Microsoft Entra External ID EmailOtpSend Custom Authentication Extension Not Invoking API Endpoint

1. Additional configuration for EmailOtpSend to invoke the API

For EmailOtpSend custom authentication extensions, the critical configuration items are:

• A valid custom authentication extension object with:
  • Event type set to EmailOtpSend.
  • targetUrl using HTTPS and in a valid URL format.
  • resourceId referencing a real service principal in the tenant.
  • resourceId and targetUrl sharing the same fully qualified domain name.
• The resource application (API) must expose an app role with value CustomAuthenticationExtension.Receive.Payload and admin consent must be granted to the service principal used by the custom extension.

If any of these are misconfigured, Entra can fail before sending the HTTP request and will surface one of the custom extension error codes. Relevant error codes include:

• 1003015 CustomExtensionDomainNameDoesNotMatch – targetUrl and resourceId must have the same FQDN.
• 1003016 CustomExtensionResourceServicePrincipalNotFound – resourceId appId must correspond to a real service principal.
• 1003018/1003019 – resource or client service principal disabled.
• 1003020 CustomExtensionIncorrectTargetUrlFormat – URL must be valid and start with https.
• 1003021 CustomExtensionPermissionNotGrantedToServicePrincipal – missing admin consent for CustomAuthenticationExtensions.Receive.Payload.

Verifying these conditions and checking for these error codes in sign-in logs is the supported way to confirm that Entra can reach and call the API.

2. Where to view detailed execution logs for EmailOtpSend

Execution and failure details for custom authentication extensions are available in Microsoft Entra sign-in logs:

1. Sign in to the Microsoft Entra admin center.
2. Go to Entra ID → Enterprise apps.
3. Select Sign-in logs, then open the relevant sign-in.
4. Select the Authentication Events tab.

This view shows:

• HTTP status returned by the custom extension API (when the call is made).
• Error code and error name for custom extension failures.
• Execution duration and retry count.

These logs are the primary place to see whether Entra attempted the outbound call and what failed. The same logs can be integrated with Azure Monitor for alerting and visualization.

3. Where token acquisition failures are logged

If Entra fails to acquire or validate the access token for the configured API, the failure is surfaced as a custom extension error in the same sign-in logs under Authentication Events. For example, a timeout or token-related problem can appear as:

• 1003005 CustomExtensionTimedOut – can also indicate that the access token is invalid; guidance is to follow the steps to call the REST API directly.

Use the error code reference in combination with the sign-in logs to pinpoint whether the failure is in token acquisition/validation or in the HTTP call itself.

4. Additional app role / scope / pre-authorization requirements

For custom authentication extensions, the documented requirement is that the resource application expose the CustomAuthenticationExtension.Receive.Payload app role (application permission) and that admin consent be granted to the service principal used by the custom extension:

• Error 1003021 CustomExtensionPermissionNotGrantedToServicePrincipal is raised if this permission is missing.

The error code reference does not list any additional mandatory app roles, scopes, knownClientApplications, or pre-authorized application settings beyond:

• Correct identifierUris format for the resource app (api://{fully qualified domain name}/{appid}) – otherwise error 1003014 CustomExtensionIncorrectResourceIdFormat.
• The CustomAuthenticationExtension.Receive.Payload app role with admin consent.

No further requirements are documented in the provided context.

5. Restrictions when using Azure Application Gateway

The error code reference and troubleshooting guidance for custom authentication extensions focus on:

• URL format and HTTPS requirement (1003020).
• Domain name alignment between targetUrl and resourceId (1003015).
• Service principal existence and state.

There is no documented restriction that the target API must be hosted on Azure Functions or App Service. The guidance explicitly allows “Azure Functions and other API-development platforms” and, for attribute collection events, “an Azure Function, Azure Logic App, or another publicly available API endpoint.”

Therefore, hosting the API behind Azure Application Gateway is supported as long as:

• The endpoint is publicly reachable over HTTPS.
• The FQDN and URL format requirements are met.

6. How to diagnose why no outbound request reaches the API

Based on the available guidance, the recommended diagnostic path is:

1. Use Microsoft Entra sign-in logs → Authentication Events to:
   • Confirm whether the custom extension is invoked.
   • Capture the specific custom extension error code.
2. Compare the error code with the custom extension error code reference to identify configuration issues such as:
   • Domain mismatch (1003015).
   • Invalid identifierUris format (1003014).
   • Missing or unconsented CustomAuthenticationExtension.Receive.Payload permission (1003021).
   • Invalid URL format (1003020).
3. If the error indicates timeout or token issues (1003005), follow the documented approach to call the REST API directly with a Microsoft Entra access token associated with the custom extension’s application registration, using an API testing tool.

These steps, combined with the error codes, are the supported way to determine why Entra is not sending the outbound request.

References:

• Troubleshoot your custom authentication extension
• Configure a custom email provider for one time passcode send events
• Email OTP send event reference
• Extend authentication flows with your own business logic