Getting production ready with Keystone
This page covers the tests your application needs to pass before publication in the OpenAthens Federation. The goal is not to tick boxes, but to make sure that our mutual customers get the best experience from us both. This includes being able to link seamlessly to your content from other applications. This can include content discovery services and user portals.
You shoujld review our best practices and technical recommendations first.
Pre-checks you should perform before submitting to OpenAthens for publication
Organisation discovery (WAYF, or Where are you from)
- There must be a method of signing in on the website via federated access, this should be labelled institutional login.
- Should be available on the homepage
- Should be available on content pages
- Should not mention specific software or technology e.g. Shibboleth/OpenAthens.
- Should not ask user to select the federation or region their organisation is from.
- If using your own organisation discovery service, it should allow organisation name search alongside any other methods such as email address.
Authentication / authorisation check
Can you sign in to your application using your test OpenAthens credentials (Configuring your OpenAthens IdP for testing)
If successful
user should be able to tell that they are signed in e.g. “Access provided by {organisationName}”
the sign-in button should no longer be displayed, or is replaced by a sign-out button (or equivalent)
If unsuccessful
user must be informed in some way that access has been denied access e.g. “You have successfully signed-in but your organisation does not have a subscription. Please contact your organisation's administrator”.
user should be guided towards who they should contact e.g. “You have successfully signed-in but your organisation does not have a subscription. Please contact your organisation's administrator”
Can you grant/limit access to match your differing subscription/license terms e.g. Concurrent users, a specific department within an organisation, partner organisations such as overseas campuses.
WAYFless linking
A method of bypassing the Where Are You From / organisation discovery step by including an organisation identifier in the URL. This identifier must be the organisation's entityID.
Must have a WAYFless link syntax that contains the identity provider’s entityID such as
https://auth.example.com/wayfless?entity={entityID}
e.g.
https://auth.example.com/wayfless?entity=https://idp.example.edu/entity
When not already logged in to OpenAthens you should see that you are redirected to your test OpenAthens IdP for authentication
after signing in, you are returned to the homepage as a recognised subscriber
Deep-linking
Directly from a deeper page within your application (i.e. not your homepage), go through the organisation discovery process and sign in via your test IdP. You should be returned to the specific page where you started the login process.
Via a WAYFless link. Example syntax:
https://auth.example.com/wayfless?entity={entityID}&target={contentURL}
e.g.
https://auth.example.com/wayfless?entity=https://idp.example.edu/entity&target=https://example.com/some/webpage
Personalisation
If you provide personalisation, e.g. bookshelves, favourites, watch lists, CPD (Continual Professional Development) credits, any such ‘profiles’ should be linked to the unique user identifier(s) you support via single sign-on.
You should allow some flexibility on what attributes you need for the user identifier. Whilst federation customers will be able to send targetedID, they are changing to Pairwise-ID and if you intend to support 1:1 connections the customer might not be able to send either.
We recommend building support for at least urn:oid:1.3.6.1.4.1.5923.1.1.1.10 (eduPersonTargetedID), and urn:oasis:names:tc:SAML:attribute:pairwise-id (Pairwise-ID) as a minimum for federation users.
Profile provisioning - you should consider the provisioning options you support and whether they may be configurable per organisation. Things to consider:
Personally Identifiable Information (PII) should not be required
Auto-provisioning of new profiles
Whether a user needs to self-register
registering should be optional
not registering should still allow access to content
continuing without registering personally identifiable information should still allow personalisation
If you provide a registration form, or require PII, some organisations may request you to disable this for all of their users
Logout functionality
If you provide a logout function, it must not automatically log the user out of their single sign on system. It may offer the user the choice to do so.
Preparation before submitting to OpenAthens for testing and publication
Enable access to our test organisations
In order for us to run our tests we will need access to one or more parts of your application. This could be an individual product, package or area - basically enough access to test your application and compare the experiences when trying to access content we do and do not have access to.
Access will need to be enabled in two areas:
Within your Keystone connection - turn on the switch for OpenAthens test identity providers.
Leave the switch for live identity providers off.
Save the connection.
Within your application: You will need to enable access within your subscription / entitlement / access control system etc. The details for our test identity provider are as follows:
Organisation name | Entity ID | Scope |
---|---|---|
University of OpenAthens |
|
|
University of OpenAthens - Specialist School |
|
|
No other test organisations should have access enabled, and users should, therefore, be refused and presented with a helpful message indicating that they do not have access. These other test organisations will have the same entityID but a different scope.
The application must be able to accept multiple eduPersonScopedAffiliation
attributes e.g. member@ps.openathens.net
and staff@ps.openathens.net
.
You can remove this authorisation once you are live.
Review customer-facing resource information shown to OpenAthens customers
Check all the information for your application within the SP dashboard is production ready
Details tab
The name, description, logo, and banner should all be approved by your marketing or product management team. See: What makes a good resource description
You should have a general access URL that will authenticate users via OpenAthens. See: Access URLs
Linking tab
Add all relevant WAYFless/Deep-linking syntaxes and the associated service domains for generating customer-specific login links to your application. See: WAYFless access and deep linking in OpenAthens Keystone
Discovery
An organisation discovery service has been configured to allow users to sign in to your application when navigating directly to your site e.g. from a search engine.
Attributes
You have added all required and optional attribute information
IdP support
You have included details on your preferred method of contact for enabling access to your product
Check all the information for your connection within the SP dashboard is production ready
SAML Connector
Ensure your EntityID contains a domain name that you own or have permission to use and reflects what you want to see in production i.e. do not reference environments.
Ensure you have added your appropriate privacy policy link(s).
Submit a publication request
If you have an implementation ticket with OpenAthens, update it to request that we test and publish your application within the OpenAthens Federation
If you do not yet have an implementation ticket, please raise one via support.openathens.net... and request that we test and publish your application within the OpenAthens Federation
If testing runs smoothly, this shouldn’t take long, but it's not the only consideration. You should allow time for:
- Mitigation, if testing finds any problems
- Customer communication
- Customers making required updates at their end
If your go-live date is aspirational, let us know what you're hoping for as soon as you can.
If your go-live date is fixed, we suggest being ready for testing about 4 weeks ahead.