Microsoft Entra multifactor authentication external method provider reference (Preview)

This topic describes how an external authentication provider connects to Microsoft Entra multifactor authentication (MFA). An external authentication provider can integrate with Microsoft Entra ID tenants as an external authentication method (EAM). An EAM can satisfy the second factor of an MFA requirement for access to a resource or application. EAMs require at least a Microsoft Entra ID P1 license.

When a user signs in, that tenant policies are evaluated. The authentication requirements are determined based on the resource that the user tries to access.

Multiple policies may apply to the sign-in, depending on their parameters. Those parameters include users and groups, applications, platform, sign-in risk level, and more.

Based on the authentication requirements, the user may need to sign in with another factor to meet the MFA requirement. The second factor needs to complement the type of first factor.

EAMs are added to Microsoft Entra ID by the tenant admin. If a tenant requires an EAM for MFA, the sign-in is considered to meet the MFA requirement after Microsoft Entra ID validates both:

• The first factor completed with Microsoft Entra ID
• The second factor completed with the EAM

That validation meets the MFA requirement for two or more types of methods from:

• Something you know (knowledge)
• Something you have (possession)
• Something you are (inherence)

EAMs are implemented on top of Open ID Connect (OIDC). This implementation requires at least three publicly facing endpoints:

• An OIDC Discovery endpoint, as described in Discovery of provider metadata
• A valid OIDC authentication endpoint
• A URL where the public certificates of the provider are published

Let's look closer at how sign-in works with an EAM:

1. A user tries to sign in with a first factor, like a password, to an application protected by Microsoft Entra ID.
2. Microsoft Entra ID determines that another factor needs to be satisfied. For example, a Conditional Access policy requires MFA.
3. The user chooses the EAM as a second factor.
4. Microsoft Entra ID redirects the user's browser session to the EAM URL:
   1. This URL is discovered from the discovery URL provisioned by an admin when they created the EAM.
   2. The application provides an expired or nearly expired token that contains information to identify the user and tenant.
5. The external authentication provider validates that the token came from Microsoft Entra ID, and checks the contents of the token.
6. The external authentication provider might optionally make a call to Microsoft Graph to fetch additional information about the user.
7. The external authentication provider performs any actions it deems necessary, such as authenticating the user with some credential.
8. The external authentication provider redirects the user back to Microsoft Entra ID with a valid token, including all required claims.
9. Microsoft Entra ID validates that the token's signature came from the configured external authentication provider, and then checks the contents of the token.
10. Microsoft Entra ID validates the token against the requirements.
11. The user satisfied the MFA requirement if the validation succeeds. The user might also have to meet other policy requirements.

Configure a new external authentication provider with Microsoft Entra ID

An application representing the integration is required for EAMs to issue the id_token_hint. The application can be created in two ways:

• Created in each tenant that uses the external provider.
• Created as one multitenant application. Privileged Role Administrators need to grant consent to enable the integration for their tenant.

A multitenant application reduces the chance of misconfiguration in each tenant. It also lets providers make changes to metadata like reply URLs in one place, rather than require each tenant to make the changes.

To configure a multitenant application, the provider admin must first:

1. Create an Microsoft Entra ID tenant if they don't have one yet.

2. Register an application in their tenant.

3. Set the Supported Account types of the application to: Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).

4. Add the delegated permission openid and profile of Microsoft Graph to the application.

5. Don't publish any scopes in this application.

6. Add the external identity provider’s valid authorization_endpoint URLs to that application as Reply URLs.

   Note

   The authorization_endpoint provided in the provider’s discovery document should be added as a redirect url in the application registration. Otherwise, you get the following error: ENTRA IDSTS50161: Failed to validate authorization url of external claims provider!

The application registration process creates an application with several properties. These properties are required for our scenario.

An application for each tenant is also a valid model to support the integration. If you use a single-tenant registration, the tenant admin needs to create an application registration with the properties in the preceding table for a single-tenant application.

Configure optional claims

A provider can configure more claims by using optional claims for id_token.

Add an EAM to Microsoft Entra ID

