This guide outlines the configuration of an Okta Custom SAML App to accept authentication requests from an AAF Rapid Identity Provider (Rapid IdP) instance. In this mode of operation, the Rapid IdP service provides access to federation enabled services and proxies all user authentication requests to an organisation's Okta Authentication Service.

The article is specific to connecting to the Okta Authentication Service, as a discrete task during one of the following activities:

deployment of a new Rapid IdP instance
migrating an existing identity provider to the Rapid IdP service
converting an existing Rapid IdP service from LDAP authentication to a cloud based authentication service.

These activities follow a similar pattern and are outlined in the article On-premise IdP Migration to Rapid IdP.

This guide is one in a series for connecting and proxying cloud based authentication to AAF's Rapid IdP Service. These guides will eventually cover Google, Okta and Azure AD.

The AAF will provide the necessary information to start the configuration of the Okta Custom SAML App. The AAF will need to receive the Okta Custom SAML App metadata and certificate to complete the configuration of the Rapid IdP service.

In proxying authentication requests to a third-party authentication service like Okta, Rapid IdP no longer requires access to an organisation's on-premise LDAP service for authentication or to source user attribute values. However, the necessary user attribute values must be available within the authentication service for Rapid IdP to retrieve and release user attributes to those federation connected services to which users authenticate.

If there is no configuration item to input the AAF provided signing certificate within the Okta Administrative Console, it can be safely ignored. This means user information is not encrypted within the SAML response, but the user’s data is still sent over an encrypted transport session.

These instructions were derived from the following Okta Support document

https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_SAML.htm

https://support.okta.com/help/s/article/How-to-define-and-configure-a-custom-SAML-attribute-statement

Before starting configuration of the Okta Custom SAML App, the AAF will provide the following configuration information:

the Single Sign On URL - also known as ACS (Assertion Consumer Service). Use this value for Recipient URL and Destination URL if necessary
an Audience URI - which exactly matches the Shibboleth IdP EntityID if migrating an existing service
a list of SAML attribute names that Rapid IdP is expecting - attribute names are case-sensitive
a certificate for signing assertions - if the Okta Console allows the import of an external certificate.

Step 1 - Sign in to the Okta Admin Console

Sign in to the Okta Tenant Admin Console with a suitable admin account and select Applications > Applications. Click Create App Integration and select SAML 2.0 as the sign-on method.

Step 2 - Configure General Settings

Assign an App name such as Rapid IdP-Prod or if connecting to the Test Federation and AAF’s Rapid IdP Test service use a value like Rapid IdP-Test.

Step 3 - Configure the SAML Settings

SAML2 integration configuration requires the combination of information from both your organisation and the AAF. For help completing each field, use your app-specific documentation and the Okta Dashboard tool tips.

Add the value for the Single sign-on URL (ACS). This is the default Assertion Consumer Services (ACS) URL value. This same value is used for Recipient URL and Destination URL values.
Select the checkbox to use the same value for Recipient URL and Destination URL.
Set the Audience URI (Audience Restriction or Service Provider (SP) Entity ID).
Default RelayState: Leave blank
Add Attribute Statement for the attributes requested by the AAF. For each Statement define these three items:
- Define Name: using the list of case-sensitive attribute names provided by the AAF
- Set Name Format to be Basic
- Set Value for the attribute defined by the Name element. Okta Admins can create custom expressions (using Okta Expression Language) to reference values from the Okta user profile. The maximum length for this field is 1024 characters.
When the option appears, enable Forced Authentication

Missing attributes should be added to Okta and populated with the necessary user values. Attribute names are case-sensitive, administrators need to ensure that claim names match the AAF provided attribute names.

An example Okta Attribute Statement view with AAF attribute names on the left side. The AAF will advise on the attribute AAF names.

Consult the Okta Documentation for any other steps to complete the mapping of Okta attributes to Rapid IdP attributes.

Unrelated or superfluous claims should be removed.

Federation Attributes

Complete documentation on AAF Attributes is available here: https://validator.aaf.edu.au/documentation.

