Microsoft Azure Webjobs Extensions Authentication Events Dotnet

作者 microsoft354361d83247MIT收錄於 2026年10月8日更新於 2026年10月8日

Microsoft Entra Authentication Events SDK for .NET. Azure Functions triggers for custom authentication extensions. Use for token enrichment, custom claims, attribute collection, and OTP customization in Entra ID. Triggers: "Authentication Events", "WebJobsAuthenticationEventsTrigger", "OnTokenIssuanceStart", "OnAttributeCollectionStart", "custom claims", "token enrichment", "Entra custom extension", "authentication extension".

精選僅含說明Software Development Security

AI 產生的概覽

指導 .NET 開發人員建置可處理 Microsoft Entra ID 自訂驗證事件的 Azure Functions。

功能: 此技能說明 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents .NET 套件，並示範如何撰寫由 Entra ID 驗證事件觸發的 Azure Functions。內容涵蓋以自訂宣告擴充權杖、屬性收集的開始與提交處理，以及自訂 OTP 傳送，並為每種事件類型提供 C# 程式碼範例。此外還包含 Function App 組態檔、關鍵類型參考、Entra ID 註冊步驟與錯誤處理指引。
適用情境: 適用於在 .NET 中實作 Entra ID 自訂驗證擴充的情境，例如將自訂宣告加入權杖、在註冊過程中自訂或驗證屬性收集，或透過自訂管道傳送一次性密碼。適合需要這些事件具體觸發程序與回應模式的開發人員。
執行需求: 需要 .NET SDK 與 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents NuGet 套件，以及一個 Azure Functions 專案。部署並串接此擴充功能需要 Azure 訂用帳戶、具備 CustomAuthenticationExtension.Receive.Payload 範圍的 Entra ID 應用程式註冊，以及存取外部資料或 OTP 提供者所需的網路連線。此技能不含指令碼，僅為指示與程式碼範例。

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

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

Installation

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

1. Token Enrichment (Add Custom Claims)

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

csharp

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<string, string>            {                { "customClaim1", "customValue1" },                { "department", "Engineering" },                { "costCenter", "CC-12345" },                { "apiVersion", "v2" }            }        });
        return response;    }}

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<string, string>            {                { "customClaim1", "customValue1" },                { "department", "Engineering" },                { "costCenter", "CC-12345" },                { "apiVersion", "v2" }            }        });
        return response;    }}

2. Token Enrichment with External Data

Fetch claims from external systems (databases, APIs).

csharp

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;using Microsoft.Extensions.Logging;using System.Net.Http;using System.Text.Json;
public static class TokenEnrichmentWithExternalData{    private static readonly HttpClient _httpClient = new();
    [FunctionName("OnTokenIssuanceStartExternal")]    public static async Task<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<string, string>            {                { "employeeId", userProfile.EmployeeId },                { "department", userProfile.Department },                { "roles", string.Join(",", userProfile.Roles) }            }        });
        return response;    }
    private static async Task<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<UserProfile>(json)!;    }}
public record UserProfile(string EmployeeId, string Department, string[] Roles);

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart;using Microsoft.Extensions.Logging;using System.Net.Http;using System.Text.Json;
public static class TokenEnrichmentWithExternalData{    private static readonly HttpClient _httpClient = new();
    [FunctionName("OnTokenIssuanceStartExternal")]    public static async Task<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<string, string>            {                { "employeeId", userProfile.EmployeeId },                { "department", userProfile.Department },                { "roles", string.Join(",", userProfile.Roles) }            }        });
        return response;    }
    private static async Task<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<UserProfile>(json)!;    }}
public record UserProfile(string EmployeeId, string Department, string[] Roles);

3. Attribute Collection - Customize UI (Start Event)

Customize the attribute collection page before it's displayed.

csharp

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;using Microsoft.Extensions.Logging;
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<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;    }}

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;using Microsoft.Extensions.Logging;
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<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;    }}

4. Attribute Collection - Validate Submission (Submit Event)

Validate and modify attributes after user submission.

csharp

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;using Microsoft.Extensions.Logging;
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 < 3)        {            response.Actions.Add(new WebJobsShowValidationError            {                Message = "Display name must be at least 3 characters.",                AttributeErrors = new Dictionary<string, string>                {                    { "displayName", "Name is too short" }                }            });            return response;        }
        // Modify attributes before saving        response.Actions.Add(new WebJobsModifyAttributeValues        {            Attributes = new Dictionary<string, string>            {                { "displayName", displayName.Trim() },                { "city", attributes?["city"]?.ToString()?.ToUpperInvariant() ?? "" }            }        });
        return response;    }}

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;using Microsoft.Extensions.Logging;
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 < 3)        {            response.Actions.Add(new WebJobsShowValidationError            {                Message = "Display name must be at least 3 characters.",                AttributeErrors = new Dictionary<string, string>                {                    { "displayName", "Name is too short" }                }            });            return response;        }
        // Modify attributes before saving        response.Actions.Add(new WebJobsModifyAttributeValues        {            Attributes = new Dictionary<string, string>            {                { "displayName", displayName.Trim() },                { "city", attributes?["city"]?.ToString()?.ToUpperInvariant() ?? "" }            }        });
        return response;    }}

5. Custom OTP Delivery

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

csharp

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;using Microsoft.Extensions.Logging;
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;    }}

using Microsoft.Azure.WebJobs;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents;using Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework;using Microsoft.Extensions.Logging;
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;    }}

6. Function App Configuration

Configure the Function App for authentication events.

csharp

// Program.cs (Isolated worker model)using Microsoft.Extensions.Hosting;
var host = new HostBuilder()    .ConfigureFunctionsWorkerDefaults()    .Build();
host.Run();

// Program.cs (Isolated worker model)using Microsoft.Extensions.Hosting;
var host = new HostBuilder()    .ConfigureFunctionsWorkerDefaults()    .Build();
host.Run();

json

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

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

json

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

// 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)

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

csharp

[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();    }}

[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/skills位於.github/plugins/azure-sdk-dotnet/skills/microsoft-azure-webjobs-extensions-authentication-events-dotnet提交354361d

授權條款： MIT

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

Microsoft Azure Webjobs Extensions Authentication Events Dotnet

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

Installation

Supported Events

Core Workflows

1. Token Enrichment (Add Custom Claims)

2. Token Enrichment with External Data

3. Attribute Collection - Customize UI (Start Event)

4. Attribute Collection - Validate Submission (Submit Event)

5. Custom OTP Delivery

6. Function App Configuration

Key Types Reference

Entra ID Configuration

Required App Registration Settings

Best Practices

Error Handling

Related SDKs

Reference Links

來源與署名

更多來自 microsoft/skills 的技能

Customize

Discover Azure Skills

Azure Resource Visualizer

Azure Resource Lookup

Azure Messaging

Azure Kusto

更多Software Development技能

Playground

M5 Onboard

Cardputer Buddy

Dpop Adoption

Gemini Live Api

Gemini Api