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

用途

Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents 是面向 .NET 的 Azure Functions 扩展，用于在 Microsoft Entra ID（原 Azure AD）的自定义身份验证流程中插入自定义逻辑。它以 Azure Functions 触发器的形式接收 Entra ID 发出的身份验证事件，并返回相应的响应动作。

主要能力

该 SDK 支持的认证事件包括：

事件	用途
OnTokenIssuanceStart	在令牌颁发期间添加自定义声明
OnAttributeCollectionStart	在属性收集界面显示前进行定制
OnAttributeCollectionSubmit	在用户提交后校验或修改属性
OnOtpSend	自定义 OTP 下发（短信、邮件等）

围绕这些事件，SDK 提供请求、响应与动作类型，例如 WebJobsTokenIssuanceStartRequest / Response、WebJobsProvideClaimsForToken、WebJobsAttributeCollectionStartRequest / Response、WebJobsAttributeCollectionSubmitRequest / Response、WebJobsSetPrefillValues、WebJobsShowBlockPage、WebJobsShowValidationError、WebJobsModifyAttributeValues、WebJobsOnOtpSendRequest / Response、WebJobsOnOtpSendSuccess、WebJobsOnOtpSendFailed、WebJobsContinueWithDefaultBehavior 等。

使用方式

安装命令：

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

当前版本：v1.1.0（稳定版）。

函数以 [WebJobsAuthenticationEventsTrigger] 特性标注触发，函数返回 WebJobsAuthenticationEventResponse。典型流程为：接收请求对象，读取其 Data（如 AuthenticationContext 中的用户 ID、CorrelationId 等），构造对应响应对象，并向其 Actions 集合添加动作后返回。

例如在令牌颁发事件中，可创建 WebJobsTokenIssuanceStartResponse，并向 Actions 添加 WebJobsProvideClaimsForToken，其中的 Claims 为声明字典；也可先经外部数据源（数据库或 API）查询用户档案，再把员工编号、部门、角色等写入声明。

在属性收集开始事件中，可添加 WebJobsContinueWithDefaultBehavior 走默认流程，或添加 WebJobsSetPrefillValues 预填属性值，或以 WebJobsShowBlockPage 阻止注册。在属性提交事件中，可读取 request.Data?.UserSignUpInfo?.Attributes，对邮箱域名进行拦截（WebJobsShowBlockPage）、对显示名称做长度校验（WebJobsShowValidationError，可带 AttributeErrors），或在保存前用 WebJobsModifyAttributeValues 修改属性值。

在自定义 OTP 事件中，可从 request.Data?.OtpContext 获取 Identifier 与 OneTimeCode，调用自有渠道发送验证码，成功则添加 WebJobsOnOtpSendSuccess，失败则添加 WebJobsOnOtpSendFailed 并附上 Error。

函数应用需要相应配置，资料中给出 Isolated worker 模型的 Program.cs 示例（HostBuilder + ConfigureFunctionsWorkerDefaults），以及 host.json 与 local.settings.json 示例（包含 AzureWebJobsStorage、FUNCTIONS_WORKER_RUNTIME 等）。

部署函数应用后，需在 Entra ID 中配置自定义扩展：在“应用注册”中注册 API、在“外部标识 → 自定义身份验证扩展”中创建扩展、并在“外部标识 → 用户流”中关联。所需的“公开 API”配置包含应用 ID URI（api://<your-function-app-name>.azurewebsites.net）与作用域 CustomAuthenticationExtension.Receive.Payload；API 权限包含 Microsoft Graph 的 User.Read（委托）。

适用场景

在登录或注册等身份验证环节需要注入自定义业务逻辑时适用，例如向令牌注入来自外部系统的自定义声明、对注册表单字段做校验或预填、拦截特定邮箱域名、在保存前规范化属性值，或通过自有短信 / 邮件等渠道下发一次性验证码。

最佳实践与限制

资料给出的最佳实践包括：校验所有输入、优雅处理错误、记录 CorrelationId 便于排查、保持函数执行快速（身份验证事件有超时限制）、使用托管标识访问 Azure 资源、缓存外部数据以避免每次请求都做慢查询、使用 Azure Functions Core Tools 以示例负载在本地测试、并通过 App Insights 监控。

错误处理方面，示例建议在函数内使用 try/catch，捕获异常后返回空的响应对象（如 new WebJobsTokenIssuanceStartResponse()），让认证继续而不附加自定义声明；不应抛出异常，否则会导致认证失败。

该技能仅适用于任务与上述范围明确匹配的场景；输出不应替代针对具体环境的验证、测试或专家评审；若缺少必要输入、权限、安全边界或成功标准，应停止并请求澄清。

参考链接

NuGet 包：https://www.nuget.org/packages/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents
自定义扩展概述：https://learn.microsoft.com/entra/identity-platform/custom-extension-overview
令牌颁发事件：https://learn.microsoft.com/entra/identity-platform/custom-extension-tokenissuancestart-setup
属性收集事件：https://learn.microsoft.com/entra/identity-platform/custom-extension-attribute-collection
GitHub 源码：https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/entra/Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents