Microsoft Entra External ID
Authentication

Custom Authentication Extensions

In brief

The documentation now maps custom extension events to authentication approaches and covers attribute collection, email passcode delivery, and token issuance. It also clarifies unsupported scenarios such as password migration hooks and password-update synchronization.

What Entra admins need to know

Use the event comparison to verify that an event is supported for your selected authentication approach and API or SDK version.

This editorial summary was generated by AI from the documentation changes. Verify important details in the full Microsoft Learn article.

Documentation change

The comparison below shows only the changed extract. Use the full-page view for complete context.

#Customer intent: As a dev, devops, or it admin, I want to know


ExtendCustom authentication flows with your ownextensions in Microsoft Entra External ID

Custom authentication extensions add business logic

[!INCLUDE applies-to-external-only]

at specific events in Microsoft Entra External ID user flows are designed for flexibility. Within a sign-up and sign-in user flow, there are built-in authentication events. You can also add custom authentication extensions at specific points within the authentication flow. A custom authenticationflows. An extension is essentiallylistens for an event listener that, when activated, makes an HTTP call toand calls a REST API endpoint where you define a workflow action. For example, you couldan extension can validate submitted sign-up attributes or add claims from an attribute collection workflow to validateexternal system before token issuance.

[!INCLUDE authentication-approaches]

Event coverage by authentication approach

[!INCLUDE native-authentication-public-preview]

Tenant, application, and user-flow configuration define the attributesextension and the event listener. The event also needs a user enters during sign-up,supported execution point in the selected integration. Sharing tenant policies doesn't imply that every authentication approach executes every event.

Confirm event availability for your approach and API or you could use a custom claims provider to add external user data toSDK version in the token beforecustom authentication extension event comparison.

Use the token is issued.

event's documented inputs and responses. Support for the four documented events doesn't establish password-migration hooks, password-update synchronization, or arbitrary context propagation. For architectural guidance, see Choose an authentication approach.

There areConfigure two components you need to configure:components: a custom authentication extension and a REST API. The custom authentication extension specifies yourthe REST API endpoint, when the REST API should be called,to call it, and the credentials to callfor the REST API.call. You can create custom authentication extensions at the following points in the authentication flow:

  • During sign-up, before or after attribute collection:
    • The OnAttributeCollectionStart event occurs at the beginning of the attribute collection step, before the attribute collection page renders.collection.
    • The OnAttributeCollectionSubmit event occurs after the user enters and submits attributes.
    When sending an email one-time passcode through a configured email provider.
  • Upon token issuance usingissuance, before the OnTokenIssuanceStart event, which triggers just before a token is issuedconfigured claims are added to the application.application's token.

:::image type="content" source="media/concept-custom-extensions/authentication-flow-events-inline.png" alt-text="Diagram showing extensibility points in the authentication flow.of attribute collection and token issuance extension points." lightbox="media/concept-custom-extensions/authentication-flow-events-expanded.png" border="false":::

If you have a custom authentication extension configured at one of these points,When an applicable event runs, Microsoft Entra ID makes a call to thecalls your REST API you define.with the event's defined payload. The request to the REST API contains information aboutreturns one of the event,actions supported by that event. Use the user profile, authentication request data, and otherevent's documented payload to determine which application context information. In turn, the REST API performs the workflow actions.

This article provides an overview of custom authentication extensions in Microsoft Entra External ID.is available.

Attribute collection start and submit events

You can use customUse these events with Microsoft-hosted authentication extensions to add workflows toprefill fields, validate entries, modify attributes, or block self-service sign-up. OnAttributeCollectionStart and OnAttributeCollectionSubmit aren't supported for Embedded native authentication or Bring Your Own UX. Ordinary attribute collection in your self-service sign-up user flows. For example, you can prefill attribute fields with custom values, validate a userthrough the Native Authentication API doesn's entries, and modify attributes, and display errors. Two events are enabled:t enable these extension events; follow the attribute collection contract instead.

  • OnAttributeCollectionStart - The OnAttributeCollectionStart event occurs at the beginning of the attribute collection process before the attribute collection page renders. This event runs before attribute collection. It can be usedprefill attributes or block sign-up, for scenarios like preventing the user from signing upexample based on their domain or adding attributes to be collected.the customer's email domain. The following scenarios are configurable for the OnAttributeCollectionStart event:supported actions are:

    • continueWithDefaultBehavior - RenderContinue with the configured attribute collection page as usual.collection.
    • setPreFillValues - Prefill attributes in the sign-up form.
    • showBlockPage - Show an error message and block the user from signing up.

For details, see Add attribute collection custom extensions to your user flow.

For attribute collection without these extension events, see Native authentication user attributes.

Email one-time passcode send event

The OnOtpSend event lets a configured provider send email one-time passcodes. It doesn't register an MFA method or make email eligible as both the first and second factor. The service's current transaction still determines the required verification.

For setup, see Configure a custom email provider.

Token issuance start event

The token issuance start event is triggered onceoccurs after a user completes all of their authentication challenges andchallenges, just before a security token is about to be issued.

When users authenticate to your application with Microsoft Entra ID, a security token is returned to your application. The security token contains claims that are statements about the user, such as name, unique identifier, or application roles. Beyond the default set of claims that are contained in the security token, you can define your own custom claims from external systems using a REST API you develop.

Daily Entra.News

Get daily email updates

Get a concise summary of the latest Microsoft Entra updates delivered straight to your inbox.

Loading the secure signup form…