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

Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents（.NET）

用于处理 Microsoft Entra ID 自定义身份验证事件的 Azure Functions 扩展。

安装

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

请固定到经过审核且与所选 Functions 主机兼容的程序包版本。Microsoft 设置指南将此 NuGet 集成描述为预览版；不要据此推断其稳定性。

支持的事件

事件	用途
OnTokenIssuanceStart	在颁发令牌时向令牌添加自定义声明
OnAttributeCollectionStart	在显示属性收集 UI 之前对其进行自定义
OnAttributeCollectionSubmit	在用户提交属性后对其进行验证／修改
OnOtpSend	自定义 OTP 发送方式（短信、电子邮件等）

身份验证和响应前提条件

根据官方设置，使用实际租户／扩展配置 AuthenticationEvents__AudienceAppId、AuthenticationEvents__AuthorityUrl 和 AuthenticationEvents__AuthorizedPartyAppId。在访问数据或返回声明之前，验证请求的身份验证／状态；不要假设触发器被调用就意味着令牌／架构已成功验证。使用 SDK 记录的响应／错误模式拒绝无效请求。Graph User.Read 不能替代对 Entra 回调的身份验证。

示例彼此独立，需要根据程序包版本补充相应的命名空间、请求类型、System／Collections／Tasks 导入，以及所需的 SDK 操作集合初始化。请核实已安装 SDK 支持的事件名称／类型；此处未确认示例能够通过构建。声明和角色必须来自经授权且绑定到租户的数据源；示例中的 Engineering／roles 是合成数据，并非用户权限。不要记录 OTP、电话号码、令牌或原始异常负载。缓存应考虑租户／用户／版本，并限制已身份验证的外部调用。缺失／无效的必需声明必须由信赖方应用拒绝访问，不得默默授予访问权限。

核心工作流

1. 令牌增强（添加自定义声明）

在登录期间向访问令牌或 ID 令牌添加自定义声明。

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

public static class TokenEnrichmentFunction
{
    [FunctionName("OnTokenIssuanceStart")]
    public static WebJobsAuthenticationEventResponse Run(
        [WebJobsAuthenticationEventsTrigger] WebJobsTokenIssuanceStartRequest request)
    {
        try
        {
            if (request.RequestStatus != WebJobsAuthenticationEventsRequestStatusType.Successful)
                return request.Completed(); // SDK preserves validation failure; do not add claims.
            request.Response.Actions.Add(new WebJobsProvideClaimsForToken(
                new WebJobsAuthenticationEventsTokenClaim("apiVersion", "v2")));
            return request.Completed();
        }
        catch (Exception ex)
        {
            return request.Failed(ex);
        }
    }
}

apiVersion 值是合成示例，不代表用户权限。必需声明必须在 Entra 扩展／应用程序中映射，并由信赖方应用强制执行。无需记录原始用户／异常信息。

2. 使用外部数据增强令牌

从外部系统（数据库、API）获取声明。

在读取用户上下文之前，先使用上述已身份验证的请求检查机制。从经过验证的事件中解析租户和用户 ID；查询经授权且绑定到租户的配置文件适配器，并将超时时间设在回调预算内，同时限制响应大小并验证架构。使用 WebJobsAuthenticationEventsTokenClaim 和 request.Response.Actions 添加每个已批准的值，然后返回 request.Completed()。如果缺少／无效的必需配置文件数据，则返回 request.Failed(exception)，并要求信赖方应用拒绝缺失声明的请求。不要拼接来自不可信输入的角色字符串，也不要返回新的空成功响应。配置文件适配器、身份验证和角色映射属于应用程序代码，此处不提供。

3. 属性收集和 OTP 发送

这些事件取决于租户、产品和版本。之前的示例假设了未经验证的请求／操作构造函数和空操作 SMS 适配器；不能将它们照搬为可编译的 SDK 集成。对于已安装的包，请使用其官方的事件专用示例，并在访问属性或 OTP 上下文之前验证请求身份验证／状态门控。

• 开始：仅预填已批准的属性；不要信任客户端提供的身份，也不要将预填内容用作授权决策。
• 提交：验证完整的事件架构和允许的属性字段，返回事件文档中规定的验证／阻止操作，并保留用户更正输入的能力。仅显示消息无法强制执行策略。
• OTP：仅通过已配置且经过身份验证的提供程序发送；验证目标地址和质询上下文，限制尝试次数和超时时间，并且只有在提供程序接受后才报告成功。切勿记录或持久化 OTP 值，也不要通过 Task.CompletedTask 默默声称已发送。
• 使用合成的本地测试数据。在所有已部署环境中，将 AuthenticationEvents__BypassTokenValidation 保持为禁用状态；本地绕过测试无法验证生产环境的身份验证。

关键类型参考

经过验证的令牌颁发模式使用 WebJobsTokenIssuanceStartRequest、WebJobsAuthenticationEventsRequestStatusType、WebJobsProvideClaimsForToken 和 WebJobsAuthenticationEventsTokenClaim，并通过 request.Response、request.Completed() 和 request.Failed(exception) 操作。对于所有其他事件专用名称，请在已安装的包中确认，不要根据事件标签推断。

Entra ID 配置

部署 Function App 后，在 Entra ID 中配置自定义扩展：

1. 注册 API：在 Entra ID → App registrations 中
2. 创建 Custom Authentication Extension：在 Entra ID → External Identities → Custom authentication extensions 中
3. 链接到 User Flow：在 Entra ID → External Identities → User flows 中

必需的应用注册设置

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

API Permissions:
  - Microsoft Graph: User.Read (delegated)

最佳实践

1. 验证所有输入 — 切勿信任请求数据；处理前先进行验证
2. 妥善处理错误 — 返回适当的错误响应
3. 记录关联 ID — 使用 CorrelationId 进行故障排查
4. 保持函数快速 — 身份验证事件有超时限制
5. 使用托管标识 — 安全访问 Azure 资源
6. 缓存外部数据 — 避免每次请求都进行缓慢查询
7. 在本地测试 — 使用 Azure Functions Core Tools 和示例负载
8. 使用 App Insights 进行监视 — 跟踪函数执行情况和错误

错误处理

使用上文经过保护的令牌颁发函数：保留 SDK 验证状态，仅对 Successful 请求填充 request.Response，并在处理失败时使用 request.Failed(exception)。不要用新的 WebJobsTokenIssuanceStartResponse() 替换失败，也不要记录原始回调／异常负载。

相关 SDK

SDK	用途	安装
Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents	身份验证事件（此 SDK）	dotnet add package Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents
Microsoft.Identity.Web	Web 应用身份验证	dotnet add package Microsoft.Identity.Web
Azure.Identity	Azure 身份验证	dotnet add package Azure.Identity

参考链接

资源	URL
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

适用场景

当需要执行概述中描述的工作流或操作时，可使用此技能。

限制

• 仅当任务明确符合上述范围时，才使用此技能。
• 不要将输出视为针对特定环境进行验证、测试或专家审查的替代方案。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停止并请求澄清。

已验证的令牌颁发 API 形式：Microsoft 设置指南。其他事件工作流仍是程序性集成要求，并非已编译的实现。