Okta Bridge Setup - REV 3.5

Cirrus Conditional Access is a feature that allows the Cirrus Bridge to authenticate users against specific Okta apps based on which service provider (SP) is making the request. This can be an SP registered with InCommon or any other service provider for which Cirrus Identity has metadata.

Cirrus Conditional Access allows the customer to control attribute naming, attribute release, nameID, MFA, assertion encryption, and signing settings to meet SP requirements from within the Okta administrative portal rather than through Cirrus. It also allows taking advantage of other Okta features, such as assigning apps to specific users and taking advantage of Okta logs.

This feature is driven through the Okta API. The Cirrus Bridge communicates with Okta via the Okta API to learn about applications and send users to the correct application for authentication.

Allow Cirrus Bridge Okta API access

Create a Group for Cirrus Bridge Conditional Access Apps

The Okta apps you want Cirrus to use must be assigned to a group. The Okta API will only engage with the Okta apps assigned to the group, filtering out the applications you don’t want to use with Cirrus.

1. Add the group with the proposed suggested name:

2. Provide Cirrus with the group’s uniqueId, which can be found in the URL. For example, the uniqueid associated with the following group:

https://dev-933302-admin.oktapreview.com/admin/group/00gz4dm9srbl1TuYu0h7

… would be “00gz4dm9srbl1TuYu0h7”.

Create ‘Cirrus API’ Service Account and Token

1. To enable access by the Cirrus Bridge, create a user that will be a service account. The suggested name is “Cirrus Service”.

2. Assign the service account “Read Only Administrator”

3. As the service account user, log in and create an API token under Security->API->Tokens.

4. Securely provide Cirrus this token, along with your Okta Admin domain – do not use email to communicate the token. The Okta Admin domain will be the domain contained in the URL when you created the token (for example, dev-933302-admin.oktapreview.com). There are several options to transfer the token to Cirrus securely - the option chosen will depend on the organization’s security practices.

Configure Okta

Using the Cirrus Bridge’s conditional access features allows you to customize the login requirements, attribute release, signing and encryption settings for different application service providers.

You can add multiple applications to Okta using different Audience URIs - see the table below:

Per Application Settings

Application	Audience URI/ Entity ID	Description
Default (required)	https://<<domain>>/bridge	This is the default application that will get used to authenticate users. Cirrus will provide you with this URI.
Research and Scholarship	http://refeds.org/category/research-and-scholarship	Create an additional application with this ID URI if you want Research and Scholarship applications to have different attribute release from your default
Any other SP	The SP’s entityID	Create an additional application using the InCommon SP’s entityID and the Cirrus Bridge will automatically use that Okta application when it receives an authentication request from that SP NOTE: You should not use its certificate or sign on/acs urls

Cirrus will provide the Audience URI/Entity ID for the default once your Okta Bridge is created.

NOTE - Cirrus is looking at other ways to group applications. Contact “support@cirrusidentity.com” for more information.

Common Settings for Applications

The apps that you create in Okta will have a few values that will be the same:

Single Sign On / ACS url: https://HOSTNAME/module.php/saml/sp/saml2-acs.php/IDENTIFIER_proxy
SP Cert (used for encrypted assertions)
Assignment to the “Cirrus” group you created earlier
”Do not display application icon to users” is checked. (Not all SPs support Idp initiated logins)

Step 1 - Add Application

As an Okta Admin, add an application as you would with any other service provider. Select ‘Create App Integration.’

Select SAML as the Sign on method.

Name the application. For the “Default” Cirrus Bridge application, we recommend “Cirrus Federation Bridge - Default” and check the box to ‘Do not display application’.

NOTE - Pick names and set visibility as appropriate for other copies of the Cirrus Bridge application.

Configure the SAML parameters:

Enter the Single sign on URL provided to you by Cirrus (see “Common Settings for All Applications”)
Enter the Audience URI (SP Entity ID) provided to you by Cirrus (see “Per App Settings” table)
Pick a Name ID format of transient

Most InCommon apps want a Transient Name ID format, which should be the setting for your default bridge. Cirrus does not use the application username value for Transient Name IDs. You may specify another Name ID format or value for individual apps.

Step 2 - Set Signing Response or Assertions

This is found under the ‘Show Advanced Settings’.

Shibboleth signs responses, but not assertions, by default. Okta signs both, and the Cirrus Bridge will align its signing with what is configured in Okta.

Step 3 - Set Encrypted Settings

This is found under the ‘Show Advanced Settings’.

