Overview
Cirrus Conditional Access is a feature that allows the Cirrus Bridge to authenticate users against specific Azure AD (AAD) 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 that Cirrus Identity has metadata for. Cirrus Conditional Access does depend on an AAD Premium License.
Conditional Access is different from legacy SAML access in that Cirrus Conditional Access uses the MS Graph API to read configuration settings in the Azure Portal. This allows the customer to control attribute naming, attribute release, nameID, MFA, assertion encryption, and signing settings for SPs from within the Azure Portal, rather than through Cirrus. It also allows taking advantage of other AAD features, such as assigning apps to specific users and taking AAD conditional access.
This feature is driven through the AAD API. The Cirrus Bridge will communicate with AAD to learn about the applications and send users to the correct one for authentication.
Allow Cirrus Bridge Azure API Access
NOTE: You must be a Global Administrator in Azure Active Directory to configure the Azure Bridge.
Cirrus’s Bridge uses Azure’s APIs to look up which Azure applications to use for authenticating users. To do this, Cirrus will need your Azure AD tenant ID and read-only access to your configured Azure applications.
Provide Cirrus your Azure AD tenant ID
How to find your Azure AD tenant ID:
1. Sign in to the Azure portal.
2. Select Azure Active Directory.
3. Select Properties.
4. Scroll down to the Tenant ID field. Your tenant ID will be in the box.
From: learn.Microsoft.com
You can grant Cirrus read-only access to your configured Azure applications by having an Azure admin visit this URL. $TENANT_ID should be replaced with your tenant ID.
Using the Cirrus Bridge’s conditional access features allows you to customize the login requirements, attribute release, signing and encryption settings for different InCommon applications.
You can add multiple applications to Azure AD using different Identifier URI/Entity IDs - see table below:
|
Application |
Identifier URI/Entity ID |
Description |
User Visible |
|
Default (required) |
https://<<domain>>/bridge |
This is the default Azure application that will get used to authenticate users to InCommon. Cirrus will provide you with the Application ID URI. The default bridge can be tested by visiting https://<<name>>.proxy.cirrusidentity.com/module.php/core/authenticate.php?as<<name>>_proxy |
No |
|
Research and Scholarship |
http://refeds.org/category/research-and-scholarship |
Create an additional Azure application with this ID URI if you want Research and Scholarship applications to have different attribute release from your default |
No |
|
A specific SP |
The SP’s entityID |
Create an additional Azure 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 |
Yes (must enable a default application URI) |
|
Groups of SPs with common requirements |
The SP entityIDs |
Azure allows you to add multiple |
Supported |
Cirrus will provide you with the Identifier URI/Entity ID for the default once your Azure Bridge is created.
All applications created in Azure will use the values below. Cirrus will provide you with these values once your Azure Bridge is provisioned by Cirrus Engineering.
Redirect URI / Reply URL:
https://<<name>>.proxy.cirrusidentity.com/module.php/saml/sp/saml2-acs.php/<<name>>_proxy
SP Encryption Cert (if using encrypted assertions or logout - refer Step 4 below):
https://<<name>>.proxy.cirrusidentity.com/module.php/saml/idp/certs.php/idp.crt
Log into the Azure portal https://portal.azure.com/ and manage your Azure Active Directory instance. Pick the directory you want to integrate, click the “Enterprise applications” tab and then click “New application”.
In the search box, search for “Cirrus Identity” and select the “Cirrus Identity Bridge for Azure AD” gallery app.
Provide a name for your application. For the default application, we recommend “Cirrus Federation Bridge”. For other InCommon applications, we suggest looking up the service provider by entity ID in the Metadata Explorer Tool and using the displayName.
For visible apps (Azure’s default) the name will be visible to users when they visit https://myapps.microsoft.com to launch applications.
Click the “Create” button at the bottom when complete.
You should be taken to the overview page for the new application. Select “Single sign-on” from the left menu and then click on the “SAML” tile.
You should be taken to the “Set up Single Sign-On with SAML - Preview” panel. Click on the pencil in the first step to add the “Entity ID” and “Reply URL”.
A dialog will be presented. Fill in the “Identifier (Entity ID)” and “Reply URL…” fields. Reply URL is the same for all applications. Entity ID will depend on which application you are creating (see table under “Per Application Settings”).
Cirrus will provide you with the “Identifier (Entity ID)” and “Reply URL…” values.
Ensure the reply URL and the Identifier/EntityID are marked as default.
Click “Save” when done.
After returning to the “Set up Single Sign-On with SAML - Preview” panel, scroll down to Step 2, “User Attributes & Claims” and click edit.
From here you can add new claims, set NameID, claim groups, and manage Claims (by clicking the claim).
NameID
To configure a non-transient NameID click “Unique User Identifier (Name ID)” and pick the NameID format and value to use. Azure AD does allow for configuring a transient NameID. To use a transient NameID (recommended for the default and R & S application), add a user attribute claim with the name “cirrus.nameIdFormat” and value "urn:oasis:names:tc:SAML:2.0:nameid-format:transient". See picture below.
Attributes
You can configure the attributes to be released and the names of those attributes. Azure AD also allows you to perform transformations to your attributes. The majority of InCommon SPs want attributes to be named with their OID name. A subset will expect different names for the attributes.
When you add the Cirrus Identity Bridge for Azure AD from the Azure AD gallery, the application is preconfigured to release with the following claims.
You will need to edit these claims to change the Name to their OID Name and remove the Namespace. For example, here is one of the Claims pre-loaded from the gallery application.
We suggest you change the Name, "emailaddress" to its OID name, urn:oid:0.9.2342.19200300.100.1.3. See the chart below for mappings. The Namespace should also be deleted. After these changes are made the claim should look like the example below.
Save the changes.
When transitioning from Shibboleth, you may need to experiment with the correct attribute name. 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 assumption that the Azure AD 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. Consult with Cirrus Support if you have questions.
Below is a listing of common attributes and suggestions for mapping to Azure AD values based on the eduPerson schema specification (https://wiki.refeds.org/display/STAN/eduPerson).
| Attribute (friendlyName) | OID | Suggested AAD Mapping | Research and Scholarship |
| Surname (sn) | urn:oid:2.5.4.4 | user.surname | Yes |
| Given Name (givenName) | urn:oid:2.5.4.42 | user.givenname | 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.mail | Yes |
| UID (uid) | urn:oid:0.9.2342.19200300.100.1.1 | user.userprincipalname | |
|
(eduPersonPrincipalName) *See note below chart |
urn:oid:1.3.6.1.4.1.5923.1.1.1.6 | user.userprincipalname | Yes if not reassigned |
| (eduPersonUniqueId) | urn:oid:1.3.6.1.4.1.5923.1.1.1.13 | user.userprincipalname | |
| (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 |
Note: eduPersonPrincipalName should be statically assigned, invariant, persistent, not case sensitive, and scoped.
Research and Scholarship Entity Category
These suggested attributes identified above also satisfy the Research and Scholarship Entity Category requirements (https://refeds.org/category/research-and-scholarship). To be fully compliant with R&S requirements, you will also need to signal that MFA is enforced. See Step 6 below.
Azure AD signs both the SAML response and assertion. Some applications only want one or the other signed. Our recommendation for the Default and R & S applications is to only sign the response. This configuration will match Shibboleth’s default behavior.
To change the signing settings click “Edit” and pick a “Signing Option”.
Customers moving from Shibboleth likely have a default policy to encrypt all assertions. To enable this with Azure AD, navigate to the “Token Encryption” side menu, import the certificate for the Cirrus Bridge, and then activate the certificate. It can take several minutes for Azure AD to start encrypting assertions.
Azure provides a launch pad for users to launch applications you have configured in Azure AD. This, in SAML terms, is known as IdP Initiated Login. Applications such as the Default Cirrus Federation Bridge and (if created) R & S application have no single, corresponding InCommon application to send a user to.
To ensure these applications do not appear on the launch pad, go to “Properties” and ensure “Visible to users?” is No.
For applications that you do want to appear in the launch pad (and the corresponding InCommon SP supports IdP initiated login) you must:
Step 6 - MFA
Azure AD with Azure MFA - REFEDS MFA Setup
For applications that require MFA or that you want Cirrus to assert REFEDS MFA authncontext, you can configure a “Conditional Access” policy to require MFA and Cirrus will assert the appropriate REFEDS MFA authncontext to the InCommon SP. See the MFA Blog Post for more details.
Azure AD Duo MFA (or other non-native MFA) - REFEDS MFA Setup
When Azure AD is configured to use a non-native MFA, the IdPs do not automatically send the signal that MFA is enabled and, therefore, the Cirrus Bridge is unaware of any MFA status. Customers must manually configure attributes/claims to send the desired MFA signal to the Cirrus Bridge.
Cirrus added an operation attribute cirrus.rule.authnContext to allow customers to signal to the Cirrus Bridge the authncontext rules in operation. When cirrus.rule.authnContext attribute is released with the value “https://refeds.org/profile/mfa”, the Cirrus Bridge will assert the appropriate MFA attributes to downstream SPs.
|
Use Case |
Attribute/Claim to Release |
Value |
Result |
|
Duo MFA is enforced for all users * |
cirrus.rule.authnContext |
Cirrus will assert REFEDS MFA to downstream SPs |
*For other Use Cases, discuss with Cirrus Support Team.
Before you can use the Cirrus Bridge, you will need to assign access. Access can be controlled by direct assignment, but in most cases, you will want to grant using a group. In this example, a dedicated group of users has been defined.
Once complete, you can test your integration and register the Bridge in InCommon if desired.
Once the default application is configured, the test URL provided by Cirrus Identity can be used to test authentication to your Cirrus Bridge. The test URL will be of the following form:
https://<<name>>.proxy.cirrusidentity.com/module.php/core/authenticate.php?as=<<name>>_proxy
In this example, we are authenticating to our Athena Institute, the Cirrus test environment, to test a Cirrus Bridge.
1. Navigate to a Cirrus testing endpoint URL. This is unique for your Cirrus Bridge implementation and will be provided to you by Cirrus.
a. Example: https://athena-bridge.proxy.cirrusidentity.com/demo.php
2. Authenticate. You should be prompted for MFA if you have enabled it.
3. After successfully authenticating, you should see a screen for your institution similar to the one for the Athena Institute below.
Click on the test authenticating with your Cirrus proxy link.
4. You should see results similar to the screenshot below:
To validate the native Azure AD MFA is being asserted, you should see the key attribute/claim in the left-hand column http://schemas.microsoft.com/claims/authnmethodsreferences.
One of the claim values should be http://schemas.microsoft.com/claims/multipleauth, as noted in the green box above.
This indicates that MFA is enforced for all populations using the Cirrus Bridge application.
To validate non-native Azure AD MFA is being asserted.
REFEDS MFA
The Cirrus Bridge transforms the MFA signals it receives from Azure AD to assert REFEDS MFA is true. This is required to be in compliance with NIH security requirements. To verify the AuthData the Cirrus Bridge will assert, "Click to view AuthData".
You should see the assertion similar to the example below for Azure AD.