Choosing a Connection Type for an Azure AD Instance

Knowledge Articles
, , , , ,
1

Choosing a Connection Type for an Azure AD Instance

Protocols

Auth0 can connect to Microsoft Azure AD using a few different connections. The connection types are:

“Native” Azure AD

Configured under Authentication > Enterprise Connections > Microsoft Azure AD. This document assumes the Identity API setting in the Auth0 connection is “Microsoft Identity Platform (v2)”

This connection type uses the OAuth authorization code flow. It accepts claims from a basic id_token, and queries the MS graph API directly for groups and additional profile information (if configured). If custom claims are included in the id_token, they will be ignored.

Enterprise OIDC

Configured under Authentication > Enterprise connections > Open ID Connect.

This connection type can be configured to use either OAuth implicit or authorization code flows. Custom claims in an id_token will be mapped to the Auth0 user profile.

SAML

Configured under Authentication > Enterprise Connections > SAML.

This connection type uses the SAML protocol, and supports attribute mapping and all standard SAML features.

Comparison

The table below compares and contrasts the capabilities of the different connection types:

Connection Type “Native” Azure AD Enterprise OIDC SAML
Protocol OAuth authorization code flow OAuth implicit flow OR OAuth authorization code flow SAML
Can receive optional claims from Azure AD? No Yes Yes
Federated logout support (“Single Logout” or SLO) Yes No Yes [1]
Receive AD Groups Yes, friendly names [2] Yes, object IDs [3] Yes, object IDs [4]
Receive Extended Profile Yes[5] No No

Choosing a Connection Type

Overall, SAML and the “native” Azure AD connection type provide the most functionality. Of these two connection types, SAML is the most flexible but also the most complex to configure. Azure AD might be required if specific claims are needed (see later section on “Extended Profile”).

An enterprise OIDC connection might be preferred in the following cases:

  • Providing a client secret is not possible or desirable (implicit flow only)
  • Custom claims are required but the additional functionality of SAML is not.

Except for specific use cases, the connections are recommended in the following order:

  1. “Native” Azure AD
  2. SAML
  3. OIDC

The “Extended Profile” in Azure AD Connections

If the “Extended Profile” option is enabled for an Azure AD connection, Auth0 will map certain attributes received from the Microsoft Graph API. Specifically, Auth0 queries the following graph endpoint:

https://graph.microsoft.com/v1.0/users/{AzureUserId}

If available, the following attributes are mapped to the Auth0 user profile. This table also includes the equivalent optional claims that can be configured for OIDC or SAML connections.

Graph Attribute Auth0 Profile Attribute Data type Equivalent optional claim for OIDC or SAML
businessPhones phone array -
givenName given_name string given_name
jobTitle job_title string -
mobilePhone mobile string -
preferredLanguage preferred_language string xms_pl
surname family_name string family_name
userPrincipalName upn string upn

Note Auth0 does not send the $select parameter to the graph endpoint so only the properties above are returned. More info

Groups

As noted above, the behavior of groups varies across connection types.

Azure AD Connection

If the appropriate graph permissions are configured, Auth0 will automatically retrieve groups for the user and map these into the groups attribute in the Auth0 profile. The groups are retrieved directly from the MS graph API and there is no need to configure a custom claim. The groups retrieved for the user will use the “displayName” of the group as returned from the graph endpoint:

https://graph.microsoft.com/v1.0/users/{AzureUserId}/memberOf

Open ID Connect and SAML

Azure AD must be configured with an optional claim for groups to be included in the id_token or SAML response. Groups are mapped into the group_ids attribute in the Auth0 profile. The primary Microsoft documentation for this is:

Microsoft: Provide optional claims to your app

The following document is also relevant:

Microsoft: Configure group claims for applications by using Azure Active Directory

Note the following text from the document on configuring group claims:

Support for use of sAMAccountName and security identifier (SID) attributes synced from on-premises is designed to enable moving existing applications from Active Directory Federation Services (AD FS) and other identity providers. Groups managed in Azure AD don't contain the attributes necessary to emit these claims.

This means optional claims will only contain the object identifier of the groups, unless the groups were synced from on-premises AD. Object identifiers have the following format:

4d409f02-f2c7-4a75-8b5c-abac0a1af785.

  1. Azure SAML SLO documentation ↩︎

  2. Requires permission to query the Microsoft Graph API ↩︎

  3. Azure can be configured to send groups as a custom claim in the id_token or as SAML attributes. Unless the groups were synced from on-premises AD, only the group object IDs are sent in the id_token or SAML response. ↩︎

  4. Azure can be configured to send groups as a custom claim in the id_token or as SAML attributes. Unless the groups were synced from on-premises AD, only the group object IDs are sent in the id_token or SAML response. ↩︎

  5. Requires permission to query the Microsoft Graph API ↩︎

3 Likes