Extend Azure Authentication Events

This skill covers Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents (currently v1.1.0, stable), an Azure Functions extension for handling Microsoft Entra ID custom authentication events. It supports four events: OnTokenIssuanceStart (add custom claims to tokens during issuance), OnAttributeCollectionStart (customize the attribute collection UI before it's displayed), OnAttributeCollectionSubmit (validate or modify attributes after user submission), and OnOtpSend (custom one-time-password delivery via SMS, email, or another channel).

It documents six core workflows with working C# examples. Token Enrichment adds custom claims (department, cost center, API version, etc.) to a token via a WebJobsProvideClaimsForToken action on OnTokenIssuanceStart. Token Enrichment with External Data fetches claims from an external API (using HttpClient and JsonSerializer) before adding them to the token. Attribute Collection Start customizes the pre-display UI with three response options: continue with default behavior, prefill attribute values, or show a blocking page to prevent sign-up. Attribute Collection Submit validates and modifies submitted attributes after the user submits them - examples include blocking sign-ups from a given email domain, returning a validation error for a too-short display name, and normalizing/trimming attribute values before saving. Custom OTP Delivery sends a one-time code through a custom channel (the example stubs an SMS provider call) and returns explicit success or failure actions. Function App Configuration shows the isolated-worker Program.cs host setup plus host.json (with Application Insights sampling and an empty HTTP route prefix) and local.settings.json for local development.

A Key Types Reference table lists the trigger attribute and the request/response/action types for each event: WebJobsAuthenticationEventsTriggerAttribute, WebJobsTokenIssuanceStartRequest/Response, WebJobsProvideClaimsForToken, WebJobsAttributeCollectionStartRequest/Response, WebJobsSetPrefillValues, WebJobsShowBlockPage, WebJobsShowValidationError, WebJobsModifyAttributeValues, WebJobsOnOtpSendRequest/Response/Success/Failed, and WebJobsContinueWithDefaultBehavior. Beyond the code, deployment requires configuring Entra ID: registering the API under App registrations, creating the custom authentication extension under External Identities, and linking it to a user flow, with the app registration exposing an API at api://<your-function-app-name>.azurewebsites.net with scope CustomAuthenticationExtension.Receive.Payload and the Microsoft Graph User.Read delegated permission.

Best practices called out: validate all inputs since request data should never be trusted, handle errors gracefully with appropriate responses, log CorrelationId for troubleshooting, keep functions fast given authentication events have timeout limits, use managed identity for secure Azure resource access, cache external data to avoid slow per-request lookups, test locally with Azure Functions Core Tools and sample payloads, and monitor with Application Insights. The error-handling example shows catching exceptions and returning an empty response rather than throwing, since throwing would fail the authentication flow entirely. Related SDKs referenced: Microsoft.Identity.Web for web app authentication and Azure.Identity for Azure authentication.

Use when implementing Microsoft Entra ID custom authentication event handlers on Azure Functions - enriching tokens with custom claims, customizing or validating the attribute-collection sign-up UI, or delivering OTPs through a custom channel. Not applicable outside the Entra ID custom authentication extension scope.

Input is a .NET Azure Functions project (isolated worker model). Output is a deployed Function App exposing the appropriate authentication-event functions, registered in Entra ID as a custom authentication extension and linked to a user flow.

dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents

Microsoft Entra ID (App registrations, External Identities custom authentication extensions, user flows, Microsoft Graph), Azure Functions (isolated worker model, Application Insights), and related SDKs Microsoft.Identity.Web and Azure.Identity.

.NET developers building Entra ID sign-up/sign-in customizations on Azure Functions - adding custom token claims, gating or validating attribute collection, or wiring up custom OTP delivery.