Azure-AD As IDP

Microsoft Azure AD (Azure Active Directory) supports both SAML and Oauth2 for SSO authentication. When an application is registered with Azure AD, a trust relationship is established between the Azure-AD identity provider (IDP) and the application acting as a service provider (SP).

Enabling A SAML Based App Within Azure AD

To register a SAML based application with Azure AD, application owners must provide the Metadata URI (or an XML  file containing the metadata details) and the Redirect URI of the application. The metadata should also contain the signing public key and the logout URI.

Azure in turn will expose the tenant-specific SSO and single sign-out URIs. These URIs represent addressable locations – they’re not just identifiers – so it is possible to go to the IDP URI  to read the tenant’s metadata information. The azure metadata is generally located at https://login.microsoftonline.com/<TenantDomainName>/FederationMetadata/2007-06/FederationMetadata.xml

The <TenantDomainName> placeholder represents a registered domain name or TenantID of your Azure AD tenant. When the application gets registered, owners will be given the details of the registration and the specific tenant information for McMaster University.

The following table outlines the basic SAML elements required to enable Azure AD to recognize applications via SAML:

Metadata Elements	Description
Identifier (EntityID)	Uniquely identifies the application. Azure AD sends the identifier to the application as the Audience parameter of the SAML token. The application is expected to validate it. This value also appears as the Entity ID in any SAML metadata provided by the application. App owners should provide a URL that uses the following pattern: ‘https://app-name.mcmaster.ca’ You can find this value as the Issuer element in the AuthnRequest (SAML request) sent by the application.
Reply URL	Specifies where the application expects to receive the SAML token response from the IDP. The reply URL is also referred to as the Assertion Consumer Service (ACS) URL. It is possible to specify more than one Reply URL.
Sign-on URL	When a user opens this URL, the service provider redirects to Azure AD to authenticate and sign in the user.
Relay State	Specifies to the application where to redirect the user after authentication is completed. Typically the value is a valid URL for the application.
Logout URL	Used to send the SAML/soap logout responses back to the application.

User Attributes and Claims

When a user authenticates via a registered application, Azure AD issues the application a SAML token with information in the form of attributes/claims about the user that uniquely identifies them. By default, this information includes the user’s unique identifier (MacID), email address, first name, and last name. These claims might need to be customized if, for example, the  application requires further specific claim values or a specific formatting of them.

The Unique User Identifier (MacID) value is a required claim and is the most important attribute in the set. The default name for this claim (based on EduPerson) is user.userprincipalname. This user identifier uniquely identifies each user within the organization. The specific name of this claim can be changed to fit an expected name-value and the content of it is generally  ‘macid@mcmaster.ca’ for all McMaster University users. This value should not be confused with the email value. The email value might precisely resemble the unique identifier but in this case, it can also be different as the organization allows for email aliases. This is important as email is not to be considered a unique identifier.

McMaster University’s Azure identity platform supports single sign-on (SSO) with most enterprise applications and when a user authenticates through the identity platform using the SAML 2.0 protocol, it sends a token to the application. The SAML token contain pieces of information about the user known as claims (Attributes). A claim is information that an identity provider to identify and categorize users. In a SAML token, claims data is typically contained in the SAML Attribute Statement. The user’s unique ID is typically represented in the SAML Subject also referred to as the name identifier (nameID).

By default, the Microsoft identity platform issues a SAML token to an application that contains a NameIdentifier claim with a value of the user’s username (also known as the user principal name) in Azure AD, which can uniquely identify the user. The default SAML token also contains other claims that include the user’s email address, first name, and last name as shown below:

Default Claims:

• Claim name |  Value
• Unique User Identifier (Name ID): user.userprincipalname [format:macid@mcmaster.ca]
• user.userprincipalname: user.userprincipalname
• user.emailaddress: emailaddress
• user.employeeid: employeeid
• user.givenname: firstname
• user.surname lastname

Optionally and upon request, the Microsoft identity platform can also issue extended claims containing the following type of information about identities:

Extended Claims:

• extensionAttribute1 = primary affiliation (possible values: student, employee, affiliate)
• extensionAttribute2 = union-code/student-status (employee’s union code or student’s status)
• extensionAttribute3 = department/faculty (emp. department or student’s faculty)
• extensionAttribute4 = sub-department (employee’s sub-department or student’s faculty)
• extensionAttribute5 = title (employee’s position name or student’s academic program)

The above-extended claims are populated by IAM based on extraction algorithms that calculate and determine what applies to each account depending on their specific status and updating of these values occurs immediately once changes have occurred on the person’s records. The passing of these extended claims on the response SAML token is optional and must be explicitly requested if an application wants to make use of these within their local processes.

SAML Signing Certificate

Azure AD uses a certificate to sign the SAML tokens it sends to the application. The application must be able to recognize this certificate to enable the trust between Azure AD and the application. The value of this certificate will be provided by UTS when configuring the application to be recognized by Azure AD.

Set Up The Application To Use Azure AD

Check out Understanding and Configuring SAML for details on how to configure your local SAML environment.

On the SAML application side, there are certain values that need to be configured on your SP deployment so it can use Azure AD as the SAML identity provider. You should set the values depending on the configuration steps of your specific SAML client software. For example, if you are configuring GitHub then you would go to the github.com site and set the values. Otherwise, you will need to use the documentation for the specific SAML client you are configuring.

The Login URL and Logout URL values should both resolve to the same SP endpoint, which is the SAML request-handling endpoint that is registered in the Azure AD tenant.

The Azure AD Identifier is the value of the issuer of the SAML token to the application, also known as the Azure AD IDP in the SAML scheme.

For an in-depth explanation of this process for SPs, refer to Understanding and Configuring SAML.

Testing The SSO Configuration

Once the application has been configured to use Azure AD, you can test the settings to see if SSO works as intended.

Use the EntityID URL provided and try to trigger an Azure session or use the login URL provided by UTS during  the registration process. You might need to request a test account if you do not want to use ‘live’ accounts to test. Please refer to Test Login Accounts for more information.

If sign-on is successful, you can then request that users and groups become assigned to the SAML application for access control.