External identity provider information is stored in the Authentication methods policy of each tenant. The provider information is stored as an authentication method of externalAuthenticationMethodConfiguration type.

Each provider has one entry in the list object of the policy. Each entry needs to state:

• If the method is enabled
• The included groups that can use the method
• The excluded groups that can't use the method

Conditional Access Administrators can create a policy with the Require MFA Grant to set the MFA requirement for user sign-in. External authentication methods aren't currently supported with authentication strengths.

For more information about how to add an external authentication method in the Microsoft Entra admin center, see Manage an external authentication method in Microsoft Entra ID (Preview).

Microsoft Entra ID interaction with provider

The next sections explain provider requirements and include examples for Microsoft Entra ID interaction with a provider.

Discovery of provider metadata

An external identity provider needs to provide an OIDC Discovery endpoint. This endpoint is used to get more configuration data. The full URL, including .well-known/oidc-configuration, must be included in the Discovery URL configured when the EAM is created.

The endpoint returns a Provider Metadata JSON document hosted there. The endpoint must also return the valid content-length header.

The following table lists the data that should be present in the metadata of the provider. These values are required for this extensibility scenario. The JSON metadata document may contain more information.

For the OIDC document with the values for Provider Metadata, see Provider Metadata.

http://customcaserver.azurewebsites.net/v2.0/.well-known/openid-configuration
{
  "authorization_endpoint": "https://customcaserver.azurewebsites.net/api/Authorize",
  "claims_supported": [
    "email"
  ],
  "grant_types_supported": [
    "implicit"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "issuer": "https://customcaserver.azurewebsites.net",
  "jwks_uri": "http://customcaserver.azurewebsites.net/.well-known/jwks",
  "response_modes_supported": [
    "form_post"
  ],
  "response_types_supported": [
    "id_token"
  ],
  "scopes_supported": [
    "openid"
  ],
  "SigningKeys": [],
  "subject_types_supported": [
    "public"
  ]
}

http://customcaserver.azurewebsites.net/.well-known/jwks
{
  "keys": [
    {
      "kty": "RSA",
      "use": "sig",
      "kid": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
      "x5t": "A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u",
      "n": "jq277LRoE6WKM0awT3b...vt8J6MZvmgboVB9S5CMQ",
      "e": "AQAB",
      "x5c": [
        "cZa3jz...Wo0rzA="
      ]
    }
  ]
}

Provider metadata caching

To improve performance, Microsoft Entra ID caches metadata returned by the provider, including the keys. Provider metadata caching prevents a discovery call each time Microsoft Entra ID talks to an external identity provider.

This cache is refreshed every 24 hrs (one day). Here's how we suggest a provider rollover their keys:

1. Publish the Existing Cert and New Cert in the "jwks_uri".
2. Keep signing with Existing Cert until Microsoft Entra ID cache is refreshed, expired, or updated (every 2 days).
3. Switch to signing with New Cert.

We don't publish schedules for key rollovers. The dependent service must be prepared to handle both immediate and periodic rollovers. We suggest using a dedicated library built for this purpose, like azure-activedirectory-identitymodel-extensions-for-dotnet. For more information, see Signing key rollover in Microsoft Entra ID.

Discovery of Microsoft Entra ID metadata

Providers also need to retrieve the public keys of Microsoft Entra ID to validate the tokens issued by Microsoft Entra ID.

Microsoft Entra ID metadata discovery endpoints:

• Global Azure: https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration
• Azure for US Government: https://login.microsoftonline.us/common/v2.0/.well-known/openid-configuration
• Microsoft Azure operated by 21Vianet: https://login.partner.microsoftonline.cn/common/v2.0/.well-known/openid-configuration

Using the public key identifier from the token (the "kid" from JSON Web Signature (JWS)), one can determine which of the keys retrieved from the jwks_uri property should be used to validate the Microsoft Entra ID token signature.

Validating tokens issued by Microsoft Entra ID

For information about how to validate the tokens issued by Microsoft Entra ID, see Validating and ID token. There are no special steps for the consumers of our discovery metadata.

Microsoft’s token validation library has all the details on the specifics of token validation that are documented, or they can be ascertained from browsing the source code. For a sample, see Azure Samples.

Once validation succeeds, you can work with the claims payload to get details of the user, and their tenant.

Microsoft Entra ID call to the external identity provider

Microsoft Entra ID uses the OIDC implicit flow to communicate with the external identity provider. Using this flow, communication with the provider is done exclusively by using the provider's authorization endpoint. To let the provider know the user for whom Microsoft Entra ID is making the request, Microsoft Entra ID passes a token in through the id_token_hint parameter.

This call is made through a POST request because the list of parameters passed to the provider is large. A large list prevents the use of browsers that limit the length of a GET request.

The Authentication request parameters are listed in the following table.

Example of a redirection URI

The redirect Uniform Resource Identifiers (URIs) should be registered with the provider off-band. The redirect URIs that can be sent are:

• Global Azure: https://login.microsoftonline.com/common/federation/externalauthprovider
• Azure for US Government: https://login.microsoftonline.us/common/federation/externalauthprovider
• Microsoft Azure operated by 21Vianet: https://login.partner.microsoftonline.cn/common/federation/externalauthprovider

Example of an EAM that satisfies MFA

Here's an example of an authentication where an EAM satisfies MFA. This example helps a provider know what claims Microsoft Entra ID expects.

The combination of the acr and amr values are used by Microsoft Entra ID to validate:

• The authentication method used for second factor satisfies the MFA requirement
• The authentication method differs in 'type' from the method used to complete the first factor for sign-in to Microsoft Entra ID

{
  "id_token": {
    "acr": {
      "essential": true,
      "values":["possessionorinherence"]
    },
    "amr": {
      "essential": true,
      "values": ["face", "fido", "fpt", "hwk", "iris", "otp", "pop", "retina", "sc", "sms", "swk", "tel", "vbm"]
    }
  }
}

Default Id_token_hint claims

This section describes the required content of the token passed as id_token_hint in the request made to the provider. The token may contain more claims than in the following table.

To prevent it from being used for anything other than a hint, the token is issued as expired. The token is signed, and can be verified using the published Microsoft Entra ID discovery metadata.

Optional claims from Microsoft Entra ID

If a provider needs optional claims from Microsoft Entra ID, then you can configure the following optional claims for id_token: given_name, family_name, preferred_username, upn. For more information, see Optional claims.

Recommended use of claims

Microsoft recommends associating accounts on the provider side with the account in Azure AD by using the oid and tid claims. These two claims are guaranteed to be unique for the account in the tenant.

Example of an id_token_hint

Here's an example of an id_token_hint for a directory member:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w"
}.{
  "ver": "2.0",
  "iss": "https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0",
  "sub": "mBfcvuhSHkDWVgV72x2ruIYdSsPSvcj2R0qfc6mGEAA",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "exp": 1536093790,
  "iat": 1536093791,
  "nbf": 1536093791,
  "name": "Test User 2",
  "preferred_username": "[email protected]"
  "oid": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "tid": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
  }.

