如何:为租户中的特定应用自定义在令牌中发出的声明(预览版)How to: Customize claims emitted in tokens for a specific app in a tenant (Preview)

备注

此功能替换并取代了当前通过门户提供的声明自定义。This feature replaces and supersedes the claims customization offered through the portal today. 在同一应用程序中,如果使用门户以及本文档中详细介绍的 Graph/PowerShell 方法自定义声明,则为该应用程序颁发的令牌会忽略门户中的配置。On the same application, if you customize claims using the portal in addition to the Graph/PowerShell method detailed in this document, tokens issued for that application will ignore the configuration in the portal. 通过本文档中详细介绍的方法进行的配置不会在门户中进行反映。Configurations made through the methods detailed in this document will not be reflected in the portal.

备注

此功能目前以公共预览版提供。This capability currently is in public preview. 应准备好还原或删除所做的任何更改。Be prepared to revert or remove any changes. 在公共预览版推出期间,可在任何 Azure Active Directory (Azure AD) 订阅中使用此功能。The feature is available in any Azure Active Directory (Azure AD) subscription during public preview. 但是,在正式版推出后,某些功能可能需要使用 Azure AD Premium 订阅。However, when the feature becomes generally available, some aspects of the feature might require an Azure AD premium subscription. 此功能支持配置适用于 WS-Fed、SAML、OAuth 和 OpenID Connect 协议的声明映射策略。This feature supports configuring claim mapping policies for WS-Fed, SAML, OAuth, and OpenID Connect protocols.

此功能由租户管理员用来自定义以令牌形式针对其租户中的特定应用程序发出的声明。This feature is used by tenant admins to customize the claims emitted in tokens for a specific application in their tenant. 可以使用声明映射策略执行以下操作:You can use claims-mapping policies to:

  • 选择在令牌中包含的声明。Select which claims are included in tokens.
  • 创建尚未存在的声明类型。Create claim types that do not already exist.
  • 选择或更改在特定声明中发出的数据的源。Choose or change the source of data emitted in specific claims.

在本文中,我们会演练几个常见方案,它们可帮助你理解如何使用声明映射策略类型In this article, we walk through a few common scenarios that can help you grasp how to use the claims mapping policy type.

创建声明映射策略时,还可以根据令牌中的目录架构扩展属性发出声明。When creating a claims mapping policy, you can also emit a claim from a directory schema extension attribute in tokens. 使用与扩展属性对应的 ExtensionID,而不是 ClaimsSchema 元素中的 ID。Use ExtensionID for the extension attribute instead of ID in the ClaimsSchema element. 有关扩展属性的更多信息,请参阅使用目录架构扩展属性For more info on extension attributes, see Using directory schema extension attributes.

先决条件Prerequisites

以下示例将创建、更新、链接和删除服务主体的策略。In the following examples, you create, update, link, and delete policies for service principals. 声明映射策略只能分配给服务主体对象。Claims mapping policies can only be assigned to service principal objects. 如果你是 Azure AD 新手,我们建议在继续学习这些示例之前,先了解如何获取 Azure AD 租户If you are new to Azure AD, we recommend that you learn about how to get an Azure AD tenant before you proceed with these examples.

若要开始,请执行以下步骤:To get started, do the following steps:

  1. 首先请下载最新的 Azure AD PowerShell 模块公共预览版Download the latest Azure AD PowerShell Module public preview release.

  2. 运行 Connect 命令,登录到 Azure AD 管理员帐户。Run the Connect command to sign in to your Azure AD admin account. 每次启动新会话都需要运行此命令。Run this command each time you start a new session.

    Connect-AzureAD -AzureEnvironmentName AzureChinaCloud -Confirm
    
  3. 若要查看组织中创建的所有策略,请运行以下命令。To see all policies that have been created in your organization, run the following command. 在以下方案中,建议在大多数操作之后运行此命令,以检查是否按预期创建策略。We recommend that you run this command after most operations in the following scenarios, to check that your policies are being created as expected.

    Get-AzureADPolicy
    

省略令牌中的基本声明Omit the basic claims from tokens

