Page tree
Skip to end of metadata
Go to start of metadata

This page should take you from the creation of an application record through to being able to test. It will link off to other areas of the documentation for more detail where necessary.

Prerequisites

  • OpenAthens admin credentials
  • An OpenAthens personal account to test with. To make one, log in at admin.openathens.net, click the big add account button and complete the wizard (this should send you an email).

Method

Create the application record

  1. Access the OpenAthens publisher dashboard at https://sp.openathens.net.

  2. Create a new application by either:

    1. Clicking the green button at the top of the dashboard, or

    2. Entering the applications list from the menu on the left and clicking the green button at the top of the page.

  3. From the modal box, select OpenID Connect and then the configure button.



  4. Fill in the three fields

    1. Name: This can be changed later. It would ultimately be the name of your resource we present to our mutual customers, but for now it only needs to make sense to you for identifying the application and connection in the interface.

    2. Application URL: This is the DNS address of your application without any path - e.g. http://www.yourdomain.com.

    3. Redirect URL: This is where in your application the user is returned by OpenAthens. It is specified without any parameters you might use for things such as the eventual target page. Your OIDC plug-in or framework will usually be able to tell you the path for this (some allow you to specify it), but if you are unsure you can leave it as the default and update it later when you get an invalid redirect URL error during your first test. 

  5. Leave the connect option as a new connection and hit the create application button (for more about connections, see: Using a connection for multiple OIDC applications)

  6. This will now create the application record and connection that will be used and display the three key pieces of information that you will need to configure your OpenID Connect software. You can look these up at any time via the application record.

Configure your OpenID Connect software

This part is where we have to leave you to your own devices to an extent since installing or updating an OpenID Connect framework or plug-in in your code and setting up your pages to invoke it is, by its very nature, somewhat bespoke. We have provided some examples using various frameworks for reference though, and there is also information on best practices for interacting with federated users.

There are at least three items you will need to specify in your OIDC software's configuration and depending on your software you may need to specify more. Here are all the things you might need:

ItemAKATypical valueNotes
Client ID
yourdomain.com.oidc-app-v1.cabwe529-c743-45b8-b6ce-acab92f3f156
Always necessary. Copy from the application record's configuration tab
Client SecretSecret Key, Client Key
aFaKEUP4Uu9o32SqcPk1Pxkdohu
Always necessary. Copy from the application record's configuration tab
Provider URI
https://connect.openathens.net

Many clients need only this to configure everything else as the protocol includes a standard path for further data (e.g: http://connect.openathens.net/.well-known/openid-configuration)

If it does not ask for this, it probably asks for separate login, userinfo and token endpoints. 





Login endpointLogin URI
https://connect.openathens.net/oidc/auth
Where the user is directed to be authenticated
Userinfo endpointUserInfo URI
https://connect.openathens.net/oidc/userinfo
Where the user's attributes can be read from
Token validation endpointToken URI
https://connect.openathens.net/oidc/token
Where the software checks that the token returned via the user's browser is valid. The software has 10 minutes to check this. Should not be used as a way of maintaining a session.
JWKS endpointJWKS URI,
https://connect.openathens.net/oidc/jwks
For JSON Web Keys
OpenID ScopeScope
openid

The OpenID scope represents a collection of OpenID claims. The only one you need to specify for OpenAthens Cloud if your client asks for it is 'openid'.

The word 'Scope' has a different meaning in SAML federations (it is an organisation identifier), but more on that later.

The supported token endpoint authentication methods are client_secret_post and client_secret_basic 

Mapping rules and testing

If you get an invalid redirect URL message on your first test, you just need to extract the redirect URL from the web address of the error message (specifically the redirect_uri parameter) and update the application record (applications menu > my app name > configuration tab) with this value. This may have been expected if you were unsure about what to enter when you first created the application record)

