Custom authentication extensions overview

The Microsoft Entra ID authentication pipeline consists of several built-in authentication events, like the validation of user credentials, conditional access policies, multifactor authentication, self-service password reset, and more.

Microsoft Entra custom authentication extensions allow you to extend authentication flows with your own business logic at specific points within the authentication flow. A custom authentication extension is essentially an event listener that, when activated, makes an HTTP call to a REST API endpoint where you define a workflow action.

For example, you could use a custom claims provider to add external user data to the security token before the token is issued. You could add an attribute collection workflow to validate the attributes a user enters during sign-up. This article provides a high-level, technical overview of Microsoft Entra ID custom authentication extensions.

The Microsoft Entra Custom Authentication Extension Overview video provides a comprehensive outline of the key features and capabilities of the custom authentication extensions.

Components overview

There are two components you need to configure: a custom authentication extension in Microsoft Entra and a REST API. The custom authentication extension specifies your REST API endpoint, when the REST API should be called, and the credentials to call the REST API.

This video provides detailed instructions on configuring Microsoft Entra custom authentication extensions and offers best practices and valuable tips for optimal implementation.

Sign-in flow

The following diagram depicts the sign-in flow integrated with a custom authentication extension.

1. A user attempts to sign into an app and is redirected to the Microsoft Entra sign-in page.
2. Once a user completes a certain step in the authentication, an event listener is triggered.
3. Your custom authentication extension sends an HTTP request to your REST API endpoint. The request contains information about the event, the user profile, session data, and other context information.
4. The REST API performs a custom workflow.
5. The REST API returns an HTTP response to Microsoft Entra ID.
6. The Microsoft Entra custom authentication extension processes the response and customizes the authentication based on the event type and the HTTP response payload.
7. A token is returned to the app.

REST API endpoints

When an event is triggered, Microsoft Entra ID invokes a REST API endpoint that you own. The REST API must be publicly accessible. It can be hosted using Azure Functions, Azure App Service, Azure Logic Apps, or another publicly available API endpoint.

You have the flexibility to use any programming language, framework, or low-code-no-code solution, such as Azure Logic Apps to develop and deploy your REST API. For a quick way to get started, consider employing Azure Function. It lets you run your code in a serverless environment without having to first create a virtual machine (VM) or publish a web application.

Your REST API must handle:

• Token validation for securing the REST API calls.
• Business logic
• Return data and action type
• Incoming and outgoing validation of HTTP request and response schemas.
• Auditing and logging.
• Availability, performance, and security controls.

Request payload

The request to the REST API includes a JSON payload containing details about the event, user profile, authentication request data, and other context information. The attributes within the JSON payload can be used to perform logic by your API.

For example, in the Token issuance start event, the request payload may include the user's unique identifier, allowing you to retrieve the user profile from your own database. The request payload data must follow the schema as specified in the event document.

Return data and action type

After your web API performs the workflow with your business logic, it must return an action type that directs Microsoft Entra on how to proceed with the authentication process.

For example, in the case of the attribute collection start and attribute collection submit events, the action type returned by your web API indicates whether the account can be created in the directory, show a validation error, or completely block the sign-up flow.

The REST API response may include data. For example, the on token issuance start event may provide a set of attributes that can be mapped to the security token.

Protect your REST API

To ensure the communications between the custom authentication extension and your REST API are secured appropriately, multiple security controls must be applied.

1. When the custom authentication extension calls your REST API, it sends an HTTP Authorization header with a bearer token issued by Microsoft Entra ID.
2. The bearer token contains an appid or azp claim. Validate that the respective claim contains the 99045fe1-7639-4a75-9d4a-577b6ca3810f value. This value ensures that the Microsoft Entra ID is the one who calls the REST API.
   1. For V1 Applications, validate the appid claim.
   2. For V2 Applications, validate the azp claim.
3. The bearer token aud audience claim contains the ID of the associated application registration. Your REST API endpoint needs to validate that the bearer token is issued for that specific audience.
4. The bearer token iss issuer claim contains the Microsoft Entra issuer URL. Depending on your tenant configuration, the issuer URL is one of the following;
   • Workforce: https://login.microsoftonline.com/{tenantId}/v2.0.
   • Customer: https://{domainName}.ciamlogin.com/{tenantId}/v2.0.

Custom authentication event types

This section lists the custom authentication extensions events available in Microsoft Entra ID workforce and external tenants. For detailed information about the events, refer to the respective documentation.

Event	Workforce tenant	External tenant
Token issuance start
Attribute collection start
Attribute collection submit
One time passcode send

Token issuance start

The token issuance start event, OnTokenIssuanceStart is triggered when a token is about to be issued to an application. It is an event type set up within a custom claims provider. The custom claims provider is a custom authentication extension that calls a REST API to fetch claims from external systems. A custom claims provider maps claims from external systems into tokens and can be assigned to one or many applications in your directory.

Attribute collection start

Attribute collection start events can be used with custom authentication extensions to add logic before attributes are collected from a user. The OnAttributeCollectionStart event occurs at the beginning of the attribute collection step, before the attribute collection page renders. It lets you add actions such as prefilling values and displaying a blocking error.

Attribute collection submit

Attribute collection submit events can be used with custom authentication extensions to add logic after attributes are collected from a user. The OnAttributeCollectionSubmit event triggers after the user enters and submits attributes, allowing you to add actions like validating entries or modifying attributes.

One time passcode send

The OnOtpSend event is triggered when a one time passcode email is activated. It allows you to call a REST API to use your own email provider. This event can be used to send customized emails to users who sign up, reset their password, or sign-in with email and one-time passcode.

When the OnOtpSend event is activated, Microsoft Entra sends a one-time passcode to the specified REST API you own. The REST API then uses your chosen email provider, such as Azure Communication Service or SendGrid, to send the one-time passcode with your custom email template, from address, and email subject, while also supporting localization.

Related content

• Learn more about custom claims providers
• Create custom authentication extensions for attribute collection start and submit events with a sample OpenID Connect application
• Configure a custom email provider for one time passcode send events