# Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents (.NET) 用于处理 Microsoft Entra ID 自定义身份验证事件的 Azure Functions 扩展。 ## 安装 dotnet 添加包 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents **当前版本**：v1.1.0（稳定） ## 支持的活动活动 |目的 ---|--- `OnTokenIssuanceStart` |在发行期间向代币添加自定义声明 `OnAttributeCollectionStart` |显示前自定义属性集合UI `OnAttributeCollectionSubmit` |用户提交后验证/修改属性 `OnOtpSend` |自定义 OTP 传送（短信、电子邮件等） ## 核心工作流程 ### 1\.令牌丰富（添加自定义声明）在登录期间添加对访问令牌或 ID 令牌的自定义声明。使用 Microsoft.Azure.WebJobs；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart；使用 Microsoft.Extensions.Logging；公共静态类 TokenEnrichmentFunction { [FunctionName("OnTokenIssuanceStart")] 公共静态 WebJobsAuthenticationEventResponse 运行（ [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest 请求， ILogger日志） { log.LogInformation("用户的令牌发行事件：{UserId}", 请求.Data?.AuthenticationContext?.User?.Id); // 使用自定义声明创建响应 var 响应 = new WebJobsTokenIssuanceStartResponse(); // 向令牌添加声明 response.Actions.Add(new WebJobsProvideClaimsForToken { 声明=新字典<字符串，字符串> { {“customClaim1”，“customValue1”}， { "部门", "工程" }, {“成本中心”，“CC-12345”}， {“api版本”，“v2”} } }); 返回响应； } } ### 2\.利用外部数据丰富代币从外部系统（数据库、API）获取声明。使用 Microsoft.Azure.WebJobs；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.TokenIssuanceStart；使用 Microsoft.Extensions.Logging；使用 System.Net.Http；使用 System.Text.Json；公共静态类 TokenEnrichmentWithExternalData { 私有静态只读 HttpClient _httpClient = new(); [FunctionName("OnTokenIssuanceStartExternal")] 公共静态异步任务 Run( [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest 请求， ILogger日志） { 字符串？ userId = request.Data?.AuthenticationContext?.User?.Id; if (string.IsNullOrEmpty(userId)) { log.LogWarning("请求中没有用户 ID"); 返回新的 WebJobsTokenIssuanceStartResponse(); } // 从外部API获取用户数据 var userProfile = 等待 GetUserProfileAsync(userId); var 响应 = new WebJobsTokenIssuanceStartResponse(); response.Actions.Add(new WebJobsProvideClaimsForToken { 声明=新字典<字符串，字符串> { { "employeeId", userProfile.EmployeeId }, { "部门", userProfile.部门 }, { "roles", string.Join(",", userProfile.Roles) } } }); 返回响应； } 私有静态异步任务 GetUserProfileAsync(string userId) { var response = wait _httpClient.GetAsync($"https://api.example.com/users/{userId}"); 响应.EnsureSuccessStatusCode(); var json = 等待响应.Content.ReadAsStringAsync(); 返回 JsonSerializer.Deserialize(json)!; } } 公共记录 UserProfile(string EmployeeId, string Department, string[] Roles); ### 3\.属性集合 - 自定义 UI（启动事件）在显示属性集合页面之前对其进行自定义。使用 Microsoft.Azure.WebJobs；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework；使用 Microsoft.Extensions.Logging；公共静态类 AttributeCollectionStartFunction { [函数名（“OnAttributeCollectionStart”）] 公共静态 WebJobsAuthenticationEventResponse 运行（ [WebJobsAuthenticationEventsTrigger] WebJobsAttributeCollectionStartRequest 请求， ILogger日志） { log.LogInformation("关联的属性集合开始：{CorrelationId}", request.Data?.AuthenticationContext?.CorrelationId); var 响应 = new WebJobsAttributeCollectionStartResponse(); // 选项 1：继续默认行为 response.Actions.Add(new WebJobsContinueWithDefaultBehavior()); // 选项 2：预填充属性 //response.Actions.Add(new WebJobsSetPrefillValues) // { // 属性 = new Dictionary<字符串, 字符串> // { // { "城市", "西雅图" }, // { “国家”, “美国” } // } // }); // 选项 3：显示阻止页面（阻止注册） //response.Actions.Add(new WebJobsShowBlockPage) // { // Message =“当前已禁用注册。” // }); 返回响应； } } ### 4\.属性集合 - 验证提交（提交事件）用户提交后验证和修改属性。使用 Microsoft.Azure.WebJobs；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework；使用 Microsoft.Extensions.Logging；公共静态类 AttributeCollectionSubmitFunction { [函数名（“OnAttributeCollectionSubmit”）] 公共静态 WebJobsAuthenticationEventResponse 运行（ [WebJobsAuthenticationEventsTrigger] WebJobsAttributeCollectionSubmitRequest 请求， ILogger日志） { var response = new WebJobsAttributeCollectionSubmitResponse(); // 访问提交的属性 var 属性 = request.Data?.UserSignUpInfo?.Attributes; 细绳？电子邮件 = 属性？["电子邮件"]?.ToString(); 细绳？显示名称 = 属性？["显示名称"]?.ToString(); // 验证示例：阻止某些电子邮件域 if (电子邮件?.EndsWith("@blocked.com") == true) { 响应.Actions.Add(new WebJobsShowBlockPage { Message =“不允许从此电子邮件域注册。” }); 返回响应； } // 验证示例：显示验证错误 if (string.IsNullOrEmpty(displayName) || displayName.Length < 3) { 响应.Actions.Add(new WebJobsShowValidationError { Message =“显示名称必须至少包含 3 个字符。”, AttributeErrors = new Dictionary<字符串, 字符串> { { "displayName", "名称太短" } } }); 返回响应； } // 保存前修改属性响应.Actions.Add(new WebJobsModifyAttributeValues { 属性=新字典<字符串，字符串> { { "displayName", displayName.Trim() }, { “城市”，属性？[“城市”]？.ToString()?.ToUpperInvariant() ?? “”} } }); 返回响应； } } ### 5\.定制 OTP 交付通过自定义渠道（短信、电子邮件、推送通知）发送一次性密码。使用 Microsoft.Azure.WebJobs；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents；使用 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents.Framework；使用 Microsoft.Extensions.Logging；公共静态类 CustomOtpFunction { [函数名("OnOtpSend")] 公共静态异步任务 Run( [WebJobsAuthenticationEventsTrigger] WebJobsOnOtpSendRequest 请求， ILogger日志） { var 响应 = new WebJobsOnOtpSendResponse(); 细绳？电话号码 = request.Data?.OtpContext?.Identifier; 细绳？ otp = request.Data?.OtpContext?.OneTimeCode; if (string.IsNullOrEmpty(phoneNumber) || string.IsNullOrEmpty(otp)) { log.LogError("缺少电话号码或 OTP"); 响应.Actions.Add(new WebJobsOnOtpSendFailed { 错误 =“缺少所需数据” }); 返回响应； } 尝试 { // 通过您的短信提供商发送 OTP wait SendSmsAsync(phoneNumber, $"您的验证码是：{otp}"); response.Actions.Add(new WebJobsOnOtpSendSuccess()); log.LogInformation("OTP 成功发送至 {PhoneNumber}",phoneNumber); } catch（异常前） { log.LogError(例如，“发送 OTP 失败”); 响应.Actions.Add(new WebJobsOnOtpSendFailed { 错误=“发送验证码失败” }); } 返回响应； } 私有静态异步任务SendSmsAsync（字符串电话号码，字符串消息） { // 实施您的 SMS 提供商集成（Twilio、Azure 通信服务等）等待任务.CompletedTask; } } ### 6\.功能应用程序配置配置 Function App 的身份验证事件。 // Program.cs（隔离工作模型）使用 Microsoft.Extensions.Hosting； var 主机 = 新的 HostBuilder() .ConfigureFunctionsWorkerDefaults() .Build(); 主机.运行(); // 主机.json { “版本”：“2.0”， “记录”：{ “应用洞察”：{ “采样设置”：{ “已启用”：真 } } }, “扩展”：{ “http”：{ “路由前缀”：“” } } } // 本地.settings.json { “IsEncrypted”：假， “价值观”：{ "AzureWebJobsStorage": "UseDevelopmentStorage=true", "FUNCTIONS_WORKER_RUNTIME": "dotnet" } } ## 按键类型参考类型 |目的 ---|--- `WebJobsAuthenticationEventsTriggerAttribute` |函数触发属性 `WebJobsTokenIssuanceStartRequest` |代币发行事件请求 `WebJobsTokenIssuanceStartResponse` |代币发行事件响应 `WebJobsProvideClaimsForToken` |添加声明的操作 `WebJobsAttributeCollectionStartRequest` |属性收集开始请求 `WebJobsAttributeCollectionStartResponse` |属性收集开始响应 `WebJobsAttributeCollectionSubmitRequest` |属性提交请求 `WebJobsAttributeCollectionSubmitResponse` |属性提交响应 `WebJobsSetPrefillValues` |预填表单值 `WebJobsShowBlockPage` |通过消息阻止用户 `WebJobsShowValidationError` |显示验证错误 `WebJobsModifyAttributeValues` |修改提交的值 `WebJobsOnOtpSendRequest` | OTP 发送事件请求 `WebJobsOnOtpSendResponse` | OTP 发送事件响应 `WebJobsOnOtpSendSuccess` | OTP 发送成功 `WebJobsOnOtpSendFailed` | OTP 发送失败 `WebJobsContinueWithDefaultBehavior` |继续默认流程 ## 内部 ID 配置部署 Function App 后，在 Entra ID 中配置自定义扩展： 1. **在 Entra ID 中注册 API** → 应用程序注册 2. **创建自定义身份验证扩展** 在 Entra ID → 外部身份 → 自定义身份验证扩展中 3. **链接到用户流**，位于 Entra ID → 外部身份 → 用户流 ### 所需的应用程序注册设置公开一个API： - 应用程序 ID URI：api://.azurewebsites.net - 范围：CustomAuthenticationExtension.Receive.Payload API权限： - Microsoft Graph：User.Read（委托） ## 最佳实践 1. **验证所有输入** — 永远不要相信请求数据；处理前验证 2. **优雅地处理错误** — 返回适当的错误响应 3. **记录相关 ID** — 使用 `CorrelationId` 进行故障排除 4. **保持功能快速** - 身份验证事件有超时限制 5. **使用托管身份** — 安全地访问 Azure 资源 6. **缓存外部数据** — 避免每个请求的缓慢查找 7. **本地测试** - 将 Azure Functions Core Tools 与示例负载结合使用 8. **使用 App Insights 进行监控** — 跟踪函数执行和错误 ## 错误处理 [FunctionName("OnTokenIssuanceStart")] 公共静态 WebJobsAuthenticationEventResponse 运行（ [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest 请求， ILogger日志） { 尝试 { // 你的逻辑在这里 var 响应 = new WebJobsTokenIssuanceStartResponse(); response.Actions.Add(new WebJobsProvideClaimsForToken { 声明 = new Dictionary { { "claim", "value" } } }); 返回响应； } catch（异常前） { log.LogError(例如，“处理令牌发行事件时出错”); // 返回空响应 - 身份验证在没有自定义声明的情况下继续 // 不要抛出 - 这会使身份验证失败返回新的 WebJobsTokenIssuanceStartResponse(); } } ## 相关SDK SDK |目的|安装 ---|---|--- `Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents` |身份验证事件（此 SDK）| `dotnet 添加包 Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents` `Microsoft.Identity.Web` | Web 应用程序身份验证 | `dotnet 添加包 Microsoft.Identity.Web` `Azure.Identity` | Azure 身份验证 | `dotnet 添加包 Azure.Identity` ## 参考链接资源 |网址 ---|--- NuGet 包 | 自定义扩展概述 | 代币发行活动 | 属性收集事件 | GitHub 来源 | ## 何时使用此技能适用于执行概述中描述的工作流程或操作。

Microsoft Azure Webjobs 扩展身份验证事件 Dotnet

包含技能