This guide outlines the configuration of an Okta Custom SAML App to accept authentication requests from an AAF 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 AzureAD.


The AAF will provide the necessary details to start the configuration of the Okta Custom SAML App. The AAF will need to receive the Okta Custom SAML App metadata, certificate and settings 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 third-party 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 sent over an encrypted transport session.


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

  • 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.


There might exist an item called Configure SAML 2.0 for Australian Access Federation. Do NOT choose this option and instead select the creation of a Custom SAML App. 

The Configure SAML 2.0 for Australian Access Federation option is a superseded configuration which is not supported for integration with AAF Rapid Idp.


Step 2 - Configure General Settings


In this step, assign an App name such as AAF Rapid IdP Prod or if connecting to the Test Federation and AAF’s Rapid IdP  Test service use a value like AAF Rapid IdP Test.

Step 3 - Configure the SAML Settings

A SAML 2.0 configuration requires a combination of information from both your organisation and the AAF. For help completing each field, use your app-specific documentation and the Okta 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


An example Okta Attribute Statement view


Consult the Okta Documentation for any other steps to complete the statements mapping Okta attributes to Rapid IdP 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 or Rapid IdP can generate the value by combining firstName and Surname values

  • eduPersonAffiliation - can be defined statically by 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 identifiers commonly include: employeeID or other identity management system internal identifier. Another source attribute may be suitable if it is persistent and non-reassignable and unique for an organisation. 

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 account creation procedure 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 (combining on uid or a suitable immutable identifier and scope )

  • eduPersonScopedAffiliation (combining on 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

  • 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:

  1. 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.

  2. Under SAML Setup, click View SAML setup instructions.

  3. 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


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.


Links

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?language=en_US

AAF Test Validator https://validator.test.aaf.edu.au/

AAF Production Validator https://validator.aaf.edu.au/