Atribut ekstensi direktori dalam klaim
Atribut ekstensi direktori menyediakan cara untuk menyimpan lebih banyak data pada objek direktori seperti pengguna. Hanya atribut ekstensi pada objek pengguna yang dapat digunakan untuk mengeluarkan klaim ke aplikasi. Artikel ini menjelaskan cara menggunakan atribut ekstensi direktori untuk mengirim data pengguna ke aplikasi dalam klaim token.
Catatan
Microsoft Graph menyediakan tiga mekanisme ekstensi lainnya untuk mengkustomisasi objek Grafik. Ketiganya adalah atribut ekstensi 1-15, ekstensi terbuka, dan ekstensi skema. Lihat dokumentasi Microsoft Graph untuk detailnya. Data yang disimpan di objek Microsoft Graph menggunakan ekstensi terbuka dan skema tidak tersedia sebagai sumber untuk klaim dalam token.
Atribut ekstensi direktori selalu dikaitkan dengan aplikasi di penyewa. Nama atribut direktori mencakup appId aplikasi atas namanya.
Pengidentifikasi untuk atribut ekstensi direktori adalah dari formulir extension_xxxxxxxxx_AttributeName. Di mana xxxxxxxxx appId aplikasi tempat ekstensi didefinisikan, dengan hanya karakter 0-9 dan A-Z.
Mendaftar dan menggunakan ekstensi direktori
Daftarkan atribut ekstensi direktori dengan salah satu cara berikut:
- Konfigurasikan Microsoft Entra Koneksi untuk membuatnya dan menyinkronkan data ke dalamnya dari lokal. Lihat Ekstensi Microsoft Entra Koneksi Sync Directory.
- Gunakan Microsoft Graph untuk mendaftar, mengatur nilai, dan membaca dari ekstensi direktori. Cmdlet PowerShell juga tersedia.
Mengeluarkan klaim dengan data dari Microsoft Entra Koneksi
Atribut ekstensi direktori yang dibuat dan disinkronkan menggunakan Microsoft Entra Koneksi selalu dikaitkan dengan ID aplikasi yang digunakan oleh Microsoft Entra Koneksi. Atribut ini dapat digunakan sebagai sumber untuk klaim dengan mengonfigurasinya sebagai klaim dalam konfigurasi Aplikasi Perusahaan di Portal. Setelah atribut ekstensi direktori dibuat menggunakan AD Koneksi, atribut tersebut ditampilkan dalam konfigurasi klaim SSO SAML.
Memancarkan klaim menggunakan Graph atau PowerShell
Jika atribut ekstensi direktori terdaftar untuk menggunakan Microsoft Graph atau PowerShell, aplikasi dapat dikonfigurasi untuk menerima data dalam atribut tersebut saat pengguna masuk. Aplikasi dapat dikonfigurasi untuk menerima data dalam ekstensi direktori yang terdaftar pada aplikasi menggunakan klaim opsional yang dapat diatur dalam manifes aplikasi.
Aplikasi multi-penyewa kemudian dapat mendaftarkan atribut ekstensi direktori untuk penggunaannya sendiri. Ketika aplikasi diprovisikan ke penyewa, ekstensi direktori terkait menjadi tersedia dan digunakan untuk pengguna di penyewa tersebut. Setelah ekstensi direktori tersedia, ekstensi tersebut dapat digunakan untuk menyimpan dan mengambil data menggunakan Microsoft Graph. Ekstensi direktori juga dapat memetakan ke klaim dalam token yang dipancarkan platform identitas Microsoft ke aplikasi.
Jika aplikasi perlu mengirim klaim dengan data dari atribut ekstensi yang terdaftar di aplikasi lain, kebijakan pemetaan klaim harus digunakan untuk memetakan atribut ekstensi ke klaim.
Pola umum untuk mengelola atribut ekstensi direktori adalah mendaftarkan aplikasi khusus untuk semua ekstensi direktori yang Anda butuhkan. Saat Anda menggunakan jenis aplikasi ini, semua ekstensi memiliki appID yang sama atas namanya.
Misalnya, kode berikut menunjukkan kebijakan pemetaan klaim untuk memancarkan satu klaim dari atribut ekstensi direktori dalam token OAuth/OIDC:
{
"ClaimsMappingPolicy": {
"Version": 1,
"IncludeBasicClaimSet": "false",
"ClaimsSchema": [{
"Source": "User",
"ExtensionID": "extension_xxxxxxx_test",
"JWTClaimType": "http://schemas.contoso.com/identity/claims/exampleclaim"
},
]
}
}
Di mana xxxxxxx appID (atau ID Klien) aplikasi tempat ekstensi didaftarkan.
Peringatan
Saat Anda menentukan kebijakan pemetaan klaim untuk atribut ekstensi direktori, gunakan ExtensionID properti alih-alih ID properti dalam isi ClaimsSchema array, seperti yang ditunjukkan pada contoh sebelumnya.
Tip
Konsistensi kasus penting saat Anda mengatur atribut ekstensi direktori pada objek. Nama atribut ekstensi tidak peka huruf besar/kecil saat disiapkan, tetapi peka huruf besar/kecil saat dibaca dari direktori oleh layanan token. Jika atribut ekstensi diatur pada objek pengguna dengan nama "LegacyId" dan pada objek pengguna lain dengan nama "legacyid", ketika atribut dipetakan ke klaim menggunakan nama "LegacyId" data berhasil diambil dan klaim yang disertakan dalam token untuk pengguna pertama tetapi bukan yang kedua.