Integrating OpenAthens Keystone with Amazon Cognito

Create the OpenAthens Application Record:

First set up a basic application record in the OpenAthens Service Provider Dashboard as per Quickstart for OpenAthens Keystone. You’ll need to enter a placeholder for the redirect URI to get it set up - you’ll update that later with value from Amazon Cognito.

Hop into the connection that was created and turn on the rule called ‘Shortened OIDC subject (52 characters)’ and save.

Return to the application configuration tab as you’ll need the client ID and client Secret in the next step…

In the Amazon Cognito Dashboard:

Step 1: Setup your application

1. User pools > Create user pool

2. Select the Application type (we’ll go with Traditional web application for the purposes of these instructions)

3. Provide a name (this will be for internal use only)

4. Select options for ‘Options for sign-in identifiers’ (we’ll select Email)

5. ‘Return URL’ should be set to your Relaying Party default URL

6. Create user directory

7. From Amazon Cognito > User pools > User pool ({your user pool ID})

copy the last section of the ARN value from beneath the ‘User pool information’ section and substitute the value into the Redirect URL placeholder in the Keystone configuration, modified slightly as follows:

ARN:

arn:aws:cognito-idp:eu-north-1:286652833501:userpool/eu-north-1_R4APU6vRe

Redirect URI placeholder:

https://{afterSlashLowerCaseWithoutTheUnderscore}.auth.{region}.amazoncognito.com/oauth2/idpresponse

Example Redirect URI:

https://eu-north-1r4apu6vre.auth.eu-north-1.amazoncognito.com/oauth2/idpresponse

8. Update the placeholder redirect URI application record in Keystone with the Redirect URI above and save it. Don’t forget to remove the underscore and make it lowercase.

Step 2: Setup resources for your application (App client)

1. From the Overview page, in the left-hand menu select ‘App clients’ beneath Applications

2. Click on the App client name you entered in the previous step and copy the Client ID and Client secret from the ‘App client information’ section - you’ll need to update your OpenID Connect client with these values. You’ll also need to add the issuerUri to your OpenID Connect client and this value can be obtained from the example code provided beneath the ‘Quick setup guide’ section for your App client

Step 3: Add custom attributes to the User pool

1. Add the following custom attributes beneath Authentication > Sign-up > Add custom attributes:

Name: targetedID

Type: String
not Mutable

Name: scopedAffiliation

Type: String
not Mutable

Amazon Cognito automatically prepends the word “custom” to all custom attribute names. We’ll need to map these custom attributes to OpenID Connect attributes after we setup the Identity Provider.

Step 4: Create the Identity Provider

1. Authentication Social and external providers > Add identity provider > OpenID Connect (OIDC)

2. Provide a name (The name which will be displayed to users when the login method is enabled)

3. The Client ID & Client Secret from the OpenAthens Keystone record

4. Leave ‘Authorized scopes’ as: openid

5. Leave ‘attribute request method’ as: GET

6. Select ‘Manual input’ for ‘Retrieve OIDC endpoints’ and populate the endpoints obtained from: https://connect.openathens.net/.well-known/openid-configuration

7. Ensure the following mapping are set:

custom:targetedID -> urn:oid:1.3.6.1.4.1.5923.1.1.1.10

custom:scopedAffiliation -> urn:oid:1.3.6.1.4.1.5923.1.1.1.9

(The mapping for ‘sub -> username’ won’t be visible here but that mapping will be added automatically once the Identity Provider has been added. This is a default unique user identifier within each user pool).

Step 5: Add the Identity Provider to the App client

1. App clients > {App client name}

2. ‘Login pages’ tab > Edit

3. Beneath ‘Identity providers’ click the drop-down and select the name of the App client you added in Step 4

4. > Save changes.

The Amazon Cognito integration should now be complete and ready for testing.