使用 PowerShell 和宣告對應原則的宣告自定義

宣告是識別提供者在發給使用者的權杖內用以描述使用者的資訊。 租用戶系統管理員會使用自訂宣告，以針對其租用戶的特定應用程式自訂權杖中所發出的宣告。 您可以使用宣告對應原則來進行下列作業：

• 選取要在權杖中包括哪些宣告。
• 建立尚未存在的宣告類型。
• 選擇或變更特定宣告中所發出的資料來源。

宣告自訂功能支援設定 SAML、OAuth 及 OpenID Connect 通訊協定的宣告對應原則。

必要條件

• 了解如何取得 Microsoft Entra 租用戶。
• 下載最新的 Microsoft Graph PowerShell SDK。

開始使用

在下列範例中，您會為服務主體建立、更新、連結和刪除原則。 宣告對應原則只能指派給服務主體物件。

建立宣告對應原則時，您也可以從權杖中的目錄延伸模組屬性發出宣告。 請使用 ExtensionID 作為擴充屬性，而非 ClaimsSchema 元素中的識別碼。 如需擴充功能屬性的詳細資訊，請參閱使用目錄延伸模組屬性。

開啟終端機並執行下列命令，以登入您的 Microsoft Entra 系統管理員帳戶。 您每次啟動新的工作階段時執行此命令。

Import-Module Microsoft.Graph.Identity.SignIns

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

現在，您可以建立宣告對應原則，並將其指派給服務主體。 如需常見案例，請參閱下列範例：

• 省略權杖中的基本宣告
• 在權杖中包括 EmployeeID 和 TenantCountry 做為宣告
• 在權杖中使用宣告轉換

建立宣告對應原則之後，請設定您的應用程式，以確認權杖將包含自訂宣告。 如需詳細資訊，請參閱安全性考量。

省略權杖中的基本宣告

在此範例中，您將會建立原則，以從核發給連結服務主體的權杖中移除基本宣告集。

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 新增至核發給連結服務主體的權杖。 在 SAML 權杖和 JWT 中，系統會以名稱宣告類型來發出 EmployeeID。 在 SAML 權杖和 JWT 中，系統會以國家/區域宣告類型來發出 TenantCountry。 在此範例中，我們會繼續在權杖中納入基本宣告集。

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>"}
   

相關內容

• Microsoft Graph identity SignIns