This space contains the old OpenAthens SP documentation and is no longer maintained.
OpenAthens SP software is already out of support and will reach end of life in May 2020.

Check out OpenAthens Keystone instead. It's supercool and makes dealing with SAML much easier.

Search

Skip to end of metadata
Go to start of metadata

These instructions detail the steps involved in creating a single authentication service that can be used by one or more web applications. For customers who already have an existing OpenAthens SP implementation and are migrating to a single authentication service, the steps described here have been designed to retain your existing OpenAthens SP entity ID to maintain personalisation.

Process

Set up a website to handle authentication

  1. Create a separate website, either on the same server as your main web application, or on a separate server. This site will handle authentication
  2. If you are migrating to a single authentication service from an existing OpenAthens SP implementation and your authentication service is on the same server, you will already have the OpenAthens SP software installed, otherwise install the relevant version.
  3. Create a configuration in the SP Dashboard setting the Base URL to match the URL of the new authentication service. If you have an existing OpenAthens SP implementation registered, you will need to overwrite the pre-populated entity ID to match your existing registration
  4. If you are migrating to a single authentication service from an existing OpenAthens SP implementation and OpenAthens SP is installed on a separate server from your main web application, copy the self-signed certificate from the original server to the new server and rename it to match the domain being used for the new authentication service. If the same server is being used, copy the existing certificate to the same directory and rename the copy to match the new domain
  5. If you are not migrating to a single authentication service from an existing OpenAthens SP implementation, you will need to create a self-signed certificate and install it on your authentication server.
  6. On the new site, implement a protected page that can accept a ‘return URL’ in the query string to support deep linking (authenticated links to specific protected pages within your main application) and return an authentication handle to your main application when redirecting the user back to it 
  7. Implement authorisation code behind the protected page on the new site. If you are migrating to a single authentication service from an existing OpenAthens SP implementation, you can use the existing code from your current live web application
  8. Implement a basic API to accept the authentication handle and return an ‘authorised’ or ‘not authorised’ state to your application and any required organisation/personalisation data

Configure your main application to use the authentication service

  1. Implement a redirect for all federated logins to the protected page on the Authentication Service passing a ‘return URL’ in the query string to define where users should be returned to following successful authentication and authorisation
  2. Implement functionality within your main application to call Authentication Service API using the authentication handle and accept response to either create session for valid user or redirect user to a non-subscribers info page
  3. If you are migrating to a single authentication service from an existing OpenAthens SP implementation, you will need to remove the OpenAthens SP configuration items from the web.config of the main application

Registering metadata

  • If you are not migrating to a single authentication service from an existing OpenAthens SP implementation and you intend to offer authentication via the OpenAthens Federation, you will need to register the metadata of the authentication service in the OpenAthens Federation via the OpenAthens Federation Manager (https://fed.openathens.net).
  • If you are migrating to a single authentication service from an OpenAthens SP implementation already registered in the OpenAthens Federation, you will need to update your registration to additionally include the endpoints for the new authentication service. Contact the OpenAthens Service Desk for assistance with this step
  • If you are not migrating to a single authentication service from an existing OpenAthens SP implementation and you intend to offer authentication via the UK Access Management Federation, you will need to contact the UK Federation Help Desk and request registration of the metadata from your OpenAthens SP authentication service
  • If you are migrating to a single authentication service from an OpenAthens SP implementation already registered in the UK Access Management Federation, you will need to contact the UK Federation Help Desk and request that your OpenAthens SP entity is updated with additional endpoints for the new authentication service.

Post implementation steps

  • Once release has been completed, if you are migrating to a single authentication service from an existing OpenAthens SP implementation already registered in the OpenAthens Federation, the OpenAthens Federation metadata should be updated to remove the ‘old’ OpenAthens SP endpoints as these will no longer be required
  • Once release has been completed, if you are migrating to a single authentication service from an OpenAthens SP implementation already registered in the UK Access Management Federation, the UK Federation metadata should be updated to remove the ‘old’ OpenAthens SP endpoints as these will no longer be required

Additional considerations

If you are migrating to a single authentication service from an OpenAthens SP implementation already registered in the OpenAthens Federation and the access URL changes as part of this work, then it will need to be updated in the OpenAthens Federation Manager (http://fed.openathens.net/). This URL is used (a) to provide single click access from the MyAthens portal, and (b) by OpenAthens administrators to add links to their library intranets, VLEs, etc.  The OpenAthens generic entity id (https://idp.eduserv.org.uk/openathens) must continue to be supported in any revised access URL

Single Authentication Service Process

  1. User clicks ‘OpenAthens / UK Institution Log In’ on the main website and is redirected to the Authentication Service
  2. User selects an ‘OpenAthens’ link and is redirected to the OpenAthens authentication point, OR if the service supports authentication via a federation, user selects their IdP from a list and is redirected to their IdP
  3. Attributes are returned from IdP
  4. Authentication Service redirects user back to the main website returning an authentication handle
  5. The main website makes API call to Authentication Service using auth handle provided
  6. API responds with user authorisation status and the main application either creates session or redirects user to a non-subscribers page

 

  • No labels