通过

为令牌颁发事件配置自定义声明提供程序

  • 项目

本文介绍如何为令牌颁发启动事件配置自定义声明提供程序。 使用现有的 Azure Functions REST API，你将注册自定义身份验证扩展并添加预期它从 REST API 分析的属性。 要测试自定义身份验证扩展，需要注册一个示例 OpenID Connect 应用程序以获取令牌并查看声明。

先决条件

步骤 1：注册自定义身份验证扩展

现在，你将配置自定义身份验证扩展，以供 Microsoft Entra ID 用于调用你的 Azure 函数。 该自定义身份验证扩展包含有关 REST API 终结点、它从 REST API 分析的声明以及如何对 REST API 进行身份验证的信息。 按照以下步骤将自定义身份验证扩展注册到 Azure 函数应用。

注意

最多可以有 100 个自定义扩展策略。

注册自定义身份验证扩展

  1. 至少以应用程序管理员或身份验证管理员身份登录到 Azure 门户。
  2. 搜索并选择“Microsoft Entra ID”，然后选择“企业应用程序”。
  3. 选择“自定义身份验证扩展”，然后选择“创建自定义扩展”。
  4. 在“基本信息”中选择“TokenIssuanceStart”事件类型，然后选择“下一步”。
  5. 在“终结点配置”中填写以下属性：
    • 名称 - 自定义身份验证扩展的名称。 例如“令牌颁发事件”。
    • 目标 URL - Azure 函数 URL 的 {Function_Url}。 导航到 Azure 函数应用的“概述”页，然后选择创建的函数。 在函数“概述”页中，选择“获取函数 URL”，并使用复制图标复制 customauthenticationextension_extension（系统密钥）URL。
    • 说明 - 自定义身份验证扩展的说明。
  6. 选择“下一页”。
  7. 在“API 身份验证”中，选择“创建新的应用注册”选项以创建代表你的函数应用的应用注册。
  8. 为应用命名，例如“Azure Functions 身份验证事件 API”。
  9. 选择“下一页”。
  10. 在声明中，输入自定义身份验证扩展预期从 REST API 分析的、将合并到令牌中的属性。 添加以下声明：
    • dateOfBirth
    • customRoles
    • apiVersion
    • correlationId
  11. 依次选择“下一步”和“创建”，这会注册该自定义身份验证扩展和关联的应用程序注册。
  12. 请注意“API 身份验证”下的“应用 ID”，需要在 Azure 函数应用中“为 Azure 函数配置身份验证”。

创建自定义身份验证扩展后，需要向 API 授予权限。 自定义身份验证扩展使用client_credentials和Receive custom authentication extension HTTP requests权限对 Azure 函数应用进行身份验证。

  1. 打开新自定义身份验证扩展的“概述”页。 记下“API 身份验证下”的应用 ID，因为添加标识提供者时会需要它。

  2. 在“API 身份验证”下，选择“授予权限”。

  3. 此时会打开一个新窗口，登录后，它会请求权限以接收自定义身份验证扩展 HTTP 请求。 通过此操作，自定义身份验证扩展可以向 API 进行身份验证。 选择“接受”。

    显示如何授予管理员同意的屏幕截图。

步骤 2：配置 OpenID Connect 应用以接收扩充的令牌

要获取令牌并测试自定义身份验证扩展，可以使用https://jwt.ms应用。 它是 Microsoft 拥有的一个 Web 应用程序，可显示令牌的解码内容（令牌内容永远不会离开你的浏览器）。

2.1 注册测试 Web 应用

按照以下步骤注册 jwt.ms Web 应用程序：

  1. 在 Azure 门户的“开始”页中，选择“Microsoft Entra ID”。

  2. 选择“应用注册”>“新建注册”。

  3. 输入应用程序的“名称”。 例如“我的测试应用程序”。

  4. 在“支持的帐户类型”下，选择“仅此组织目录中的帐户” 。

  5. 在“重定向 URI”中的“选择平台”下拉列表中选择“Web”，然后在“URL”文本框中输入 https://jwt.ms。

  6. 选择“注册”以完成应用注册。

    显示如何选择支持的帐户类型和重定向 URI 的屏幕截图。

  7. 在应用注册的“概述”页中，复制应用程序（客户端）ID。 在后续步骤中，该应用 ID 将引用为 {App_to_enrich_ID}。 在 Microsoft Graph 中，appId 属性引用了它。

    显示如何复制应用程序 ID 的屏幕截图。

