Integrating OpenAthens Keystone with Okta

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 a value Okta will generate.

Hop into the connection that was created and turn on the rule called Common EduPerson and save.

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

Within the Okta Dashboard:

Step 1: Create an Identity Provider

1. Security > Identity Providers > Add identity provider > OpenID Connect IdP

2. 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. Endpoints obtained from: https://connect.openathens.net/.well-known/openid-configuration including the Userinfo endpoint

5. Enable ‘Enable automatic linking’

6. Enable ‘Update attributes for existing users’

7. Once the Identity Providers is created, view the newly created Identity Provider and copy the redirect URI from the Summary section

8. Update the placeholder redirect URI application record in Keystone with the Redirect URI from the Summary section

Step 2: Create Mappings for the Identity Provider

1. Identity Providers > select your newly created identity provider > Actions > Edit Profile and Mappings

2. Add the following string attributes:

Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.9

Variable name: eduPersonScopedAffiliation

Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.10

Variable name: eduPersonTargetedID

Step 3. Setup Routing rules

1. Identity Providers > Routing rules

2. ‘Add Routing Rule’

3. Give the rule a name and ensure the ‘THEN’ section includes your newly created identity provider and click ‘Create rule’. If asked to activate the rule, select to Activate.

Step 4. Create an Application

1. Applications > Applications >  Create App Integration

2. For Sign-in method choose ‘OIDC – OpenID Connect’

3. For Application type choose ‘Web Application’

4. Sign-in redirect URIs should be your Relaying Party default redirect URI

5. Ensure ‘Allow everyone in your organization to access’ is selected

6. Take note of the ClientID and Client Secret as this will need to be added to your OpenID Connect Client configuration.

Step 5. Complete the mappings

User (default)

1. Profile Editor > Select User (default) profile

2. Add the following string attributes:

Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.9

Variable name: eduPersonScopedAffiliation

Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.10

Variable name: eduPersonTargetedID

Application

1. Profile Editor > Select the relevant ‘Application’ profile

2. Add the following string attributes:

Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.9

Variable name: eduPersonScopedAffiliation

Display name: urn:oid:1.3.6.1.4.1.5923.1.1.1.10

Variable name: eduPersonTargetedID

3. Profile Editor > Select the relevant ‘Application’ profile > Mappings

4. Ensure the following mappings are set for Okta User to {your Application name} (ensuring the mapping arrows are green):
   user.eduPersonTargetedID -> eduPersonTargetedID
   user.eduPersonScopedAffiliation -> eduPersonScopedAffiliation

Identity Provider

1. Profile Editor > Select ‘Mappings’ for the Identity Provider

2. Ensure the following mappings are mapped for {your Identity provider name} to Okta User:

String.append(appuser.eduPersonTargetedID, "@null.com") -> login

String.append(appuser.eduPersonTargetedID, "@null.com") -> firstName (this is just an example mapping, we’re recycling the email mapping below for convenience)

String.append(appuser.eduPersonTargetedID, "@null.com") -> lastName (this is just an example mapping, we’re recycling the email mapping below for convenience)

String.append(appuser.eduPersonTargetedID, "@null.com") -> email (this is because Okta requires an email attribute and OpenAthens Identity Providers do not release an email address attribute as standard. This should be mapped to the relevant email address attribute where available)

appuser.eduPersonTargetedID -> eduPersonTargetedID

appuser.eduPersonScopedAffiliation -> eduPersonScopedAffiliation

Step 6. Update the IdP username for the Identity Provider created in Step1

1. Identity Providers > select your created identity provider > Actions > Configure Identity Provider

2. Edit the General settings and ensure IdP username is set to: idpuser.eduPersonTargetedID

The Okta integration should now be complete and ready for testing.