Microsoft.Azure.WebJobs.Extensions.AuthenticationEvents 1.0.1

Azure Functions 客户端库用于 .NET 的认证事件触发

对于 Azure Functions，认证事件触发器可让您实现自定义扩展来处理 Microsoft Entra 认证事件。认证事件触发器处理所有针对 Microsoft Entra 认证事件的 incoming HTTP 请求的后续处理操作，并为开发人员提供

• 令牌验证以保障 API 调用的安全
• 对象模型、类型和 IDE 代码智能感应
• API 请求和响应模式的入站和出站验证

入门指南

您可以按照以下文章开始创建您的函数： 在 Azure Functions 中为令牌颁发开始事件创建 REST API

安装包

使用 NuGet 安装 Authentication Event 扩展

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

先决条件

• 理解在自定义身份认证扩展概述中涵盖的概念。
• 拥有可创建Azure Function的Azure订阅。如果您还没有现有的Azure账户，可以注册免费试用或使用您在Visual Studio订阅中可用的权益来创建账户。
• 一个Microsoft Entra ID租户。您可以使用客户租户或工作租户来遵循此指南。
• 以下之一IDE和配置
  • 配置了Visual Studio Azure开发工作负载的Visual Studio。
  • 已启用Azure Functions扩展的Visual Studio Code。

客户端认证

为Azure Function设置认证的方式有以下三种

• 使用环境变量在Azure门户中设置认证（推荐）
• 使用WebJobsAuthenticationEventsTriggerAttribute在您的代码中设置认证
• Azure App服务认证和授权

默认情况下，代码已通过环境变量在Azure门户中设置了认证。使用下方的标签选择您首选的环境变量实现方法，或者可以参考内置的Azure App服务认证和授权。设置环境变量时，请使用以下值

使用环境变量在Azure门户中设置认证

1. 以至少是应用程序管理员或认证管理员的身份登录Azure门户。
2. 导航到您创建的函数应用，然后在设置下选择配置。
3. 在应用程序设置下选择新建应用程序设置并添加表格中的环境变量及其关联值。
4. 选择保存以保存应用程序设置。

使用WebJobsAuthenticationEventsTriggerAttribute在您的代码中设置认证

1. 在您的IDE中打开触发器类。
2. 修改WebJobsAuthenticationEventsTriggerAttribute包含AuthorityUrl、AudienceAppId和AuthorizedPartyAppId属性，如下方快照所示。

[FunctionName("onTokenIssuanceStart")]
public static WebJobsAuthenticationEventResponse Run(
[WebJobsAuthenticationEventsTriggerAttribute(
    AudienceAppId = "<custom_authentication_extension_app_id>",
    AuthorityUrl = "<authority_uri>", 
    AuthorizedPartyAppId = "<authorized_party_app_id>")] WebJobsTokenIssuanceStartRequest request, ILogger log)

关键概念

.NET SDK

可以在此处找到Azure .NET SDK的关键概念。

Microsoft Entra自定义扩展

自定义扩展允许您处理Microsoft Entra认证事件，与外部系统集成，并自定义您的应用程序认证体验中发生的事情。例如，自定义声明提供程序是一个允许您使用来自无法存储为Microsoft Entra目录的外部系统的信息丰富或自定义应用程序令牌的自定义扩展。

认证事件触发器

认证事件触发器允许 Microsoft Entra 事件服务发送认证事件时执行一个函数。

认证事件触发器输出绑定

认证事件触发输出绑定允许一个函数将认证事件动作发送到Microsoft Entra事件服务。

创建和构建Azure Function应用

第一步是使用您的集成开发环境（IDE）创建一个HTTP触发函数API，安装所需的NuGet包，并复制以下示例代码。您可以构建项目并运行函数以提取本地函数URL。

示例

函数API是您令牌额外声明的来源。在这个文章的目的上，我们为示例应用硬编码了值。在生产环境中，您可以从外部数据存储中获取有关用户的详细信息。

在您的触发类中（例如： AuthEventsTrigger.cs），在主函数体中添加以下代码段的内容

[FunctionName("onTokenIssuanceStart")]
public static WebJobsAuthenticationEventResponse Run(
[WebJobsAuthenticationEventsTriggerAttribute(
    AudienceAppId = "<custom_authentication_extension_app_id>",
    AuthorityUrl = "<authority_uri>", 
    AuthorizedPartyAppId = "<authorized_party_app_id>")] WebJobsTokenIssuanceStartRequest request, ILogger log)
{
    try
    {
        // Checks if the request is successful and did the token validation pass
        if (request.RequestStatus == WebJobsAuthenticationEventsRequestStatusType.Successful)
        {
            // Fetches information about the user from external data store
            // Add new claims to the token's response
            request.Response.Actions.Add(
                new WebJobsProvideClaimsForToken(
                    new WebJobsAuthenticationEventsTokenClaim("dateOfBirth", "01/01/2000"),
                    new WebJobsAuthenticationEventsTokenClaim("customRoles", "Writer", "Editor"),
                    new WebJobsAuthenticationEventsTokenClaim("apiVersion", "1.0.0"),
                    new WebJobsAuthenticationEventsTokenClaim(
                        "correlationId", 
                        request.Data.AuthenticationContext.CorrelationId.ToString())));
        }
        else
        {
            // If the request fails, such as in token validation, output the failed request status, 
            // such as in token validation or response validation.
            log.LogInformation(request.StatusMessage);
        }
        return request.Completed();
    }
    catch (Exception ex) 
    { 
        return request.Failed(ex);
    }
}