在此示例中创建一个策略,它会从颁发给链接的服务主体的令牌中删除基本声明集In this example, you create a policy that removes the basic claim set from tokens issued to linked service principals.

  1. 创建声明映射策略。Create a claims mapping policy. 此策略(链接到特定服务主体)会从令牌中删除基本声明集。This policy, linked to specific service principals, removes the basic claim set from tokens.
    1. 若要创建该策略,请运行以下命令:To create the policy, run this command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims" -Type "ClaimsMappingPolicy"
      
    2. 若要查看新策略并获取其 ObjectId,请运行以下命令:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. 将策略分配到服务主体。Assign the policy to your service principal. 还需要获取服务主体的 ObjectId。You also need to get the ObjectId of your service principal.
    1. 若要查看组织的所有服务主体,可以查询 Microsoft Graph APITo see all your organization's service principals, you can query the Microsoft Graph API. 或者,在 Microsoft Graph Explorer 中登录到你的 Azure AD 帐户。Or, in Microsoft Graph Explorer, sign in to your Azure AD account.

    2. 获取服务主体的 ObjectId 后,运行以下命令:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

在令牌中包括 EmployeeID 和 TenantCountry 作为声明Include the EmployeeID and TenantCountry as claims in tokens

在此示例中创建一个策略,它会向颁发给链接的服务主体的令牌添加 EmployeeID 和 TenantCountry。In this example, you create a policy that adds the EmployeeID and TenantCountry to tokens issued to linked service principals. EmployeeID 在 SAML 令牌和 JWT 中都作为名称声明类型发出。The EmployeeID is emitted as the name claim type in both SAML tokens and JWTs. TenantCountry 在 SAML 令牌和 JWT 中都作为国家/地区声明类型发出。The TenantCountry is emitted as the country/region claim type in both SAML tokens and JWTs. 在此示例中,我们继续在令牌中包含基本声明集。In this example, we continue to include the basic claims set in the tokens.

  1. 创建声明映射策略。Create a claims mapping policy. 此策略(链接到特定服务主体)向令牌添加 EmployeeID 和 TenantCountry 声明。This policy, linked to specific service principals, adds the EmployeeID and TenantCountry claims to tokens.
    1. 若要创建该策略,请运行以下命令:To create the policy, run the following command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid","JwtClaimType":"name"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample" -Type "ClaimsMappingPolicy"
      
    2. 若要查看新策略并获取其 ObjectId,请运行以下命令:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. 将策略分配到服务主体。Assign the policy to your service principal. 还需要获取服务主体的 ObjectId。You also need to get the ObjectId of your service principal.
    1. 若要查看组织的所有服务主体,可以查询 Microsoft Graph APITo see all your organization's service principals, you can query the Microsoft Graph API. 或者,在 Microsoft Graph Explorer 中登录到你的 Azure AD 帐户。Or, in Microsoft Graph Explorer, sign in to your Azure AD account.

    2. 获取服务主体的 ObjectId 后,运行以下命令:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

在令牌中使用声明转换Use a claims transformation in tokens

在此示例中创建一个策略,它会向颁发给链接的服务主体的 JWT 发出自定义声明“JoinedData”。In this example, you create a policy that emits a custom claim "JoinedData" to JWTs issued to linked service principals. 此声明包含通过将用户对象的 extensionattribute1 属性中存储的数据与“.sandbox”联接所创建的值。This claim contains a value created by joining the data stored in the extensionattribute1 attribute on the user object with ".sandbox". 在此示例中,我们在令牌中排除基本声明集。In this example, we exclude the basic claims set in the tokens.

  1. 创建声明映射策略。Create a claims mapping policy. 此策略(链接到特定服务主体)向令牌添加 EmployeeID 和 TenantCountry 声明。This policy, linked to specific service principals, adds the EmployeeID and TenantCountry claims to tokens.
    1. 若要创建该策略,请运行以下命令:To create the policy, run the following command:

      New-AzureADPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema":[{"Source":"user","ID":"extensionattribute1"},{"Source":"transformation","ID":"DataJoin","TransformationId":"JoinTheData","JwtClaimType":"JoinedData"}],"ClaimsTransformations":[{"ID":"JoinTheData","TransformationMethod":"Join","InputClaims":[{"ClaimTypeReferenceId":"extensionattribute1","TransformationClaimType":"string1"}], "InputParameters": [{"ID":"string2","Value":"sandbox"},{"ID":"separator","Value":"."}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample" -Type "ClaimsMappingPolicy"
      
    2. 若要查看新策略并获取其 ObjectId,请运行以下命令:To see your new policy, and to get the policy ObjectId, run the following command:

      Get-AzureADPolicy
      
  2. 将策略分配到服务主体。Assign the policy to your service principal. 还需要获取服务主体的 ObjectId。You also need to get the ObjectId of your service principal.
    1. 若要查看组织的所有服务主体,可以查询 Microsoft Graph APITo see all your organization's service principals, you can query the Microsoft Graph API. 或者,在 Microsoft Graph Explorer 中登录到你的 Azure AD 帐户。Or, in Microsoft Graph Explorer, sign in to your Azure AD account.

    2. 获取服务主体的 ObjectId 后,运行以下命令:When you have the ObjectId of your service principal, run the following command:

      Add-AzureADServicePrincipalPolicy -Id <ObjectId of the ServicePrincipal> -RefObjectId <ObjectId of the Policy>
      

