Our technical documentation is moving

SAML with Azure

Overview

This is a basic overview of integrating with IE via SAML in an Azure application.

Enable single sign-on for an app

To set up single sign-on for an application:

In the Azure AD portal, select Enterprise applications. Then ,click Create your Own Application
Give it a name and then select the "integrate any other application..." option and create
In the Manage section, select Single sign-on to open the Single sign-on pane for editing.

Upload the SP (IE) Metadata File

Upload the metadata file you received from IE and this will auto populate most of the SAML configuration that you'll need.

NOTE: If uploading an XLM file (instead of utilizing a live hosted URL), remove the validUntil property and value.

Azure Docs for SAML Claim Customization: https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-saml-claims-customization

Edit/Add User Attributes and Claims

This is how Azure will know what to send along with the User authentication via SAML

Required Claims

email
firstname
lastname
licenseIds (see instructions below)

Optional Claims

These are useful for passing extra values that will be included next to learners in reports (examples: role, department, major, title, year, studentId).

ref1
ref2
ref3

How to Add a New Claim:

Click "Add New Claim" to bring up the manage claim dialog.
Give the claim an identifying name
Namespace can be the attribute name, otherwise we're able to match whatever namespace you enter here.
Source should be Attribute.
Source attribute is the key matching the user value you'd like to include.

Add licenseId as a Claim (Static Attribute)

Perform the same steps as above say for the last one
In the Source Attribute field, add the license Id (provided by IE) in plain text instead of matching an already defined attribute key. You'll know it's a static value if Azure surrounds it in quotes.

Configuring the NameId (Name Identifier)

The Name Identifier is the unique ID that will identify SAML users coming from the IdP (identity provider).

Requirements

Must be unique across the instance: This value of the NameId must be unique across all learners of every client in an instance. This means that if you share an instance with other clients (almost everyone), then your ID must not clash with other client's learners. Some good options include:
- Email Addresses
- Appending the school domain name to a name or ID
- Or utilizing an ID random enough to sufficiently collision resistant

In Azure, the NAME_ID attribute/claim looks like this:

Recommendations

Use an ID that doesn't change: Since this value used to sync learner to their accounts or create a new account if one doesn't exist for a learner, it's recommended that this value be from a source that doesn't change. If the value does change, then the learner will receive a fresh account upon authenticating and will lose all previous progress.
- Email Address as NameId will suffice : Sending an email as the NameId can cause the problem mentioned above when a learner's email changes due to a name change. That said, email addresses are used by many clients without much headache. Though it isn't the "perfect" option, we considered it "good enough".
- Unique IDs are a better option: If available, an ID with sufficient randomness to be collision resistant, or appending a domain or school name to less random ID, has the benefits of being both unique and unchanging. See below for an example how to create a unique ID by combining an learner ID and a static

Making the NameID unique

A recommended NameID is a combination of unique-to-your-institution ID like an employee ID or student ID combined with a domain name you own. To do this in Azure, follow these steps:

Start by editing the Name Identifier Value attribute and changing the source to Transformation by selecting the radio button

2. Then set the Transformation to Join(), the Parameter 1 to the unique-to-your-institution ID, and Parameter 2 to the static value of the @ symbol and your domain name like below.

Note: Azure will put your string in quotes (like the licenseId above) if it recognizes your input as a static value.

3. Then click save and you're all set!

Report abuse