2.2 启用隐式流

jwt.ms 测试应用程序使用隐式流。 在“我的测试应用程序”注册中启用隐式流：

  1. 在“管理”下，选择“身份验证”。
  2. 在“隐式授权和混合流”下，选中“ID 令牌(用于隐式流和混合流)”复选框。
  3. 选择“保存”。

2.3 为声明映射策略启用应用

声明映射策略用于选择要将自定义身份验证扩展返回的哪些属性映射到令牌。 若要允许扩充令牌，必须显式启用应用程序注册以接受映射的声明：

  1. 在“我的测试应用程序”注册中，在“管理”下选择“清单”。
  2. 在清单中找到 acceptMappedClaims 属性，并将值设置为 true。
  3. 将 accessTokenAcceptedVersion 设置为 2。
  4. 选择“保存”，保存更改。

以下 JSON 代码片段演示如何配置这些属性。

{
	"id": "22222222-0000-0000-0000-000000000000",
	"acceptMappedClaims": true,
	"accessTokenAcceptedVersion": 2,  
    ...
}

警告

对于多租户应用，请勿将 acceptMappedClaims 属性设置为 true，这可能会允许恶意参与者为应用创建声明映射策略。 应该配置自定义签名密钥。

继续执行下一步，向应用分配自定义声明提供程序。

步骤 3：将自定义声明提供程序分配到应用

对于要使用自定义身份验证扩展传入的声明颁发的令牌，必须将自定义声明提供程序分配到应用程序。 这基于令牌受众，因此必须向客户端应用程序分配提供程序以接收 ID 令牌中的声明，并向资源应用程序分配提供程序以接收访问令牌中的声明。 该自定义声明提供程序依赖于使用令牌颁发启动事件侦听器配置的自定义身份验证扩展。 可以选择是要将自定义声明提供程序提供的所有还是一部分声明映射到令牌。

注意

只能在应用程序和自定义扩展之间创建 250 个唯一分配。 如果你希望将同一个自定义扩展调用应用于多个应用，我们建议使用 authenticationEventListeners Microsoft Graph API 为多个应用程序创建侦听器。 Azure 门户中不支持此功能。

按照以下步骤将我的测试应用程序与自定义身份验证扩展相连接：

将自定义身份验证扩展分配为自定义声明提供程序源；

  1. 在 Azure 门户的“开始”页中，选择“Microsoft Entra ID”。

  2. 选择“启用应用程序”，然后在“管理”下面选择“所有应用程序”。 在列表中查找并选择“我的测试应用程序”。

  3. 在“我的测试应用程序”的“概述”页中，导航到“管理”，然后选择“单一登录”。

  4. 在“属性和声明”下，选择“编辑”。

    显示如何配置应用声明的屏幕截图。

  5. 展开“高级设置”菜单。

  6. 在“自定义声明提供程序”旁边，选择“配置”。

  7. 展开“自定义声明提供程序”下拉框，然后选择之前创建的“令牌颁发事件”。

  8. 选择“保存”。

接下来，从自定义声明提供程序分配属性，这些属性应作为声明颁发到令牌中：

  1. 选择“添加新声明”以添加新声明。 提供要颁发的声明的名称，例如 dateOfBirth。

  2. 在“源”下，选择“属性”，然后从“源属性”下拉列表框中选择“customClaimsProvider.dateOfBirth”。

    显示如何将声明映射添加到应用的屏幕截图。

  3. 选择“保存”。

  4. 重复此过程以添加“customClaimsProvider.customRoles”、“customClaimsProvider.apiVersion”和“customClaimsProvider.correlationId”属性以及相应的名称。 最好将声明的名称与属性的名称匹配。

步骤 4：保护 Azure 函数

Microsoft Entra 自定义身份验证扩展使用服务器到服务器的流来获取在 HTTP Authorization标头中发送到 Azure 函数的访问令牌。 将函数发布到 Azure 时（尤其是在生产环境中），需要验证在授权标头中发送的令牌。