Here's an example of the id_token hint for a guest user in the tenant:

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "C2dE3fH4iJ5kL6mN7oP8qR9sT0uV1w"
}.{
  "ver": "2.0",
  "iss": "https://login.microsoftonline.com/9122040d-6c67-4c5b-b112-36a304b66dad/v2.0",
  "sub": "mBfcvuhSHkDWVgV72x2ruIYdSsPSvcj2R0qfc6mGEAA",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "exp": 1536093790,
  "iat": 1536093791,
  "nbf": 1536093791,
  "name": "External Test User (Hotmail)",
  "preferred_username": "[email protected]",
  "oid": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "tid": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
  }.

Suggested actions for external identity providers

We suggest that external identity providers complete these steps. The list isn't exhaustive, and providers should complete other validation steps as they see fit.

1. From the request:
   • Ensure that the redirect_uri is published provided in Microsoft Entra ID call to the external identity provider.
   • Ensure that the client_id has a value assigned to Microsoft Entra ID, such as ABCD.
   • The provider should first validate the id_token_hint that is presented to it by Microsoft Entra ID.
2. From the claims in the id_token_hint:
   • They can optionally make a call to Microsoft Graph to fetch other details about this user. The oid and tid claims in the id_token_hint is useful in this regard. For details about the claims provided in the id_token_hint, see Default id_token_hint claims.
