Okta Bridge Setup - REV 3.4

Overview 

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 multilateral federation-enabled SP 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”. Assign the service account “Read Only Administrator”.

 

2. As the service account user, log in and create an API token under Security->API->Tokens.
3. 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:
   
   a) If your organization has an encrypted file sharing service, Cirrus will work with you to use the service 
   
   b) Some organizations will consider commercial file sharing utilities sufficiently secure (for example Microsoft OneDrive, Google Drive, Box, or Dropbox) 
   
   c) Cirrus staff can provide a PGP public key to encrypt a file
   
   d) Cirrus staff can provide an SMS number that can be used to receive a text of password for a traditionally encrypted file (for example a password encrypted ZIP archive) 

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 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 a different attribute release from your default
Any other SP	The SP’s entityID	Creating an additional application using the InCommon SP’s entityID and the Cirrus Bridge will automatically use that Azure 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 all 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)
• Assign the app the “Cirrus” group you created earlier 
• Do not enable ”application visibility”. (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.

And select ‘Create New App.’ 

Select SAML as the Sign on method.

Name the application. For the “Default” Cirrus Bridge application, we would recommend “Cirrus Bridge - Default” and check both boxes to ‘Do not display application’. For other copies of the Cirrus Bridge application, pick names and set visibility as appropriate. 

 

Configure the SAML parameters: 

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

Step 2 - Attribute Release and Naming 

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

The majority of 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). 

Research and Scholarship Entity Category 

These suggested attributes identified 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 3 - Set NameID 

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 4 - Set Encrypted 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.

An alternative to control the Bridge’s encrypting setting is to send an operational user attribute named “cirrus.encryptAssertion” with value “true”.

Step 5 - Set Signing Response or Assertions 

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. 

An alternative to control the Bridge’s signing settings is to send cirrus.signAssertion or cirrus.signResponse 

Step 6 - 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 to be released as multi-valued. To change this setting, you will need to make a request to 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 7 - Assign App to Okta Group 

Before the configured application in Okta will be recognized by the Cirrus Bridge, it needs to be added to the group created in the “Allow Cirrus Bridge Okta API access” section. 

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 as asserted by the configured default application. 

© Copyright Cirrus Identity, Inc.