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 should review our best practices and technical recommendations first.

Pre-checks to perform before submitting to OpenAthens for publication

Organization discovery (WAYF, or Where are you from)

• There must be a method of signing in on the website via federated access. This should be labeled “institutional login”.

  1. Should be available on the homepage

  2. Should be available on content pages

  3. Should not mention specific software or technology, e.g. Shibboleth/OpenAthens.

  4. Should not ask user to select the federation or region their organization is from.

  5. If using your own organization discovery service, it should allow organization name search alongside any other methods such as email address.

Examples:

Authentication / authorization check

• Can you sign in to your application using your test OpenAthens credentials (Configuring your OpenAthens IdP for testing)?

  1. If successful

     1. user should be able to tell that they are signed in, e.g. “Access provided by {organizationName}”

     2. the login button should no longer be displayed, or is replaced by a logout button (or equivalent)

  2. If unsuccessful

     1. user must be informed in some way that access has been denied, e.g. “You have successfully logged in but your organization does not have a subscription. Please contact your organization's administrator.”

     2. user should be guided towards who they should contact, e.g. “You have successfully logged in but your organization does not have a subscription. Please contact your organization's administrator.”

• Can you grant/limit access to match your differing subscription/license terms, e.g. concurrent users, a specific department within an organization, partner organizations such as overseas campuses?

WAYFless linking

A method of bypassing the Where Are You From / organization discovery step by including an organization identifier in the URL. This identifier must be the organization'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 recognized subscriber

Deep-linking

• Directly from a deeper page within your application (i.e. not your homepage), go through the organization discovery process and sign in via your test IdP. You should be returned to the specific page where you started the login process.

  • e.g.

• 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

Personalization

• If you provide personalization, e.g. bookshelves, favorites, watch lists, or 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. While federation customers will be able to send targetedID, they are changing to Pairwise-ID. 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 organization. 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 personalization

  • If you provide a registration form, or require PII, some organizations 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 organizations

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:

1. Within your Keystone connection - turn on the switch for OpenAthens test identity providers.

   1. Leave the switch for live identity providers off.

   2. Save the connection.

2. 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:

No other test organizations 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 organizations 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 authorization once you are live.

Review customer-facing resource information shown to OpenAthens customers

Check all the information for your application within the Service Provider 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 organization 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 Service Provider 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 - see Launching to our mutual customers

• 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.