Okta Bridge Setup - REV 3.4

Configuring Cirrus Bridge with Okta

REV 3.4

Table of Contents


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: 

Okta Group

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


… 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”.
Read Only Administrator


  1. As the service account user, log in and create an API token under Security->API->Tokens.
  2. 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 


Audience URI/Entity ID


Default (required)


This is the default application that will get used to authenticate users. Cirrus will provide you this URI.

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

Okta Add Application

And select ‘Create New App.’ 

Okta Create New App

Select SAML as the Sign on method.

Okta SAML 2.0

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. 

Create SAML Integration


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) 

Configure the SAML Parameters

Step 2 - Attribute Release and Naming 

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

Screen Shot 2022-08-17 at 10.55.46 AM

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 eduPersonPrincipalNameConsult 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: user.lastName Yes
Given Name (givenName) urn:oid: user.firstName Yes
Display Name (displayName) urn:oid:2.16.840.1.113730.3.1.241 user.displayName Yes
Common Name (cn) urn:oid: 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: user.login Yes, if not assigned
ePUID (eduPersonUniqueId) urn:oid: user.login  
(eduPersonScopedAffiliation) urn:oid: A custom attribute  
(eduPersonEntitlement)  urn:oid: A custom attribute  
(eduPersonAssurance) urn:oid: A custom attribute  
(eduPersonTargetedID) urn:oid: Contact Cirrus Support to configure  

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.

Set Name ID

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.

Screen Shot 2022-08-17 at 10.59.44 AM

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. 

Set Signing Response or Assertions

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. 

Assign App to Okta Group

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: 


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. 

Testing Integration

© Copyright Cirrus Identity, Inc.

Blog comments