At the moment you have a situation where, if you invoke the login, you will get transferred to OpenAthens where you can enter your OpenAthens personal account credentials and then get sent back to your application. Various claims are returned, but only one is potentially relevant to authorisation of an end user and then only if you never need to tell the different parts of a consortium apart (the realmName contains the SAML entityID of the user's home organisation, but all OUs of that organisation share that ID).

Mapping rules are the part that lets OpenID Connect work with SAML federations because it converts the attributes sent by the SAML IdP within the federation to the claims your OpenID Connect client can consume and make available to your application for authorising and/or mapping users. These SAML attributes will contain the persistent user identifiers and organisation identifiers you need. It's a bit more complicated than that of course, but that is the essence.

If you have so far just set up a basic page that perhaps displays the claims that have been received, the next step is to turn on the default rules and see what they do:

  1. Access the publisher dashboard again (https://sp.openathens.net)

  2. Go to: Connections > your connection name



  3. Toggle the EduPerson rule to on.

  4. Save.

If you return to your page and re-authenticate you should now see that more attributes have been mapped.

The Standard OpenAthens rule should, in most cases, be left off - it is only of use to aid you in migrating from an older OpenAthens system. It must not be used for authorisation as it will not be available in other federations and is being phased out in the OpenAthens federation.

The EduPerson rule will usually be useful as it will translate all the EduPerson attributes that might be sent by a federated provider. Providers outside of a federation such as ADFS or Ping will not send these and will need their own mappings. The rules will not interfere with each other and can map multiple source attributes to the same claim.

The important mappings in the EduPerson rule are listed here, and there is also a full list of eduPerson attributes available.

SAML attributeWhat is it?Typical value where relevantClaim
urn:oid:1.3.6.1.4.1.5923.1.1.1.7

The 'Entitlement' value for a user. This one is technically in common usage, but few service providers ask for it.

Is used to do more granular groupings than roles - e.g. if a library service could not afford to buy access for all 20,000 students, but could for the 150 Geology staff and students, they could pass you an entitlement value for just the geologists, and you can make a sale.

You define the value that you want them to pass for the group of users.

geology
eduPersonEntitlement
urn:oid:1.3.6.1.4.1.5923.1.1.1.9

The 'scopedAffiliation' of the user. A two part identifier consisting of a role and a federation_scope. This attribute may be multi-valued so if using any part of this for authorisation the condition should be inclusive rather than exclusive. This is generally released by default for any user in any federation.

Role values are defined by the federation. Most federations are academic, so roles are typically one or more of: member, staff, student, faculty, alum, library-walk-in, affiliate, employee.

The federation scope is the organisation identifier and can identify sub-organisations too - e.g. a group of hospitals might have a root federation scope of eng.nhs.uk, but an individual hospital might have the scope of holbycity.eng.nhs.uk. This facilitates activities such as selling access to the whole group by authorising on *.eng.nhs.uk, or supplying specific OUs in the group.

It is this the claim(s) based on this attribute that is it best to base authorisation on.

member@organisation.org
eduPersonScopedAffiliation
urn:oid:1.3.6.1.4.1.5923.1.1.1.10

The 'targetedID' of the user. An opaque user ID that is provided by default for any OpenAthens federation user, and is in general use in all major federations.

It is persistent for a user so long as federation entityIDs do not change.

3d6qquvckr9vcauasrp3g13rur eduPersonTargetedID

If you need any other data from a federation identity provider, you would need to arrange that with them on a case by case basis. You will find though that in general they will be reluctant to release personally identifiable information to you without a good reason and you should bear that in mind when setting up your app.

If those names are inconvenient or your application is already set up to authorise on an existing claim, you can set up your own mapping rules. There are two types of rule you can set up and both are very flexible.

Simple mapping rules

As you would imagine, these allow you to specify an incoming and outgoing attribute name. They can also modify both the name and value using regular expressions - e.g:

TypeIncomingOutgoingNotes
NameemailAddressemailchanges the attribute name emailAddress to the claim name email
Name

((?:.(?!\/))+$)

mynamespace$1

Strips everything before the final slash in a name and replaces it with mynamespace - e.g.

changes blah/blah/role to mynamespace/role

Value.*@(.*)$1Removes all but the domain part of an eduPersonScopedAffiliation value
Value
(.*)@.*
$1
Removes all but the role from an eduPersonScopedAffiliation value

For more information see: Mapping SAML attributes to OIDC claims

Javascript mapping rule

There may come a time when the simple rules cannot provide the mappings that you need, either because the transformation is too complicated for a regular expression, or because a very large number of simple rules are required. In such a situation you can create a rule using Javascript. There are limitations in execution time, and you can only have one but it affords the opportunity to do things with a script that would not otherwise be possible.

For more information see: Mapping SAML attributes to ODIC claims with Javascript

Testing

So far you have logged in with one OpenAthens account. You can create more accounts with different properties and see what effects they have on your test application.

For how, see: OpenAthens test accounts


  • No labels