要保护 Azure 函数，请按照以下步骤集成 Microsoft Entra 身份验证，以便使用Azure Functions 身份验证事件 API应用程序注册来验证传入的令牌。 根据租户类型选择以下选项卡之一。

注意

如果托管 Azure 函数应用的 Azure 租户不同于注册自定义身份验证扩展的租户，请选择“OpenID Connect”选项卡。

4.1 使用 Microsoft Entra 标识提供者

使用以下步骤将 Microsoft Entra 作为标识提供者添加到 Azure 函数应用。

  1. 在 Azure 门户中，查找并选择之前发布的函数应用。

  2. 在“设置”下选择“身份验证” 。

  3. 选择“添加标识提供者”。

  4. 选择“Microsoft”作为标识提供者。

  5. 选择“员工”作为租户类型。

  6. 在“应用注册”下，选择“选取此目录中的现有应用注册”作为“应用注册类型”，然后选取先前在注册自定义声明提供程序时创建的“Azure Functions 身份验证事件 API”应用注册。

  7. 输入以下颁发者 URL https://login.microsoftonline.com/{tenantId}/v2.0，其中 {tenantId} 是员工租户的租户 ID。

  8. 在“客户端应用程序要求”下，选择“允许来自特定客户端应用程序的请求”，然后输入 99045fe1-7639-4a75-9d4a-577b6ca3810f。

  9. 在“租户要求”下，选择“允许来自特定租户的请求”并输入工作人员租户 ID。

  10. 在“未经身份验证的请求”下，选择“HTTP 401 未授权”作为标识提供者。

  11. 取消选择“令牌存储”选项。

  12. 选择“添加”以将身份验证添加到 Azure 函数。

    屏幕截图显示了如何在员工租户中向函数应用添加身份验证。

4.2 使用 OpenID Connect 标识提供者

如果你配置了 Microsoft 标识提供者，请跳过此步骤。 否则，如果 Azure 函数所在的租户不同于注册自定义身份验证扩展的租户，请执行以下步骤保护函数：

创建客户端机密

  1. 在 Azure 门户的“开始”页中，选择“Microsoft Entra ID”>“应用注册”。
  2. 选择先前创建的“Azure Functions 身份验证事件 API”应用注册。
  3. 选择“证书和机密”>“客户端密码”>“新建客户端密码”。
  4. 选择机密的过期时间或指定自定义生存期，添加说明，然后选择“添加”。
  5. 请记下机密值，以便在客户端应用程序代码中使用。 退出此页面后，此机密值永不再显示。

将 OpenID Connect 标识提供者添加到 Azure 函数应用。

  1. 查找之前发布的函数应用并选择它。

  2. 在“设置”下选择“身份验证” 。

  3. 选择“添加标识提供者”。

  4. 选择“OpenID Connect”作为标识提供者。

  5. 提供名称，例如Contoso Microsoft Entra ID。

  6. 在“元数据条目”下的“文档 URL”中输入以下 URL。 将{tenantId}替换为 Microsoft Entra 租户 ID。

    https://login.microsoftonline.com/{tenantId}/v2.0/.well-known/openid-configuration

  7. 在“应用注册”下，输入先前创建的“Azure Functions 身份验证事件 API”应用注册的应用程序 ID（客户端 ID）。

  8. 返回 Azure 函数，在“应用注册”下输入“客户端机密”。

  9. 取消选择“令牌存储”选项。

  10. 选择“添加”以添加 OpenID Connect 标识提供者。

步骤 5：测试应用程序

要测试自定义声明提供程序，请执行以下步骤：

  1. 打开新的隐私浏览器，并通过以下 URL 进行导航和登录。

    https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize?client_id={App_to_enrich_ID}&response_type=id_token&redirect_uri=https://jwt.ms&scope=openid&state=12345&nonce=12345

  2. 将 {tenantId} 替换为你的租户 ID、租户名称或已验证的域名之一。 例如 contoso.onmicrosoft.com。

  3. 将 {App_to_enrich_ID} 替换为“我的测试应用程序”客户端 ID。

  4. 登录后，你将在 https://jwt.ms 上看到解码的令牌。 验证来自 Azure 函数的声明是否显示在解码的令牌中，例如 dateOfBirth。

另请参阅