End user facing error messages

Occasionally things don’t go to plan and your patrons and end users may encounter errors. Some of them may be from us, whilst others come from resources or even your own systems if you use a local connector.

The first step is always to consider where the message is by looking at the URL in the address bar of the browser. If the message is from us, it will have a URL that is on the openathens.net domain.

Hopefully you’ll be able to look at the error message yourself, but sometimes all you have to go on is what the end user remembers.

Here are some of the OpenAthens error messages that might be encountered. You can search the page by name and code (ctrl+f or ⌘+f):

Sorry, access to this resource has been restricted by your organisation

Code: OA-AP-4032-01

Cause: restrictive mode and the resource being accessed not being in any permission set attached to the user’s account

Resolution: check if the user should have access or not and if they have the correct permission sets assigned

This account has been temporarily locked

Code: OA-AP-4011-10

Cause: too many incorrect password attempts.

Resolution: wait 10 minutes and try again - or reset the user’s password.

Account temporarily suspended

Code: OA-AP-4031-04

Cause: The user is trying to authenticate way more times than is reasonable. This can sometimes be a sign of a compromised account.

Resolution: Contact user and have them change their password

Too many redirects

Code: OA-AP-4031-06

Cause: the user is being sent back repeatedly by a resource. This is usually a sign of a technical problem with the resource.

Resolution: first check https://resource.status.openathens.net/ and if it’s not listed there try a test account. If that also fails, contact our service desk.

Page could not be found

Code: OA-AP-4041-01

Cause: the page on the authentication point that was requested doesn’t exist.

Resolution: If you publish a link to the password reset page, check for a typo. If you see something like test or dev in the URL, contact our service desk.

Account disabled

Code: OA-AP-4011-05

Cause: You or a colleague have manually disabled the user’s account in the admin area

Resolution: As and if the reasons for disabling the user have ended, either:

bring up their account details, clear the disabled flag and save (recommended), or
delete the account (it will be recreated fully operational the next time they sign in but without an activity history)

Access to OpenAthens has been restricted by your organisation

Code: OA-AP-4011-06

Cause: The user has matched a suspend rule you have set up on your local connector.

Resolution: If the user should have access, then either your local directory is sending the wrong details for them, or your suspend rule needs an update.

For SAML based connectors, you can see the attributes being passed to us by having the user sign in using debug mode. For LDAP connectors there is a function on the connector to read the data.

Invalid resource configuration

Code: OA-AP-4001-02

Cause: The resource has sent an invalid SAML request

Resolution: This is most likely to be seen when setting up a new 1:1 resource. Check the resource configuration has the correct details for your OpenAthens setup - see: Add and manage custom SAML resources for more help

If it’s a federation resource, check the resource status page and if there’s no mention of it there, contact our service desk.

Invalid resource configuration

Code: OA-AP-4001-07

Cause: Part of the SAML request doesn’t match up with the metadata. Specifically the Assertion Consumer Service (ACS) URL.

Resolution: If this is a 1:1 resource it may have been updated by the publisher. Open the resources details in the catalogue and check the URLs in the bottom panel. If they’re different:

If you added it via metadata URL, hit the the refresh button then recheck the URLs in the bottom panel and save.
If you added it by metadata file, get a fresh copy from the resource and look for lines starting with <AssertionConsumerService Binding. You will need to delete and then re-add the resource with the new metadata file. Stats will be unaffected as long as the name and entityID stay the same.

If it’s a federation resource, check the resource status page and if there’s no mention of it there, contact our service desk.

Account banned

Code: OA-AP-4011-07

Cause: The account activity resembles that of a compromised or shared account

Resolution: Check the account’s activity tab for details. If the account holder is innocent have them change their password.

OpenAthens access not granted

Code: OA-AP-4011-21

Cause: The user ID does not appear in your pre-mapped accounts

Resolution: If they should have access, add their ID to the pre-mapping. See: How to pre-map local accounts

OpenAthens access has been restricted by your organisation

Code: OA-AP-4011-25

Cause: The user ID does not appear in your pre-mapped accounts

Resolution: If they should have access, add their ID to the pre-mapping. See: How to pre-map local accounts

Mandatory attribute (unique user) not provided

Code: OA-AP-4011-18, OA-AP-4011-28

Cause: The expected unique user id attribute has not been sent from your directory

Resolution: This is most likely to occur whilst you’re setting up a connector. Check both ends for typos in the field and if it’s a SAML connector, use debug mode to confirm what is being sent.

Mandatory attribute (display name) not provided

Code: OA-AP-4011-27

Cause: The expected display name attribute has not been sent from your directory

