Kustomisasi klaim menggunakan PowerShell dan Kebijakan Pemetaan Klaim

Klaim adalah informasi yang menyatakan penyedia identitas tentang pengguna di dalam token yang mereka terbitkan untuk pengguna tersebut. Penyesuaian klaim digunakan oleh admin penyewa untuk menyesuaikan klaim yang dikeluarkan dalam token untuk aplikasi tertentu di penyewa mereka. Anda dapat menggunakan kebijakan pemetaan klaim untuk:

• memilih klaim mana yang disertakan dalam token.
• membuat jenis klaim yang belum ada.
• memilih atau mengubah sumber data yang dikeluarkan dalam klaim tertentu.

Penyesuaian klaim mendukung konfigurasi kebijakan pemetaan klaim untuk protokol SAML, OAuth, dan OpenID Connect.

Catatan

Kebijakan Pemetaan Klaim menggantikan kebijakan Klaim Kustom dan kustomisasi klaim yang ditawarkan melalui pusat admin Microsoft Entra. Menyesuaikan klaim untuk aplikasi menggunakan Kebijakan Pemetaan Klaim berarti bahwa token yang dikeluarkan untuk aplikasi tersebut akan mengabaikan konfigurasi dalam Kebijakan Klaim Kustom atau konfigurasi dalam bilah kustomisasi klaim di pusat admin Microsoft Entra.

Prasyarat

• Pelajari tentang cara mendapatkan penyewa Microsoft Entra.
• Unduh Microsoft Graph PowerShell SDK terbaru.

Memulai

Dalam contoh berikut, Anda membuat, memperbarui, menautkan, dan menghapus kebijakan untuk perwakilan layanan. Kebijakan pemetaan klaim hanya dapat ditetapkan ke objek perwakilan layanan.

Saat membuat kebijakan pemetaan klaim, Anda juga dapat mengeluarkan klaim dari atribut ekstensi direktori dalam token. Gunakan ExtensionID untuk atribut ekstensi alih-alih ID dalam ClaimsSchema elemen . Untuk informasi selengkapnya tentang atribut ekstensi, lihat Menggunakan atribut ekstensi direktori.

Catatan

Microsoft Graph PowerShell SDK diperlukan untuk mengonfigurasi kebijakan pemetaan klaim.

Buka terminal dan jalankan perintah berikut untuk masuk ke akun admin Microsoft Entra Anda. Jalankan perintah ini tiap kali Anda memulai sesi baru.

Import-Module Microsoft.Graph.Identity.SignIns

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

Sekarang Anda dapat membuat kebijakan pemetaan klaim dan menetapkannya ke perwakilan layanan. Lihat contoh berikut untuk skenario umum:

• Menghilangkan klaim dasar dari token
• Sertakan EmployeeID dan TenantCountry sebagai klaim dalam token
• Menggunakan transformasi klaim dalam token

Setelah membuat kebijakan pemetaan klaim, konfigurasikan aplikasi Anda untuk mengakui bahwa token akan berisi klaim yang disesuaikan. Untuk mengetahui informasi selengkapnya, lihat pertimbangan keamanan.

Menghilangkan klaim dasar dari token

Dalam contoh ini, Anda membuat kebijakan yang menghapus serangkaian klaim dasar dari token yang dikeluarkan untuk perwakilan layanan tertaut.

1. Buat kebijakan pemetaan klaim. Kebijakan ini, yang terkait dengan perwakilan layanan tertentu, menghapus serangkaian klaim dasar dari token.

2. Menggunakan terminal yang telah Anda buka, jalankan perintah berikut untuk membuat kebijakan:

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

3. Untuk melihat kebijakan baru Anda, dan untuk mendapatkan kebijakan ObjectId, jalankan perintah berikut:

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

Sertakan EmployeeID dan TenantCountry sebagai klaim dalam token

Dalam contoh ini, Anda membuat kebijakan yang menambahkan EmployeeID dan TenantCountry ke token yang dikeluarkan ke perwakilan layanan tertaut. EmployeeID dikeluarkan sebagai jenis klaim nama dalam token SAML dan JWT. TenantCountry dikeluarkan sebagai jenis klaim negara/wilayah dalam token SAML dan JWT. Dalam contoh ini, kami terus menyertakan serangkaian klaim dasar dalam token.

1. Buat kebijakan pemetaan klaim. Kebijakan ini, yang terkait dengan perwakilan layanan tertentu, menambahkan klaim EmployeeID dan TenantCountry ke token.

2. Untuk membuat kebijakan, jalankan perintah berikut di terminal Anda:

   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. Untuk melihat kebijakan baru Anda, dan untuk mendapatkan kebijakan ObjectId, jalankan perintah berikut:

   Get-MgPolicyClaimMappingPolicy
   

Menggunakan transformasi klaim dalam token

Dalam contoh ini, Anda membuat kebijakan yang mengeluarkan klaim kustom "JoinedData" ke JWT yang dikeluarkan untuk perwakilan layanan terkait. Klaim ini berisi nilai yang dibuat dengan menggabungkan data yang disimpan dalam atribut extensionattribute1 pada objek pengguna dengan "-ext". Dalam contoh ini, kami mengecualikan serangkaian klaim dasar dalam token.

1. Buat kebijakan pemetaan klaim. Kebijakan ini, yang ditautkan ke perwakilan layanan tertentu, memancarkan klaim JoinedData kustom ke token.

2. Untuk membuat kebijakan, jalankan perintah berikut:

   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. Untuk melihat kebijakan baru Anda, dan untuk mendapatkan kebijakan ObjectId, jalankan perintah berikut:

   Get-MgPolicyClaimMappingPolicy
   

Menetapkan kebijakan pemetaan klaim ke perwakilan layanan Anda

Untuk menetapkan kebijakan ke perwakilan layanan, Anda akan memerlukan ObjectId kebijakan pemetaan klaim Anda dan objectId perwakilan layanan tempat kebijakan harus ditetapkan.

1. Untuk melihat semua perwakilan layanan organisasi, Anda dapat mengkueri Microsoft Graph API atau, memeriksanya di Microsoft Graph Explorer.

2. Untuk melihat semua kebijakan pemetaan klaim di penyewa Anda, dan untuk mendapatkan kebijakan ObjectId, jalankan perintah berikut:

   Get-MgPolicyClaimMappingPolicy
   

3. Saat Anda memiliki ObjectId kebijakan pemetaan klaim dan perwakilan layanan, jalankan perintah berikut:

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

Konten terkait

• Cara: Menyesuaikan klaim dengan kebijakan pemetaan klaim di Microsoft Graph
• Microsoft Graph identity SignIns