> ## Documentation Index
> Fetch the complete documentation index at: https://docs.authsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entra ID (External Authentication Methods - EAM)

> Use Authsignal as an external authentication method to satisfy multifactor authentication in Microsoft Entra ID.

Microsoft Entra ID supports [external authentication methods (EAM)](https://learn.microsoft.com/en-us/entra/identity/authentication/concept-authentication-external-method-provider), which let your users complete a multifactor authentication challenge with an external provider during sign-in. With this integration, an Authsignal challenge satisfies the Entra ID MFA requirement, so your users can verify with any authenticator you have enabled in Authsignal, such as email OTP, SMS OTP, passkeys, or push.

When a user signs in and Entra ID requires MFA, they choose Authsignal from the method picker, complete a challenge in the Authsignal Pre-built UI, and are returned to Microsoft to finish signing in.

## Prerequisites

* An Authsignal tenant with at least one [authenticator](https://portal.authsignal.com/organisations/tenants/authenticators) enabled.
* An [action](/actions-rules/actions/getting-started) configured for the sign-in challenge, with a default outcome of Challenge. Multi-step actions are not yet supported for this integration.
* A Microsoft Entra ID tenant with Conditional Access (Entra ID P1 or higher).
* An Entra ID account with at least the Authentication Policy Administrator role, plus the Privileged Role Administrator role to grant admin consent.

## Set up the integration

<Steps>
  <Step title="Register an application in Entra ID">
    The external method needs an application registration in your Entra ID directory. Entra ID issues a token for this application to identify the user to Authsignal.

    1. In the [Microsoft Entra admin center](https://entra.microsoft.com/), go to **App registrations** and select **New registration**.
    2. Give the application a name, for example `Authsignal External MFA Provider`.
    3. Under **Supported account types**, select **Accounts in this organizational directory only**.
    4. Register the application, then open **API permissions** and add the delegated Microsoft Graph permissions `openid`, `profile`, and `email`.
    5. Open **Token configuration** and add the `email` optional claim for **ID** tokens. This includes the user's email address in the token Entra ID sends to Authsignal, so email authenticator enrollment is pre-filled.
    6. Open **Authentication** and add a **Web** redirect URI. Copy the exact value from the Authsignal Portal setup page in the next step. If it is missing or does not match, sign-ins fail with `AADSTS5001255: Failed to validate authorization url of external authentication provider`.

    Note the application's **Application (client) ID** and **Directory (tenant) ID** from the overview page.
  </Step>

  <Step title="Activate Entra ID external MFA in the Authsignal Portal">
    1. In the [Authsignal Portal](https://portal.authsignal.com/), go to **Settings**, then **Marketplace**, and select **Entra ID external MFA**.
    2. Enter the **Application (client) ID** and **Directory (tenant) ID** from the previous step.
    3. Select the **action code** that will be tracked each time a user authenticates through this integration.
    4. Select **Activate Entra External MFA**.

    Activation configures everything needed on the Authsignal side, including the signing keys used to issue tokens to Microsoft. The page then displays the three values you need in Entra ID:

    * **Client ID**
    * **Discovery Endpoint**
    * **App ID**
  </Step>

  <Step title="Add the external method in Entra ID">
    1. In the Microsoft Entra admin center, go to **Entra ID**, then **Authentication methods**, and select **Add external MFA**.
    2. Give the method a display name. This is what users see in the method picker, and it cannot be changed later.
    3. Enter the **Client ID**, **Discovery Endpoint**, and **App ID** from the Authsignal Portal.
    4. Select **Request admin consent** and grant consent when prompted. Without consent, sign-ins fail with `AADSTS900491`.
    5. On the **Enable and target** tab, enable the method and target the users or groups who should be able to use it.
  </Step>

  <Step title="Require MFA with Conditional Access">
    Create a Conditional Access policy that requires MFA for the users and applications you want to protect:

    1. Go to **Entra ID**, then **Conditional Access**, and create a new policy.
    2. Assign the users and target resources.
    3. Under **Grant**, select **Grant access** with **Require multifactor authentication**.

    <Warning>
      External authentication methods only satisfy the standard **Require multifactor authentication** grant control. They do not satisfy **Require authentication strength** grants, and they do not satisfy legacy per-user MFA. Make sure targeted users have per-user MFA set to Disabled, and that any policies applying to them use the standard MFA grant.
    </Warning>
  </Step>
</Steps>

## User experience

The first time a user chooses the Authsignal method, Entra ID runs a registration flow. The user is redirected to the Authsignal Pre-built UI, enrolls and verifies an authenticator, and is returned to Microsoft. The method is then registered in their security info. Users can also register ahead of time from [Security info](https://mysignins.microsoft.com/security-info) by adding a sign-in method and selecting **External Auth methods**.

On later sign-ins, choosing the Authsignal method runs a verification challenge with the user's enrolled authenticator.

Authsignal identifies the user by their Entra ID object ID (the `oid` claim), so a user record is created in Authsignal on first use. When Entra ID provides an email claim, it is used to pre-fill email authenticator enrollment.

<Info>
  Entra ID populates the email claim from the user's **mail** attribute in the directory, not from
  their user principal name, and [omits addresses on domains the directory has not
  verified](https://learn.microsoft.com/en-us/entra/identity-platform/migrate-off-email-claim-authorization).
  Users receive no email claim when their mail attribute is empty, which is common for cloud-only
  accounts, or when it is set to an address on an unverified domain, which is common in test
  directories. Set the **Email** field on the user's properties to an address on one of the
  directory's verified domains to include it. Users without an email claim can still complete the
  flow by entering their email address during enrollment.
</Info>

Entra ID does not include phone numbers in the tokens it sends to external providers. Users enrolling an SMS authenticator enter their phone number during their first challenge and verify it with a one-time code.

<Info>
  Entra ID abandons a sign-in attempt around 5 minutes after redirecting to the external provider, so
  challenges need to be completed within that window. Users signing in must be members of the
  directory where the method is configured. We recommend testing with a member account rather than a
  guest account from another directory.
</Info>

## Changing the configuration

Microsoft caches the external provider's metadata for up to 24 hours. If you re-activate the integration on a different Authsignal tenant, or the discovery endpoint changes, delete the external method in Entra ID and add it again with the new values.

Deleting a method orphans any user registrations that reference it. If a user who registered against a deleted method can no longer sign in, remove their external method registration (in the Entra admin center, open the user, then **Authentication methods**) and have them register again.

## Troubleshooting

| Error                                                                                                                | Cause and resolution                                                                                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AADSTS50166: Request to External OIDC endpoint failed`                                                              | Entra ID could not fetch the discovery document. Confirm the Discovery Endpoint in the method configuration exactly matches the value shown in the Authsignal Portal, including the Authsignal tenant ID.                                                                                                                                                   |
| `AADSTS5001255: Failed to validate authorization url`                                                                | The Authsignal `authorize` endpoint is not registered as a Web redirect URI on the application registration, or does not match exactly.                                                                                                                                                                                                                     |
| `AADSTS900491: Service principal not found`                                                                          | Admin consent has not been granted for the application in the directory using the method.                                                                                                                                                                                                                                                                   |
| `AADSTS501581: The selected external provider authentication method configuration does not exists or is not enabled` | The method is disabled or the user is not targeted on the **Enable and target** tab, the user's registration references a method that was deleted and re-added, or the user is a guest from outside the directory. Remove the user's external method registration and have them register again against the current method.                                  |
| The Authsignal method does not appear in the picker                                                                  | The user is not targeted on the method, or nothing in the sign-in requires MFA. Confirm a Conditional Access policy with the **Require multifactor authentication** grant applies to the sign-in.                                                                                                                                                           |
| Email is not pre-filled during enrollment                                                                            | The user has no **mail** attribute set in the directory, the address is on a domain the directory has not verified, or the `email` permission and optional claim are not configured on the application registration. Set the Email field on the user's properties to an address on a verified domain, or have the user enter their email during enrollment. |