Azure AD Bridge Setup - REV 7.1

Configuring Cirrus Bridge with Azure AD

REV 7.1

Table of Contents

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

Grant API Access

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. 

https://login.microsoftonline.com/$TENANT_ID/adminconsent?client_id=ea71bc49-6159-422d-84d5-6c29d7287974&state=12345&redirect_uri=https://admin.cirrusidentity.com/azure-registration

Configuring Azure AD

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: 

Per Application Settings 

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
Application URIs/EntityIDs to a single
Azure application. Cirrus will automatically
use the application for all entityID added to
it.

Supported
(must enable a default application URI)

Cirrus will provide you with the Identifier URI/Entity ID for the default once your Azure Bridge is created.

Common Settings for all Applications

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

Step 1 - Add Application

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

Screen Shot 2022-08-17 at 9-33-40 AM-png

In the search box, search for “Cirrus Identity” and select the “Cirrus Identity Bridge for Azure AD” gallery app.

Cirrus Identity Bridge for Azure AD

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. 

Cirrus Identity Bridge for Azure AD

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. 

Cirrus SSO

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

Premium Demo

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.

Basic SAML Configuration 1

Ensure the reply URL and the Identifier/EntityID are marked as default. 

Basic SAML Configuration Patterns

Click “Save” when done. 

Step 2 - Attribute Mapping and NameID

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

Attribute Mapping and NameID

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 and claims

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.

attributes

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.

Manage Claim

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.

manage claim 2

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.

Step 3 - Set Signing Settings

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

Signing Option

SAML Signing Certificate

Step 4 - Set Encrypted Settings

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. 

Token encryption

Step 5 - Application Visibility and Icons 

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.

Cirrus Federation Bridge

For applications that you do want to appear in the launch pad (and the corresponding InCommon SP supports IdP initiated login) you must: 

  • Set “Visible to users” to “Yes”.
  • Ensure from Step 1, an Identifier/EntityID is marked as default and a Reply URL is marked as default. 
  • You may upload an Icon. View the XML metadata for the InCommon SP and look for the “mdui:Logo” URL. 

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 

https://refeds.org/profile/mfa

Cirrus will assert REFEDS MFA to downstream SPs

*For other Use Cases, discuss with Cirrus Support Team.

Step 7 - Assigning Access

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. 

Users and Groups

Once complete, you can test your integration and register the Bridge in InCommon if desired. 

Testing Integration 

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.

Test authentication

Click on the test authenticating with your Cirrus proxy link.

4. You should see results similar to the screenshot below:

SAML 2.0 SP Demo Example

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

SAML 2.0 SP Demo Example-1 

You should see the assertion similar to the example below for Azure AD.  

Click to view AuthData

© Copyright Cirrus Identity, Inc.
 

 

Blog comments