3. Then carry out any other authentication activity that the provider’s product is built to do.
4. Depending upon the result of user’s actions and other factors, the provider would then construct and send a response back to Microsoft Entra ID, as explained in the next section.

Microsoft Entra ID processing of the provider response

The provider needs to POST a response back to the redirect_uri. The following parameters should be provided on a successful response:

On success, the provider would then issue an id_token for the user. Microsoft Entra ID uses the published OIDC metadata to verify that the token contains the expected claims, and does any other validation of the token that OIDC requires.

Supported acr claims

Supported amr claims

Microsoft Entra ID requires MFA to be satisfied to issue a token with MFA claims. As a result, only methods with a different type can satisfy the second factor requirement. As mentioned earlier, the different method types that can be used to satisfy the second factor are knowledge, possession, and inherence.

Microsoft Entra ID validates the type mapping based on the following table.

If no issues are found with the token, then Microsoft Entra ID considers MFA to be satisfied, and issues a token to the end user. Otherwise, the end user’s request fails.

Failure is indicated by issuing error response parameters.

Microsoft Entra ID considers the request successful if the id_token parameter is present in the response, and if the token is valid. Otherwise, the request is considered unsuccessful. Microsoft Entra ID fails the original authentication attempt due to requirement of the Conditional Access policy.

Microsoft Entra ID abandons the state of the authentication attempt on its end about 5 minutes after the redirection to the provider.

Microsoft Entra ID error response handling

Microsoft Azure services use a correlationId to correlate calls across various internal and external systems. It serves as a common identifier of the whole operation or flow that potentially involves multiple HTTP calls. When an error occurs during any of the operations, the response contains a field named Correlation ID.

When you reach out to Microsoft support or a similar service, provide the value of this Correlation ID as it helps to access the telemetry and logs faster.

For example:

ENTRA IDSTS70002: Error validating credentials. ENTRA IDSTS50012: External ID token from issuer 'https://sts.XXXXXXXXX.com/auth/realms/XXXXXXXXXmfa' failed signature verification. KeyID of token is 'A1bC2dE3fH4iJ5kL6mN7oP8qR9sT0u' Trace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333 Correlation ID: aaaa0000-bb11-2222-33cc-444444dddddd Timestamp: 2023-07-24 16:51:34Z

Custom controls and EAMs

In Microsoft Entra ID, EAMs and Conditional Access custom controls can operate in parallel while customers prepare for and migrate to EAMs.

Customers who currently use an integration with an external provider by using custom controls can continue to use them, and any Conditional Access policies they configured to manage access. Admins are recommended to create a parallel set of Conditional Access policies during the migration period:

• The policies should use the Require multifactor authentication grant control instead of the custom control grant.

  Note

  Grant controls based on authentication strengths, including the built-in MFA strength, aren't satisfied by the EAM. Policies should only be configured with Require multifactor authentication. We're actively working to support EAMs with authentication strengths.

• The new policy can be tested first with a subset of users. The test group would be excluded from the policy that requires the custom controls, and included in the policy that requires MFA. Once the admin is comfortable that the policy that requires MFA is satisfied by the EAM, the admin can include all required users in the policy with the MFA grant, and the policy configured for custom controls can be moved to Off.

Integration support

If you have any issues when you build EAM integration with Microsoft Entra ID, the Microsoft Customer Experience Engineering (CxE) Independent Solution Vendor (ISV) may be able to assist. To engage with the CxE ISV team, submit a request for assistance.

References

• OAuth2.0 and OIDC specification

Glossary

Next steps

For more information about how to configure an EAM in Microsoft Entra admin center, see Manage an external authentication method in Microsoft (Preview).