How to use debug mode

The function or feature discussed below is experimental, and may be changed or withdrawn.

The authentication point has a debug mode that allows you to perform a couple of useful functions.

For all:

  • See exactly which attributes are being passed to a service provider, so that you can confirm how your release policy is working and test changes

For local authentication users:

  • View the attributes being passed to OpenAthens by SAML connections such as ADFS

  • View and interact with local authentication connections that are not yet marked as live, e.g. when adding a new one or migrating from an old one

Enable debug mode

You activate or deactivate debug mode by using a bookmarklet called OpenAthens SSO Debug.

Get the bookmarklet

If you don’t already have the bookmarklet, add it to your browser first.

  1. Go to our Enable SSO debug page (https://login.openathens.net/resources/static/ssodebug.html).

    Screenshot of a web page. A message reads 'Drag the following link to your bookmarks to enable or disable debug mode', followed by a link called 'OpenAthens SSO Debug'.
  2. Drag the highlighted link OpenAthens SSO Debug to your bookmarks bar.

Turn on debug mode

Before using debug mode, you must turn it on in your browser. Once turned on, debug mode will remain active either until you turn it off or until you close the browser (depending on your browser settings).

  1. Go to any page on the domain login.openathens.net. The password reset page is a convenient choice.

  2. Click the OpenAthens SSO Debug bookmarklet in your bookmarks list. A message confirms that debug mode is now turned on.

  3. Forgotten password page, with an overlay that shows the message 'SSO debug enabled' and an 'OK' button.

    Press OK to dismiss the message.

To turn off debug mode, repeat this process. Clicking the OpenAthens SSO Debug bookmarklet while debug mode is turned on will disable debug mode.

View debugging output

With debug mode turned on in your browser, access the resource you want to check. The debug tool interrupts the transfer to show you details of the attributes being released. You can then choose whether or not to continue to the resource.

Table of attributes. Each attribute is shown with its name and value. Above the table, advisory text reads 'The attributes shown below will be set to (an example URL)'. There are buttons labeled 'Sign out' and 'Proceed to service'.

The Attributes tab shows attributes as a table. To view the data as SAML, go to the SAML tab.

Local connections view

If you have multiple local connections and none of them is set as the default, the authentication point will display available connectors in an overlay (including any not marked as live or visible). If you select a SAML based connector, debug mode will show you which attributes the connector is sending to OpenAthens.

To see the available connections, you first need to search for your organisation at the authentication point, use a WAYFless URL or access a resource.

Page headed 'Choose how to sign in'. It shows the options 'Student login - for full time students', 'Staff login - faculty and support colleagues', and 'Guest users (OpenAthens account)'.

Anything to watch out for?

With local connectors, debug mode can show only incoming attributes from SAML based sources, not things like the API or LDAP.

If you have only one local connection and it is LDAP or SirsiDynix, you will not see the overlay because these connection types can accept OpenAthens accounts. You will only be able to tell the difference if you modify the username and password labels on the login page tab of the connection.

If you do this while accessing a resource, you will interrupt a time-stamped SAML response. If you do not proceed to the resource within a minute, access is likely to fail.

If the request and response use SAML 2, the key attributes are passed using the format urn:oid format. In this format, each attribute is distinguished by the last number in its name, for example:

Name

Passes

May have been previously known as

urn:oid:1.3.6.1.4.1.5923.1.1.1.1

Role (e.g. member, staff, student)

eduPersonScopedAffiliation / Scoped Affiliation / Affiliation

urn:oid:1.3.6.1.4.1.5923.1.1.1.7

Entitlement values

eduPersonEntitlement / Entitlement

urn:oid:1.3.6.1.4.1.5923.1.1.1.10

The targeted ID value

eduPersonTargetedID / Targeted ID

The older urn:mace format should be seen only if a service provider makes a SAML 1 request.

If debug mode is active when you sign in to the Compass admin area, it will also output details of that login. However, you are unlikely to need this information.

Testing other connectors when you have a default connector

If you have a local connector marked as default, debug mode will not show you other connector options. This presents a challenge if you want to change from one default connector to another - for example if moving from ADFS to Azure - as it may seem impossible to test the new connector.

Luckily it is possible to specify a connector in the URL when debug mode is active. Use a URL in this format:

https://login.openathens.net/auth/<API_NAME>/o/<NUMERIC_ORG_ID>?t=<PERCENT_ENCODED_URL>&ctx=sd&l=<CONNECTOR_ID>

Replace the placeholder variables in the URL with the appropriate values, according to the following table. Ask your IT team if you need help.

<API_NAME>

Usually the same as your scope, e.g. organisation.org. Read it from the first line of the table on your organisation summary page

<NUMERIC_ORG_ID>

The unique ID number on the same line as your scope on the organisation summary page 

<PERCENT_ENCODED_URL>

Since what you need to test is getting data from your local source into OpenAthens, this does not need to be a resource or anything complicated. Any web page will do as long as you percent encode the URL (sometimes called URL encoding). For example: https%3A%2F%2Fwww.openathens.net

<CONNECTOR_ID>

This is visible in the URL when you select the connection in the admin area, e.g.:
https://admin.openathens.net/#Connections:id=123456
   or if it's a newer one:
https://admin.openathens.net/#Connections:id=3bd8f312-d0d4-4dee-8f7d-583bee57feca