microsoft-azure-webjobs-extensions-authentication-events-dotnet

Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents (.NET)

Azure Functions extension for handling Microsoft Entra ID custom authentication events.

Installation

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

Current Version: v1.1.0 (stable)

Supported Events

Event Purpose

OnTokenIssuanceStart

Add custom claims to tokens during issuance

OnAttributeCollectionStart

Customize attribute collection UI before display

OnAttributeCollectionSubmit

Validate/modify attributes after user submission

OnOtpSend

Custom OTP delivery (SMS, email, etc.)

Core Workflows

Token Enrichment (Add Custom Claims)

Add custom claims to access or ID tokens during sign-in.

using Microsoft.Azure.WebJobs; using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents; using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart; using Microsoft.Extensions.Logging;

public static class TokenEnrichmentFunction { [FunctionName("OnTokenIssuanceStart")] public static WebJobsAuthenticationEventResponse Run( [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log) { log.LogInformation("Token issuance event for user: {UserId}", request.Data?.AuthenticationContext?.User?.Id);

    // Create response with custom claims
    var response = new WebJobsTokenIssuanceStartResponse();
    
    // Add claims to the token
    response.Actions.Add(new WebJobsProvideClaimsForToken
    {
        Claims = new Dictionary&#x3C;string, string>
        {
            { "customClaim1", "customValue1" },
            { "department", "Engineering" },
            { "costCenter", "CC-12345" },
            { "apiVersion", "v2" }
        }
    });

    return response;
}

}

Token Enrichment with External Data

Fetch claims from external systems (databases, APIs).

public static class TokenEnrichmentWithExternalData { private static readonly HttpClient _httpClient = new();

[FunctionName("OnTokenIssuanceStartExternal")]
public static async Task&#x3C;WebJobsAuthenticationEventResponse> Run(
    [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request,
    ILogger log)
{
    string? userId = request.Data?.AuthenticationContext?.User?.Id;
    
    if (string.IsNullOrEmpty(userId))
    {
        log.LogWarning("No user ID in request");
        return new WebJobsTokenIssuanceStartResponse();
    }

    // Fetch user data from external API
    var userProfile = await GetUserProfileAsync(userId);
    
    var response = new WebJobsTokenIssuanceStartResponse();
    response.Actions.Add(new WebJobsProvideClaimsForToken
    {
        Claims = new Dictionary&#x3C;string, string>
        {
            { "employeeId", userProfile.EmployeeId },
            { "department", userProfile.Department },
            { "roles", string.Join(",", userProfile.Roles) }
        }
    });

    return response;
}

private static async Task&#x3C;UserProfile> GetUserProfileAsync(string userId)
{
    var response = await _httpClient.GetAsync($"https://api.example.com/users/{userId}");
    response.EnsureSuccessStatusCode();
    var json = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize&#x3C;UserProfile>(json)!;
}

}

public record UserProfile(string EmployeeId, string Department, string[] Roles);

Attribute Collection - Customize UI (Start Event)

Customize the attribute collection page before it's displayed.

public static class AttributeCollectionStartFunction { [FunctionName("OnAttributeCollectionStart")] public static WebJobsAuthenticationEventResponse Run( [WebJobsAuthenticationEventsTrigger] WebJobsAttributeCollectionStartRequest request, ILogger log) { log.LogInformation("Attribute collection start for correlation: {CorrelationId}", request.Data?.AuthenticationContext?.CorrelationId);

    var response = new WebJobsAttributeCollectionStartResponse();

    // Option 1: Continue with default behavior
    response.Actions.Add(new WebJobsContinueWithDefaultBehavior());

    // Option 2: Prefill attributes
    // response.Actions.Add(new WebJobsSetPrefillValues
    // {
    //     Attributes = new Dictionary&#x3C;string, string>
    //     {
    //         { "city", "Seattle" },
    //         { "country", "USA" }
    //     }
    // });

    // Option 3: Show blocking page (prevent sign-up)
    // response.Actions.Add(new WebJobsShowBlockPage
    // {
    //     Message = "Sign-up is currently disabled."
    // });

    return response;
}

}

Attribute Collection - Validate Submission (Submit Event)

Validate and modify attributes after user submission.

public static class AttributeCollectionSubmitFunction { [FunctionName("OnAttributeCollectionSubmit")] public static WebJobsAuthenticationEventResponse Run( [WebJobsAuthenticationEventsTrigger] WebJobsAttributeCollectionSubmitRequest request, ILogger log) { var response = new WebJobsAttributeCollectionSubmitResponse();

    // Access submitted attributes
    var attributes = request.Data?.UserSignUpInfo?.Attributes;
    
    string? email = attributes?["email"]?.ToString();
    string? displayName = attributes?["displayName"]?.ToString();

    // Validation example: block certain email domains
    if (email?.EndsWith("@blocked.com") == true)
    {
        response.Actions.Add(new WebJobsShowBlockPage
        {
            Message = "Sign-up from this email domain is not allowed."
        });
        return response;
    }

    // Validation example: show validation error
    if (string.IsNullOrEmpty(displayName) || displayName.Length &#x3C; 3)
    {
        response.Actions.Add(new WebJobsShowValidationError
        {
            Message = "Display name must be at least 3 characters.",
            AttributeErrors = new Dictionary&#x3C;string, string>
            {
                { "displayName", "Name is too short" }
            }
        });
        return response;
    }

    // Modify attributes before saving
    response.Actions.Add(new WebJobsModifyAttributeValues
    {
        Attributes = new Dictionary&#x3C;string, string>
        {
            { "displayName", displayName.Trim() },
            { "city", attributes?["city"]?.ToString()?.ToUpperInvariant() ?? "" }
        }
    });

    return response;
}

}

Custom OTP Delivery

Send one-time passwords via custom channels (SMS, email, push notification).

public static class CustomOtpFunction { [FunctionName("OnOtpSend")] public static async Task<WebJobsAuthenticationEventResponse> Run( [WebJobsAuthenticationEventsTrigger] WebJobsOnOtpSendRequest request, ILogger log) { var response = new WebJobsOnOtpSendResponse();