安全注意事项Security considerations

接收令牌的应用程序依赖于这样一个事实:即声明值是由 Azure AD 权威颁发的,不能篡改。Applications that receive tokens rely on the fact that the claim values are authoritatively issued by Azure AD and cannot be tampered with. 但当你通过声明映射策略修改令牌内容时,上述事实可能不再适用。However, when you modify the token contents via claims mapping policies, these assumptions may no longer be correct. 应用程序必须明确承认令牌已被声明映射策略的创建者修改,才能防止被恶意参与者创建的声明映射策略破坏。Applications must explicitly acknowledge that tokens have been modified by the creator of the claims mapping policy to protect themselves from claims mapping policies created by malicious actors. 通过以下方式可实现此目的:This can be done in the following ways:

  • 配置自定义签名密钥Configure a custom signing key
  • 更新应用程序清单,以接受映射的声明。Update the application manifest to accept mapped claims.

否则,Azure AD 将返回 AADSTS50146 错误代码Without this, Azure AD will return an AADSTS50146 error code.

自定义签名密钥Custom signing key

若要将自定义签名密钥添加到服务主体对象,可使用 Azure PowerShell cmdlet New-AzureADApplicationKeyCredential 为应用程序对象创建证书密钥凭据。In order to add a custom signing key to the service principal object, you can use the Azure PowerShell cmdlet New-AzureADApplicationKeyCredential to create a certificate key credential for your Application object.

启用了声明映射的应用必须通过将 appid={client_id} 追加到其 OpenID Connect 元数据请求来验证令牌签名密钥。Apps that have claims mapping enabled must validate their token signing keys by appending appid={client_id} to their OpenID Connect metadata requests. 下面是你应该使用的 OpenID 连接元数据文档的格式:Below is the format of the OpenID Connect metadata document you should use:

https://login.partner.microsoftonline.cn/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

更新应用程序清单Update the application manifest

或者,可以在应用程序清单中将 acceptMappedClaims 属性设置为 trueAlternatively, you can set the acceptMappedClaims property to true in the application manifest. apiApplication 资源类型中所述,这样可以让应用程序使用声明映射,而无需指定自定义签名密钥。As documented on the apiApplication resource type, this allows an application to use claims mapping without specifying a custom signing key.

这确实会要求请求令牌的受众使用经过验证的 Azure AD 租户域名,这意味着应确保设置 Application ID URI(在应用程序清单中由 identifierUris 表示),例如将其设置为 https://contoso.com/my-api 或(仅使用默认租户名)https://contoso.partner.onmschina.cn/my-apiThis does require the requested token audience to use a verified domain name of your Azure AD tenant, which means you should ensure to set the Application ID URI (represented by the identifierUris in the application manifest) for example to https://contoso.com/my-api or (simply using the default tenant name) https://contoso.partner.onmschina.cn/my-api.

如果不使用经过验证的域,Azure AD 将返回 AADSTS501461 错误代码以及消息“AcceptMappedClaims 仅支持与应用程序 GUID 匹配的令牌受众或经过验证的租户域中的受众。请更改资源标识符,或使用特定于应用程序的签名密钥。”If you're not using a verified domain, Azure AD will return an AADSTS501461 error code with message "AcceptMappedClaims is only supported for a token audience matching the application GUID or an audience within the tenant's verified domains. Either change the resource identifier, or use an application-specific signing key."

后续步骤Next steps