Use Microsoft Entra MFA with an external provider (preview)

This article describes how an external authentication provider connects to Microsoft Entra multifactor authentication (MFA).

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

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

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

The tenant admin adds external authentication methods to Microsoft Entra ID. If a tenant requires an external authentication method 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 external authentication method.

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

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

External authentication methods are implemented on top of OpenID Connect (OIDC). This implementation requires at least three publicly facing endpoints to implement an external authentication method:

• 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

Here's how sign-in works with an external authentication method:

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, if a Conditional Access policy requires MFA).

3. The user chooses the external authentication method as a second factor.

4. Microsoft Entra ID redirects the user's browser session to the URL of the external authentication method.

   This URL is discovered from the discovery URL that an admin provisioned when they created the external authentication method.

   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 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 a credential.

8. The external authentication provider redirects the user back to Microsoft Entra ID with a valid token, including all the 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. If the validation succeeds, that means that the user satisfied the MFA requirement. The user might also have to meet other policy requirements.

Configuring a new external authentication provider with Microsoft Entra ID

To issue id_token_hint, external authentication methods need an application that represents the integration. You can create the application in two ways:

• In each tenant that uses the external provider.
• As one multitenant application. To enable the integration for their tenant, privileged role administrators need to grant consent.

Using a multitenant application can reduce the chance of misconfiguration in each tenant. Providers can also make changes to metadata (for example, 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 a Microsoft Entra ID tenant (if they don't already have one).

2. Register an application in their tenant.

3. In the application, under Supported Account types, select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant).

4. Add the delegated permission openid and profile values for Microsoft Graph.

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

   In the application registration, add the authorization_endpoint value provided in the provider's discovery document as a redirect URL. 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. You need these properties for our scenario.

Another valid model for supporting integration is to use an application for each tenant. 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.

Adding an external authentication method 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 the type externalAuthenticationMethodConfiguration.

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.

To set the MFA requirement for user sign-in, users with the Conditional Access Administrator role can create a policy with the Require MFA grant. External authentication methods aren't currently supported with authentication strengths.

Learn more about how to add an external authentication method in the Microsoft Entra admin center.

Microsoft Entra ID interaction with provider

The next sections explain provider requirements and include examples for how Microsoft Entra ID interacts 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 discovery URL must use the https scheme and must end with /.well-known/openid-configuration. You can't include any additional path segments, query strings, or fragments after this segment. The full discovery URL must be included in the discovery URL that you configure when you create the external authentication method.

The endpoint returns a provider metadata JSON document hosted there. The endpoint must also return a valid content-length header. The metadata document must comply with OpenID Connect Discovery 1.0 (incorporating errata set 2) and include all required OIDC metadata fields.

The provider's metadata needs to include the data listed in the following table. These values are required for this extensibility scenario. The JSON metadata document might contain more information.

For the OIDC document that has the values for provider metadata, see Provider metadata.

https://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/v2.0",
  "jwks_uri": "https://customcaserver.azurewebsites.net/.well-known/jwks",
  "response_modes_supported": [
    "form_post"
  ],
  "response_types_supported": [
    "id_token"
  ],
  "scopes_supported": [
    "openid"
  ],
  "SigningKeys": [],
  "subject_types_supported": [
    "public"
  ]
}

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

Discovery URL and issuer examples

The following examples illustrate valid and invalid discovery URL and issuer combinations for this integration.

Valid discovery URL and issuer pairs

• Discovery URL: https://example.com/.well-known/openid-configuration
  Issuer: https://example.com
• Discovery URL: https://example.com:8443/.well-known/openid-configuration
  Issuer: https://example.com:8443
• Discovery URL: https://example.com/tenant1/.well-known/openid-configuration
  Issuer: https://example.com/tenant1

Invalid discovery URL and issuer examples

• Discovery URL: https://example.com/.well-known/openid-configuration
  Issuer: https://example.com:443/ (Default HTTPS port explicitly added in issuer.)
• Discovery URL: https://example.com:443/.well-known/openid-configuration
  Issuer: https://example.com/ (Port mismatch.)
• Discovery URL: https://example.com/.well-known/openid-configuration?client_id=0oasxuxkghOniBjlQ697
  Issuer: https://example.com (You can't include a query string in a discovery URL.)

Provider metadata caching

To improve performance, Microsoft Entra ID caches metadata that the provider returns, including the keys. Provider metadata caching prevents a discovery call each time Microsoft Entra ID communicates with an external identity provider.

This cache is refreshed every 24 hours. We recommend that providers follow these steps to roll over their keys:

1. Publish the Existing Cert and New Cert in jwks_uri.
2. Keep signing in with Existing Cert until the Microsoft Entra ID cache is refreshed, expired, or updated (every 2 days).
3. Switch to signing in 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

You can use the public key identifier from the token (the "kid" from JSON Web Signature (JWS)) to 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 Validate an ID token. There are no special steps for the consumers of our discovery metadata.

You can find all the details on token validation in Microsoft's token validation library. You can also ascertain these details by browsing the source code. For a sample, see Azure Samples.

After validation succeeds, you can work with the claims payload to get details about 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. When you use this flow, communication with the provider occurs by using only the provider's authorization endpoint.

To inform the provider about 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 a large list of parameters gets passed to the provider. 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 redirect URI

The redirect URIs should be registered with the provider off-band. The redirect URIs that you can send 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 external authentication method that satisfies MFA

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

Microsoft Entra ID uses the combination of the acr and amr values to validate that:

• The authentication method used for the second factor satisfies the MFA requirement.
• The authentication method is a different type than 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 that's passed as id_token_hint in the request made to the provider. The token might contain more claims than the following table shows.

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

Optional claims from Microsoft Entra ID

If a provider needs optional claims from Microsoft Entra ID, 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

We recommend that you associate accounts on the provider side with the account in Azure by using the oid and tid claims. These two claims are guaranteed to be unique for the account in the tenant.

Example of id_token_hint

Here's an example of 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": "testuser2@contoso.com"
  "oid": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "tid": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
  }.

Here's an example of 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": "externaltestuser@hotmail.com",
  "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 the following items. The list isn't exhaustive, and providers should complete other validation steps as they see fit.

• From the request:

  • Ensure that the redirect_uri is published as described in Microsoft Entra ID call to the external identity provider.
  • Ensure that the configured discovery URL uses HTTPS and ends with /.well-known/openid-configuration. Also ensure that it doesn't include query parameters or fragment identifiers. Make sure that the issuer value matches the discovery document exactly.
  • 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 Microsoft Entra ID presents to it.

• From the claims in the id_token_hint:

  • (Optional) Make a call to Microsoft Graph to fetch other details about this user. The oid and tid claims in id_token_hint are useful in this regard. For details about the claims provided in id_token_hint, see Default id_token_hint claims.

• Carry out any other authentication activity for the provider's product.

• Depending upon the result of the 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 use POST to send 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 value for the user. Microsoft Entra ID uses the published OIDC metadata to verify that the token contains the expected claims, and carries out any other token validation that OIDC requires.

Supported acr claims

Supported amr claims

Microsoft Entra ID requires that MFA is 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.

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

Failure is indicated by issuing error response parameters.

Microsoft Entra ID considers the request successful if 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 the 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 value 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 Correlation ID value. It helps 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 external authentication methods

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

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. We recommend that admins 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 external authentication method. Policies should only be configured with Require multifactor authentication.

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

Integration support

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

References

• OAuth2.0 and OIDC specification

Glossary

Related content

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