Resolution: This is most likely to occur whilst you’re setting up a connector. Check both ends for typos in the field and if it’s a SAML connector, use debug mode to confirm what is being sent.

Unable to map the user to an organisation

Code: OA-AP-4011-19, OA-AP-4011-26

Cause: The user does not match any of the organisation mapping rules you have set up

Resolution: Check the user has the correct attributes in your directory and update the rules as required: See: Organisation mapping

Invalid resource configuration

Code: OA-AP-4001-04

Cause: The resource being accessed is not configured correctly. Specifically the request contents don’t match where the request was sent. This is usually only seen with 1:1 direct connections during the initial setup.

Resolution: For 1:1 SAML resources, check the configuration at both ends for typos

If it’s a federation resource, check the resource status page and if there’s no mention of it there, contact our service desk.

Invalid resource configuration

Code: OA-AP-4001-05

Cause: The resource being accessed is not configured correctly. Specifically there was no SAML request sent. This is usually only seen with 1:1 direct connections during the initial setup.

Resolution: For 1:1 SAML resources, check the configuration at both ends for typos

If it’s a federation resource, check the resource status page and if there’s no mention of it there, contact our service desk.

Invalid resource configuration

Code: OA-AP-4001-06

Cause: The resource being accessed is not configured correctly. Specifically the request was sent to an invalid single sign on URL. This is usually only seen with 1:1 direct connections during the initial setup.

Resolution: For 1:1 SAML resources, check the configuration at both ends for typos

If it’s a federation resource, check the resource status page and if there’s no mention of it there, contact our service desk.

Invalid resource configuration

Code: OA-AP-4001-08

Cause: The resource being accessed is not configured correctly. Specifically the resource isn’t in the federation metadata. This is usually only seen with 1:1 direct connections during the initial setup.

Resolution: For 1:1 SAML resources, check the configuration at both ends for typos

If it’s a federation resource, and it’s one you should be able to access, ask the user(s) to show you how they got to that point and correct them if necessary. If that doesn’t resolve things check the resource status page and if there’s no mention of it there, contact our service desk.

Unable to process SAML request

Code: OA-AP-4001-03

Cause: A request arrived, but it couldn’t be processed as SAML. This is usually only seen with 1:1 direct connections during the initial setup.

Resolution: For 1:1 SAML resources, check the configuration at both ends for typos

If it’s a federation resource, check the resource status page and if there’s no mention of it there, contact our service desk.

Your organisation is not registered in required federation

Code: OA-AP-4001-09

Cause: Your organisation is not registered in the same federation as the resource. This is very rare and requires a resource to be configured to consume the metadata of the federation you are in without being registered in it - this is usually an oversight or a delay in registering or appearing in that federation.

Resolution: You’ll need to talk to the publisher about this one

Return URL not provided

Code: OA-AP-4001-10

Cause: When using the management API to put your own OpenAthens login on your own page, you have omitted a return URL from the initial POST.

Resolution: Include a return URL that points to one of your own pages that moves the user forward, e.g. to your library portal. See: Generating authentication tokens for end-users via the API

Token not provided

Code: OA-AP-4001-12

Cause: When using the management API to put your own OpenAthens login on your own page, you have sent the user to the session initiator URL without the token.

Resolution: These tokens are not reusable so check your code is set up to use the initiator URL supplied by the initial POST. See: Generating authentication tokens for end-users via the API

Expected OpenAthens cookie not present

Code: OA-AP-4001-11

Possible causes:

Cookies being completely disabled in the browser
Hitting the browser back button after going through organisation discovery
Unexpected redirect parameter

Resolutions:

Enable cookies. 3rd party cookies are not required can be disabled
Try not to do that
Investigate where the link is and correct it.

Expected permission set not found

Code: OA-AP-4011-20

Cause: Your local connector has been set up to use a permission set specified by your directory and it’s not there.

Resolution: The set may have been deleted, but also check if there may be a typo or missing data at the directory end. This function cannot be used with organisation mapping.

Email address change has been restricted

Code: OA-AP-4031-02

Cause: You or a colleague have disabled the option for an OpenAthens account to update their email address

Resolution: If allowable, change it manually or re-enable the function for the user to do so. See: Account preferences

Cannot change email address

Code: OA-AP-4031-03

Cause: The user is trying to change their email address for an account managed by your organisation.

Resolution: Refer them to your IT support team

Unknown error

Code: OA-AP-4031-01

Cause: Unknown

Resolution: If it’s a federation resource, and it’s repeatable, check the resource status page and if there’s no mention of it there, contact our service desk.

If this is repeatable, please include the exact steps to recreate the error.