    string? phoneNumber = request.Data?.OtpContext?.Identifier;
    string? otp = request.Data?.OtpContext?.OneTimeCode;

    if (string.IsNullOrEmpty(phoneNumber) || string.IsNullOrEmpty(otp))
    {
        log.LogError("Missing phone number or OTP");
        response.Actions.Add(new WebJobsOnOtpSendFailed
        {
            Error = "Missing required data"
        });
        return response;
    }

    try
    {
        // Send OTP via your SMS provider
        await SendSmsAsync(phoneNumber, $"Your verification code is: {otp}");
        
        response.Actions.Add(new WebJobsOnOtpSendSuccess());
        log.LogInformation("OTP sent successfully to {PhoneNumber}", phoneNumber);
    }
    catch (Exception ex)
    {
        log.LogError(ex, "Failed to send OTP");
        response.Actions.Add(new WebJobsOnOtpSendFailed
        {
            Error = "Failed to send verification code"
        });
    }

    return response;
}

private static async Task SendSmsAsync(string phoneNumber, string message)
{
    // Implement your SMS provider integration (Twilio, Azure Communication Services, etc.)
    await Task.CompletedTask;
}

}

Function App Configuration

Configure the Function App for authentication events.

// Program.cs (Isolated worker model) using Microsoft.Extensions.Hosting;

var host = new HostBuilder() .ConfigureFunctionsWorkerDefaults() .Build();

host.Run();

// host.json { "version": "2.0", "logging": { "applicationInsights": { "samplingSettings": { "isEnabled": true } } }, "extensions": { "http": { "routePrefix": "" } } }

// local.settings.json { "IsEncrypted": false, "Values": { "AzureWebJobsStorage": "UseDevelopmentStorage=true", "FUNCTIONS_WORKER_RUNTIME": "dotnet" } }

Key Types Reference

Type Purpose

WebJobsAuthenticationEventsTriggerAttribute

Function trigger attribute

WebJobsTokenIssuanceStartRequest

Token issuance event request

WebJobsTokenIssuanceStartResponse

Token issuance event response

WebJobsProvideClaimsForToken

Action to add claims

WebJobsAttributeCollectionStartRequest

Attribute collection start request

WebJobsAttributeCollectionStartResponse

Attribute collection start response

WebJobsAttributeCollectionSubmitRequest

Attribute submission request

WebJobsAttributeCollectionSubmitResponse

Attribute submission response

WebJobsSetPrefillValues

Prefill form values

WebJobsShowBlockPage

Block user with message

WebJobsShowValidationError

Show validation errors

WebJobsModifyAttributeValues

Modify submitted values

WebJobsOnOtpSendRequest

OTP send event request

WebJobsOnOtpSendResponse

OTP send event response

WebJobsOnOtpSendSuccess

OTP sent successfully

WebJobsOnOtpSendFailed

OTP send failed

WebJobsContinueWithDefaultBehavior

Continue with default flow

Entra ID Configuration

After deploying your Function App, configure the custom extension in Entra ID:

Register the API in Entra ID → App registrations
Create Custom Authentication Extension in Entra ID → External Identities → Custom authentication extensions
Link to User Flow in Entra ID → External Identities → User flows

Required App Registration Settings

Expose an API:

Application ID URI: api://<your-function-app-name>.azurewebsites.net
Scope: CustomAuthenticationExtension.Receive.Payload

API Permissions:

Microsoft Graph: User.Read (delegated)

Best Practices

Validate all inputs — Never trust request data; validate before processing
Handle errors gracefully — Return appropriate error responses
Log correlation IDs — Use CorrelationId for troubleshooting
Keep functions fast — Authentication events have timeout limits
Use managed identity — Access Azure resources securely
Cache external data — Avoid slow lookups on every request
Test locally — Use Azure Functions Core Tools with sample payloads
Monitor with App Insights — Track function execution and errors

Error Handling

[FunctionName("OnTokenIssuanceStart")] public static WebJobsAuthenticationEventResponse Run( [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request, ILogger log) { try { // Your logic here var response = new WebJobsTokenIssuanceStartResponse(); response.Actions.Add(new WebJobsProvideClaimsForToken { Claims = new Dictionary<string, string> { { "claim", "value" } } }); return response; } catch (Exception ex) { log.LogError(ex, "Error processing token issuance event");

    // Return empty response - authentication continues without custom claims
    // Do NOT throw - this would fail the authentication
    return new WebJobsTokenIssuanceStartResponse();
}

}

Related SDKs

SDK Purpose Install

Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents

Auth events (this SDK) dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents

Microsoft.Identity.Web

Web app authentication dotnet add package Microsoft.Identity.Web

Azure.Identity

Azure authentication dotnet add package Azure.Identity

Reference Links

Resource URL

NuGet Package https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents

Custom Extensions Overview https://learn.microsoft.com/entra/identity-platform/custom-extension-overview

Token Issuance Events https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup

Attribute Collection Events https://learn.microsoft.com/entra/identity-platform/custom-extension-attribute-collection

GitHub Source https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents

microsoft-azure-webjobs-extensions-authentication-events-dotnet

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

azure-observability

azure-appconfiguration-java

azure-aigateway

azure-ai-formrecognizer-java