你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 .NET 的 Azure Functions 客户端库的身份验证事件触发器

项目
04/18/2023

Azure Functions 的身份验证事件触发器允许实现自定义扩展来处理 Azure Active Directory (Azure AD) 身份验证事件。身份验证事件触发器处理 Azure AD 身份验证事件的传入 HTTP 请求的所有后端处理，并为开发人员提供：

用于保护 API 调用的令牌验证
对象模型、键入和 IDE Intellisense
API 请求和响应架构的入站和出站验证

入门

安装包

使用 NuGet 安装用于Azure Functions的身份验证事件触发器：

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

先决条件

Azure 订阅：若要使用 Azure 服务（包括Azure Functions），需要订阅。如果没有现有的 Azure 帐户，可以在创建帐户时注册免费试用版或使用 Visual Studio 订阅权益。

验证客户端

当 Azure AD 身份验证事件服务调用自定义扩展时，它会发送带有 Authorization 的 Bearer {token}标头。此令牌表示服务到服务身份验证，其中：

“资源”也称为受众，是注册以表示 API 的应用程序。这由令牌中的 aud 声明表示。
“客户端”是表示 Azure AD 身份验证事件服务的 Microsoft 应用程序。 appId它的值为 99045fe1-7639-4a75-9d4a-577b6ca3810f。这由以下项表示：
- azp如果应用程序accessTokenAcceptedVersion属性设置为 2，则为令牌中的声明。
- appid如果资源应用程序的 accessTokenAcceptedVersion 属性设置为 1 或 null，则为令牌中的声明。

有三种方法可用于对函数应用的 HTTP 请求进行身份验证和验证令牌。

使用 azure AD 身份验证集成Azure Functions验证令牌

在生产环境中运行函数时，强烈建议使用 Azure Functions Azure AD 身份验证集成来验证传入令牌。设置以下函数应用程序设置。

转到函数应用中的“身份验证”选项卡
单击“添加标识提供者”
选择“Microsoft”作为标识提供者
选择“提供现有应用注册的详细信息”
输入 Application ID Azure AD 中表示 API 的应用的

颁发者和允许的受众取决于 accessTokenAcceptedVersion 应用程序的属性， (可以在应用程序) 的“清单”中找到。

如果属性 accessTokenAcceptedVersion 设置为 2：6.设置 Issuer URL to "https://login.microsoftonline.com/{tenantId}/v2.0" 7. Set an 'Allowed Audience' to the Application ID (appId 的)

如果属性accessTokenAcceptedVersion设置为 1 或 null：6。Issuer URL to "https://sts.windows.net/{tenantId}/" 7. Set an 'Allowed Audience' to the Application ID URI (also known as如果使用自定义域名，请将 identifierUri). It should be in the format ofapi://{azureFunctionAppName}.azurewebsites.net/{resourceApiAppId}orapi://{FunctionAppFullyQualifiedDomainName}/{resourceApiAppId}'。

默认情况下，身份验证事件触发器将验证是否已配置 Azure 函数身份验证集成，并将检查令牌中的客户端设置为99045fe1-7639-4a75-9d4a-577b6ca3810f通过azp令牌) 中的或 appid 声明 (。

如果要针对不是 Azure AD 身份验证事件服务的其他客户端（例如使用 Postman）测试 API，可以配置 可选的 应用程序设置：

AuthenticationEvents__CustomCallerAppId - 所需客户端的 GUID。如果未提供， 99045fe1-7639-4a75-9d4a-577b6ca3810f 则假定为。

让触发器验证令牌

在本地环境或未托管在 Azure 函数服务的环境中，触发器可以执行令牌验证。在 local.settings.json 文件中设置以下应用程序设置：

AuthenticationEvents__TenantId - 租户 ID
AuthenticationEvents__AudienceAppId - 与选项 1 中的“允许访问群体”相同的值。
AuthenticationEvents__CustomCallerAppId (可选) - 所需客户端的 GUID。如果未提供， 99045fe1-7639-4a75-9d4a-577b6ca3810f 则假定为。

示例 local.settings.json 文件：

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__TenantId": "8615397b-****-****-****-********06c8",
    "AuthenticationEvents__AudienceAppId": "api://46f98993-****-****-****-********0038",
    "AuthenticationEvents__CustomCallerAppId": "46f98993-****-****-****-********0038"
  }
}

无令牌验证

如果想要在本地开发过程中不对令牌进行身份验证，请在 local.settings.json 文件中设置以下应用程序设置：

AuthenticationEvents__BypassTokenValidation - 的值true将使触发器不检查令牌验证。

快速入门

Visual Studio 2019
- 启动 Visual Studio
- 选择“创建新项目”
- 在模板搜索区域中搜索并选择“AzureAuthEventsTrigger”
- 为项目提供有意义的项目名称、位置、解决方案和解决方案名称。
Visual Studio Code
- 启动 Visual Studio Code
- 通过命令面板运行“创建 Azure 身份验证事件触发器项目”命令
- 按照项目创建提示操作
请注意：首次运行时，下载所需的包可能需要一些时间。
对于开发目的，请轮到用于测试的令牌验证：
将 AuthenticationEvents__BypassTokenValidation 应用程序密钥添加到 local.settings.json 文件中的“值”部分，并将其值设置为 true。如果本地环境中没有 local.settings.json 文件，请在 Function App 的根目录中创建一个。

{
  "IsEncrypted": false,
  "Values": {
    "AzureWebJobsStorage": "UseDevelopmentStorage=true",
    "FUNCTIONS_WORKER_RUNTIME": "dotnet",
    "AuthenticationEvents__BypassTokenValidation": true
  }
}

加载项目后，可以运行示例代码，应会看到 Azure Functions 开发人员的应用程序加载终结点。