在本地构建和运行项目

在将功能部署到Azure之前，在本地测试功能是一个好主意。我们可以使用一个模拟的JSON主体，该主体模仿Microsoft Entra ID发送到您的REST API的请求。使用您首选的API测试工具直接调用功能。

1. 在您的IDE中，打开 local.settings.json 并替换以下JSON代码。我们可以将 "AuthenticationEvents__BypassTokenValidation" 设置为 true 以进行本地测试。

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "",
    "AzureWebJobsSecretStorageType": "files",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation" : true
  }
}

2. 使用您首选的API测试工具，创建一个新的HTTP请求，并将 HTTP方法 设置为 POST。
3. 使用以下JSON主体，该主体模仿Microsoft Entra ID发送到您的REST API的请求。

{
    "type": "microsoft.graph.authenticationEvent.tokenIssuanceStart",
    "source": "/tenants/30000000-0000-0000-0000-000000000003/applications/40000000-0000-0000-0000-000000000002",
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
        "tenantId": "30000000-0000-0000-0000-000000000003",
        "authenticationEventListenerId": "10000000-0000-0000-0000-000000000001",
        "customAuthenticationExtensionId": "10000000-0000-0000-0000-000000000002",
        "authenticationContext": {
            "correlationId": "20000000-0000-0000-0000-000000000002",
            "client": {
                "ip": "127.0.0.1",
                "locale": "en-us",
                "market": "en-us"
            },
            "protocol": "OAUTH2.0",
            "clientServicePrincipal": {
                "id": "40000000-0000-0000-0000-000000000001",
                "appId": "40000000-0000-0000-0000-000000000002",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "resourceServicePrincipal": {
                "id": "40000000-0000-0000-0000-000000000003",
                "appId": "40000000-0000-0000-0000-000000000004",
                "appDisplayName": "My Test application",
                "displayName": "My Test application"
            },
            "user": {
                "companyName": "Casey Jensen",
                "createdDateTime": "2023-08-16T00:00:00Z",
                "displayName": "Casey Jensen",
                "givenName": "Casey",
                "id": "60000000-0000-0000-0000-000000000006",
                "mail": "[email protected]",
                "onPremisesSamAccountName": "Casey Jensen",
                "onPremisesSecurityIdentifier": "<Enter Security Identifier>",
                "onPremisesUserPrincipalName": "Casey Jensen",
                "preferredLanguage": "en-us",
                "surname": "Jensen",
                "userPrincipalName": "[email protected]",
                "userType": "Member"
            }
        }
    }
}

4. 选择 发送，您应该收到一个类似于以下内容的JSON响应

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "microsoft.graph.tokenIssuanceStart.provideClaimsForToken",
                "claims": {
                    "customClaim1": "customClaimValue1",
                    "customClaim2": [
                        "customClaimString1",
                        "customClaimString2" 
                    ]
                }
            }
        ]
    }
}

部署功能并发布到Azure

一旦测试并通过，就将功能部署到Azure。

故障排除

Visual Studio Code

• 如果正在Visual Studio Code中运行，并且收到类似于本地Azure存储模拟器不可用的错误，您可以通过手动启动模拟器来解决问题。（注意：Azure存储模拟器现已弃用，建议的替代方案是Azurite）
• 如果在使用Mac上的Visual Studio Code，请使用Azurite

Azure功能端点

• 为了确定您的已发布的发布端点，将创建的Azure功能端点、路由到监听器和监听器代码结合起来。监听器代码可以通过在Azure功能应用程序中导航找到，选择“应用程序密钥”并复制AuthenticationEvents_extension的值来查找。
  • 例如："https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)&function=OnTokenIssuanceStart"

下一步

请遵循配置令牌发布事件的自定义声明提供程序来创建一个将调用您的功能的自定义扩展。

有关Azure SDK的更多信息，请参阅此网站

有关部署功能日志和指标的详细信息在此找到

贡献

有关向此存储库贡献的详细信息，请参阅贡献指南。

此项目欢迎贡献和建议。大多数贡献都需要您同意贡献者许可协议（CLA），声明您有权利并实际上确实授权我们使用您的贡献。有关详细信息，请访问https://cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA并以相应的方式标记PR（例如，标签，评论）。只需遵循机器人提供的说明即可。您可能需要在所有使用我们CLA的存储库中只做一次。

本项目已采用微软开源行为准则。如需更多信息，请参阅行为准则常见问题解答，或发邮件至[email protected]咨询或提出任何问题或意见。