Shibboleth encrypts assertions by default. To enable encrypted assertions with the Cirrus Bridge, you set encrypted assertions (and upload the bridge’s public certificate) in the Okta configuration for the app.

Step 4 - Attribute Release and Naming

The attributes you configure for release in Okta will be what the Cirrus Bridge releases to downstream systems.

Most InCommon SPs want attributes to be named with their OID name. A subset will expect different names for the attributes. You may need to experiment with the correct attribute name when transitioning from Shibboleth. This is because Shibboleth sets both an attribute name and an optional friendly name, and some service providers look at both.

NOTE - the following mapping makes the general assumptions that the Okta attribute provided by user.login is scoped; and also both "long-lived" and "non re-assignable". Scoping is required for both ePPN and ePUID. Identity persistence is required for eduPersonUniqueID and recommended for eduPersonPrincipalName. Depending on customer business practices, other attributes may need to be selected or transformations may be needed. For more information, see the Cirrus Blog Picking a Good Value for an eduPersonPrincipalName. Consult with Cirrus Support if you have questions.

Below is a listing of common attributes and suggestions for mapping to Okta values based on the eduPerson schema specification (https://wiki.refeds.org/display/STAN/eduPerson).

Attribute (friendlyName)	OID	Suggested Okta Mapping	Research and Scholarship Attributes
Surname (sn)	urn:oid:2.5.4.4	user.lastName	Yes
Given Name (givenName)	urn:oid:2.5.4.42	user.firstName	Yes
Display Name (displayName)	urn:oid:2.16.840.1.113730.3.1.241	user.displayName	Yes
Common Name (cn)	urn:oid:2.5.4.3	user.displayName
Email address (mail)	urn:oid:0.9.2342.19200300.100.1.3	user.email	Yes
UID (uid)	urn:oid:0.9.2342.19200300.100.1.1	user.login
ePPN (eduPersonPrincipalName)	urn:oid:1.3.6.1.4.1.5923.1.1.1.6	user.login	Yes if not reassigned
ePUID (eduPersonUniqueId)	urn:oid:1.3.6.1.4.1.5923.1.1.1.13	user.login
(eduPersonScopedAffiliation)	urn:oid:1.3.6.1.4.1.5923.1.1.1.9	A custom attribute
(eduPersonEntitlement)	urn:oid:1.3.6.1.4.1.5923.1.1.1.7	A custom attribute
(eduPersonAssurance)	urn:oid:1.3.6.1.4.1.5923.1.1.1.11	A custom attribute
(eduPersonTargetedID)	urn:oid:1.3.6.1.4.1.5923.1.1.1.10	Contact Cirrus Support to configure

Research and Scholarship Entity Category

The suggested attributes above satisfy the Research and Scholarship Entity Category requirements (https://refeds.org/category/research-and-scholarship). To fully comply with R&S requirements, you must also signal that MFA is enforced.

Step 5 - REFEDS MFA

For InCommon SPs that require REFEDS MFA, you should define an Okta policy to require MFA for the application.

Okta can signal to the Cirrus Bridge that MFA was used if you release the “session.amr” attribute to Cirrus. To do this, in Attribute Statements (pic below) add an attribute.

The Name of the attribute should be: session.amr

The Name Format for session.amr should be: Unspecified

The Value of the attribute should be: session.amr

With session.amr attribute released in Okta, Cirrus will correctly send the REFEDS MFA context to the downstream SP.

NOTE - One common issue is Okta may be configured to release multi-valued attributes as a single, comma-separated value. For example, see below.

Cirrus needs the attribute released as multi-valued. To change this setting, you will need to request Okta support to enable SAML_SUPPORT_ARRAY_ATTRIBUTES.

Once SAML_SUPPORT_ARRAY_ATTRIBUTES is enabled, the released session.amr attribute should be configured correctly and look like this.

Step 6 - Save the App

Once you have completed steps 4 and 5, click Next. Optionally fill out the Okta support questions and then click Finish.

Step 7 - Assign App to Okta Group

The configured application in Okta needs to be added to the group created in the “Allow Cirrus Bridge Okta API access” section before it can be recognized by the Cirrus Bridge.

Testing Integration

Once the default application is configured, the test URL provided by Cirrus Identity can be used to test authentication to the Bridge. The test URL will be of the following form:

https://<<name>>.proxy.cirrusidentity.com/module.php/core/authenticate.php?as=<<name>>_proxy

Paste the test URL into a browser. If everything works, you should see a page similar to the following, showing the released attributes asserted by the configured default application.

View full post