关键概念

.NET SDK

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

Azure AD 自定义扩展

使用自定义扩展可以处理 Azure AD 事件、与外部系统集成，并自定义应用程序身份验证体验中发生的情况。例如，自定义声明提供程序是一个自定义扩展，允许你使用来自外部系统的信息来扩充或自定义应用程序令牌，这些信息不能存储为 Azure AD 目录的一部分。

身份验证事件触发器

身份验证事件触发器允许在从 Azure AD 事件服务发送身份验证事件时执行函数。

身份验证事件触发输出绑定

身份验证事件触发器输出绑定允许函数将身份验证事件操作发送到 Azure AD 事件服务。

文档

函数已发布后，可在此处找到有关日志记录和指标的一些良好阅读
有关 API 文档，请参阅 (链接 TBD)
一旦进入预览版，我们除了没有中断性变更外，只需删除指向个人预览版的 NuGet 源即可。

示例

若要测试令牌扩充，请执行以下操作。

启动 Visual Studio。
打开在上一步中创建的项目。 (快速入门)
运行应用程序。 (F5)
启动 Azure Functions 开发人员的应用程序后，复制应用程序启动时显示的侦听 URL。
注意：列出了所有身份验证函数，如果注册了一个名为“OnTokenIssuanceStart”的函数侦听器
然后，函数终结点将是侦听 URL 和函数的组合，例如：“http://localhost:7071/runtime/webhooks/AuthenticationEvents?code=(YOUR_CODE)&function=OnTokenIssuanceStart”
使用 Postman 或 Fiddler 之类的内容发布以下有效负载。
可以在链接 TBD) (找到使用 Postman 的步骤

{
  "type":"microsoft.graph.authenticationEvent.TokenIssuanceStart",
  "source":"/tenants/{tenantId}/applications/{resourceAppId}",
  "data":{
    "@odata.type": "microsoft.graph.onTokenIssuanceStartCalloutData",
    "tenantId": "30000000-0000-0000-0000-000000000003",
    "authenticationEventListenerId1": "10000000-0000-0000-0000-000000000001",
    "customAuthenticationExtensionId": "10000000-0000-0000-0000-000000000002",
    "authenticationContext1":{
      "correlationId": "20000000-0000-0000-0000-000000000002",
      "client": {
        "ip": "127.0.0.1",
        "locale": "en-us",
        "market": "en-au"
      },
      "authenticationProtocol": "OAUTH2.0",
      "clientServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000001",
        "appId": "40000000-0000-0000-0000-000000000002",
        "appDisplayName": "Test client app",
        "displayName": "Test client application"
      },
      "resourceServicePrincipal": {
        "id": "40000000-0000-0000-0000-000000000003",
        "appId": "40000000-0000-0000-0000-000000000004",
        "appDisplayName": "Test resource app",
        "displayName": "Test resource application"
      },
      "user": {
        "companyName": "Nick Gomez",
        "country": "USA",
        "createdDateTime": "0001-01-01T00:00:00Z",
        "displayName": "Dummy display name",
        "givenName": "Example",
        "id": "60000000-0000-0000-0000-000000000006",
        "mail": "test@example.com",
        "onPremisesSamAccountName": "testadmin",
        "onPremisesSecurityIdentifier": "DummySID",
        "onPremisesUserPrincipalName": "Dummy Name",
        "preferredDataLocation": "DummyDataLocation",
        "preferredLanguage": "DummyLanguage",
        "surname": "Test",
        "userPrincipalName": "testadmin@example.com",
        "userType": "UserTypeCloudManaged"
      }
    }
  }
}

应会看到以下响应：

{
    "data": {
        "@odata.type": "microsoft.graph.onTokenIssuanceStartResponseData",
        "actions": [
            {
                "@odata.type": "ProvideClaimsForToken",
                "claims": [
                    {
                        "DateOfBirth": "01/01/2000"
                    },
                    {
                        "CustomRoles": [
                            "Writer",
                            "Editor"
                        ]
                    }
                ]
            }
        ]
    }
}

故障排除

Visual Studio Code
- 如果在 Visual Studio Code 中运行，则本地 Azure 存储模拟器不可用时收到错误，可以手动启动模拟器！！ (注意：Azure 存储模拟器现已弃用，建议替换 Azurite)
- 如果在 Mac 上使用 Visual Studio Code，请使用 Azurite
- 如果在 Windows (尝试运行创建的投影时出现以下错误，则) bug。
- 此问题可以通过在 powershell Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope LocalMachine 中执行此命令来解决。有关此问题的详细信息，请参阅此处和此处

后续步骤

有关 Azure SDK 的详细信息，请参阅此网站

发布

按照此处的说明创建和发布Azure 应用程序。 https://learn.microsoft.com/azure/azure-functions/functions-develop-vs?tabs=in-process#publish-to-azure
若要确定已发布的发布终结点，组合创建的 Azure 函数终结点，路由到侦听器和侦听器代码，可以通过导航到 azure 函数应用程序，选择“应用密钥”并复制AuthenticationEvents_extension的值来找到侦听代码。
例如：“https://azureautheventstriggerdemo.azurewebsites.net/runtime/webhooks/AuthenticationEvents?code=(AuthenticationEvents_extension_key)&function=OnTokenIssuanceStart”
确保生产环境具有正确的令牌身份验证应用程序设置。
再次可以通过将上述有效负载发布到新终结点来测试已发布的函数。

供稿

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

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

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。直接按机器人提供的说明操作。只需使用 CLA 在所有存储库中执行此操作一次。

此项目采用了 Microsoft 开放源代码行为准则。有关详细信息，请参阅行为准则常见问题解答，或如果有任何其他问题或意见，请与联系。

通过