AAF Core Attributes are the standard vocabulary for the federation and the higher education and research sector.

To assist with mapping Okta values to AAF attributes, explore the AAF attribute definitions to gain an understanding of their purpose and usage. The selection of Okta attributes should be such that they align closely to the AAF attribute descriptions. Organisations are only required to support the attributes in the core list.

The following attributes are consumed without modification:

mail
givenName
surname
displayName (this can be a direct mapping to an existing Okta attribute or Rapid IdP can generate the value by combining firstName and Surname values)
eduPersonAffiliation - can be defined statically within Rapid IdP, if all users have the same affiliation status within an organisation
eduPersonEntitlement (if not available, may be defined statically within Rapid IdP).

The following attributes are generated by the Rapid IdP service from a single persistent, non-reassignable, unique identifier provided by an organisation:

auEduPersonSharedToken
eduPersonTargetedID
persistentNameID

Sources of persistent, non-reassignable, unique (for an organisation) identifiers commonly include: employeeID, studentID, unix uidnumber or other identity management system internal identifier that is sticky to the individual throughout their entire identity lifecycle with an organisation, including when an individual returns to an organisation after any period of time away. 

When there is no suitable attribute, the AAF will make recommendations, on a case-by-case basis in consultation with an organisation, for deploying an immutable identifier for every user. Unique values, for this identifier, will need to be available for every user. The process of adding values for this attribute should become part of an organisation's identity creation process and documented accordingly.

The following attributes are generated by the Rapid IdP service based on the available values for other identifiers mapped to the Okta SAML App attributes:

eduPersonPrincipalName (combines uid or a suitable immutable identifier and homeOrganization)
eduPersonScopedAffiliation (combines eduPersonAffiliation and homeOrganization)

The following attributes are generated by the Rapid IdP service at the time of user authentication:

authenticationMethod
eduPersonAssurance

The following attributes are defined statically:

homeOrganization (the organisation's security domain, ie: example.edu.au)
homeOrganizationType
‘O’ - aka: organizationName.

Step 4 - Select I'm an Okta customer adding an internal app

On the last page select I’m an Okta customer adding an internal app and click Finish.

The settings page for the AAF Rapid IdP integration appears and the configuration should be modifiable. Make sure that the SAML App is available to users and/or groups.

Step 5 - Manage Signing Certificates

After creating and configuring the SAML app integration, the SAML Signing Certificates section appears on the Sign On tab. You must configure your app integration to verify signed SAML assertions for SSO and trust Okta as the Identity Provider.

You may see two certificates available. If so, notice that one is active and one is inactive. The active certificate is scoped only for your app integration, while the inactive one is scoped for your entire org. Okta recommends keeping the app-only certificate active. Optionally, you can generate and activate a new certificate.

Perform the following steps to obtain the necessary settings to provide (to the AAF) for your SAML app:

Set the Status for the certificate you want to be Active.
If it is not active, select Activate in the Actions menu for another certificate, or click Generate new certificate and activate the new certificate.
Your SSO configuration isn't complete until you perform the following steps.
Under SAML Setup, click View SAML setup instructions.
Depending on your application, either:
- Copy the IdP settings and download the certificate, OR
- Copy all the IdP metadata if your application can consume it

Confirm that the signing certificate is long lived, before providing the certificate to the AAF.

Provide the Okta IdP settings and certificate or the Okta Idp metadata to the AAF. The AAF will use this information to complete configuration of the AAF Rapid IdP service.

Step 6 - Enabled for all users

Ensure that the Okta Custom SAML App is enabled for all users who should receive access.

Step 7 - Testing

Testing ideally requires a service to receive the login token. Once the AAF has received the Okta metadata and configured the Rapid IdP instance, testing can occur against the AAF’s Validator Service at https://validator.test.aaf.edu.au for the AAF's Test Federation or https://validator.aaf.edu.au for the AAF's Production Federation. These services will display all the released attributes for an individual.

Addition testing can occur against existing services - The AAF will outline the steps to complete testing.