通过

使用 PowerShell 和声明映射策略进行声明自定义

  • 项目

“声明”是标识提供者在为某个用户颁发的令牌中陈述的有关该用户的信息。 租户管理员使用声明自定义为其租户中的特定应用程序自定义令牌中发出的声明。 可以使用声明映射策略执行以下操作：

  • 选择在令牌中包含的声明。
  • 创建尚不存在的声明类型。
  • 选择或更改在特定声明中发出的数据的源。

声明自定义功能支持配置适用于 SAML、OAuth 和 OpenID Connect 协议的声明映射策略。

注意

声明映射策略取代了自定义声明策略以及通过 Microsoft Entra 管理中心提供的声明自定义。 使用声明映射策略自定义应用程序的声明意味着为该应用程序颁发的令牌将忽略自定义声明策略中的配置，或 Microsoft Entra 管理中心的声明自定义边栏选项卡中的配置。

先决条件

入门

以下示例将创建、更新、链接和删除服务主体的策略。 声明映射策略只能分配给服务主体对象。

创建声明映射策略时，还可以根据令牌中的目录扩展属性发出声明。 使用该扩展属性的 ExtensionID，而不是 ClaimsSchema 元素中的 ID。 有关扩展属性的更多信息，请参阅使用目录扩展属性。

注意

配置声明映射策略需要使用 Microsoft Graph PowerShell SDK。

打开终端并运行以下命令，以登录到 Microsoft Entra 管理员帐户。 每次启动新会话都需要运行此命令。

Import-Module Microsoft.Graph.Identity.SignIns

Connect-MgGraph -Scopes "Policy.ReadWrite.ApplicationConfiguration", "Policy.Read.All"

现在可以创建声明映射策略并将其分配给服务主体。 常见场景请参阅以下示例：

创建声明映射策略后，将应用程序配置为承认令牌将包含自定义声明。 有关详细信息，请阅读安全注意事项。

省略令牌中的基本声明

在此示例中创建一个策略，它会从颁发给链接的服务主体的令牌中删除基本声明集。

  1. 创建声明映射策略。 此策略（链接到特定服务主体）会从令牌中删除基本声明集。

  2. 使用你打开的终端运行以下命令来创建策略：

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"false"}}') -DisplayName "OmitBasicClaims"

  3. 要查看新策略并获取策略 ObjectId，请运行以下命令：

    Get-MgPolicyClaimMappingPolicy

Definition                    DeletedDateTime Description DisplayName      Id
----------                    --------------- ----------- -----------      --
{"ClaimsMappingPolicy":{..}}                              OmitBasicClaims  36d1aa10-f9ac...

在令牌中包含 EmployeeID 和 TenantCountry 以作为声明

此示例将创建一个策略，向颁发给所关联服务主体的令牌添加 EmployeeID 和 TenantCountry。 EmployeeID 在 SAML 令牌和 JWT 中都作为名称声明类型发出。 TenantCountry 在 SAML 令牌和 JWT 中都作为国家/地区声明类型发出。 在此示例中，我们继续在令牌中包含基本声明集。

  1. 创建声明映射策略。 此策略（链接到特定服务主体）向令牌添加 EmployeeID 和 TenantCountry 声明。

  2. 要创建策略，请在终端中运行以下命令：

    New-MgPolicyClaimMappingPolicy -Definition @('{"ClaimsMappingPolicy":{"Version":1,"IncludeBasicClaimSet":"true", "ClaimsSchema": [{"Source":"user","ID":"employeeid","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/employeeid","JwtClaimType":"employeeid"},{"Source":"company","ID":"tenantcountry","SamlClaimType":"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/country","JwtClaimType":"country"}]}}') -DisplayName "ExtraClaimsExample"

  3. 要查看新策略并获取策略 ObjectId，请运行以下命令：

    Get-MgPolicyClaimMappingPolicy

在令牌中使用声明转换

在此示例中创建一个策略，它会向颁发给链接的服务主体的 JWT 发出自定义声明“JoinedData”。 此声明包含通过在用户对象的 extensionattribute1 属性中存储的数据后联接“-ext”后创建的值。 在此示例中，我们在令牌中排除基本声明集。

  1. 创建声明映射策略。 此策略与特定的服务主体关联，将向令牌发出自定义声明 JoinedData。

  2. 若要创建该策略，请运行以下命令：

    New-MgPolicyClaimMappingPolicy -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":"ext"},{"ID":"separator","Value":"-"}],"OutputClaims":[{"ClaimTypeReferenceId":"DataJoin","TransformationClaimType":"outputClaim"}]}]}}') -DisplayName "TransformClaimsExample"

  3. 要查看新策略并获取策略 ObjectId，请运行以下命令：

    Get-MgPolicyClaimMappingPolicy

向服务主体分配声明映射策略

要向服务主题分配该策略，需要有该声明映射策略的 ObjectId 以及必须向其分配该策略的服务主体的 objectId。

  1. 要查看组织的所有服务主体，可以查询 Microsoft Graph API，也可以在 Microsoft Graph 浏览器中检查。

  2. 要查看租户中的所有声明映射策略并获取策略 ObjectId，请运行以下命令：

    Get-MgPolicyClaimMappingPolicy

  3. 获得声明映射策略和服务主体的 ObjectId 后，请运行以下命令：

    New-MgServicePrincipalClaimMappingPolicyByRef -ServicePrincipalId <servicePrincipalId> -BodyParameter @{"@odata.id" = "https://graph.microsoft.com/v1.0/policies/claimsMappingPolicies/<claimsMappingPolicyId>"}

相关内容