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:
- “Native” Azure AD
- SAML
- 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.
-
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. ↩︎
-
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. ↩︎