Memberikan klaim opsional ke aplikasi Anda
Pengembang aplikasi dapat menggunakan klaim opsional dalam aplikasi Microsoft Azure AD mereka untuk menentukan klaim mana yang mereka inginkan dalam token yang dikirim ke aplikasi mereka.
Anda dapat menggunakan klaim opsional untuk:
- Memilih klaim tambahan untuk disertakan dalam token aplikasi Anda.
- Mengubah sifat klaim tertentu yang dihasilkan platform identitas Microsoft dalam token.
- Menambahkan dan mengakses klaim kustom untuk aplikasi Anda.
Untuk daftar klaim standar, lihat token akses dan dokumentasi klaim id_token.
Meskipun klaim opsional didukung dalam token format v1.0 dan v2.0, dan token SAML, klaim tersebut memberikan sebagian besar nilainya saat berpindah dari v1.0 ke v2.0. Salah satu tujuan platform identitas Microsoft adalah ukuran token yang lebih kecil untuk memastikan performa optimal oleh klien. Akibatnya, beberapa klaim yang sebelumnya termasuk dalam token akses dan ID tidak lagi muncul dalam token v2.0, dan harus diminta secara khusus berdasarkan setiap aplikasi.
Tabel 1: Penerapan
Jenis Akun | Token v1.0 | Token v2.0 |
---|---|---|
Akun Microsoft pribadi | T/A | Didukung |
Akun Microsoft Azure AD | Didukung | Didukung |
Set klaim opsional v1.0 dan v2.0
Kumpulan klaim opsional yang tersedia secara default untuk digunakan aplikasi tercantum di bawah ini. Anda dapat menggunakan data kustom dalam atribut ekstensi dan ekstensi direktori untuk menambahkan klaim opsional untuk aplikasi Anda. Untuk menggunakan ekstensi direktori, lihat Ekstensi Direktori, di bawah ini. Saat menambahkan klaim ke token akses, klaim berlaku untuk mengakses token yang diminta untuk aplikasi (API web), bukan klaim yang diminta oleh aplikasi. Tidak penting bagaimana klien mengakses API Anda, data yang tepat berada dalam token akses yang digunakan untuk mengautentikasi terhadap API Anda.
Catatan
Sebagian besar klaim ini dapat dimasukkan dalam JWT untuk token v1.0 dan v2.0, tetapi bukan token SAML, kecuali jika terletak di kolom Jenis Token. Akun konsumen mendukung sub rangkaian klaim ini, ditandai di kolom "Jenis Pengguna". Banyak klaim yang tercantum tidak berlaku untuk pengguna konsumen (mereka tidak memiliki penyewa, sehingga tenant_ctry
tidak memiliki nilai).
Tabel 2: Set klaim opsional v1.0 dan v2.0
Nama | Deskripsi | Jenis Token | Jenis pengguna | Catatan |
---|---|---|---|---|
acct |
Status akun pengguna dalam penyewa | JWT, SAML | Jika pengguna adalah anggota penyewa, nilainya adalah 0 . Jika mereka adalah tamu, nilainya adalah 1 . |
|
auth_time |
Waktu ketika pengguna terakhir diautentikasi. Lihat spesifikasi OpenID Connect. | JWT | ||
ctry |
Negara/wilayah pengguna | JWT | Microsoft Azure AD menghasilkan klaim opsional ctry jika ada, dan nilai bidang adalah kode negara/kawasan dua huruf standar, seperti FR, JP, SZ, dan sebagainya. |
|
email |
Alamat email yang dilaporkan untuk pengguna ini | JWT, SAML | MSA, Microsoft Azure AD | Nilai ini disertakan secara default jika pengguna adalah tamu dalam penyewa. Untuk pengguna terkelola (pengguna di dalam penyewa), harus diminta melalui klaim opsional ini atau, hanya pada v2.0, dengan cakupan OpenID. Nilai ini tidak dijamin benar, dan dapat berubah dari waktu ke waktu - jangan pernah menggunakannya untuk otorisasi atau untuk menyimpan data bagi pengguna. Untuk informasi selengkapnya, lihat Memvalidasi izin pengguna untuk mengakses data ini. Jika Anda memerlukan alamat email yang dapat dialamatkan di aplikasi Anda, minta data ini dari pengguna secara langsung, menggunakan klaim ini sebagai saran atau mengisi UX Anda. |
fwd |
Alamat IP. | JWT | Menambahkan alamat IPv4 asli klien yang meminta (saat berada di dalam VNET) | |
groups |
Pembuatan format opsional untuk klaim grup | JWT, SAML | Untuk detail lihat Klaim grup berikut. Untuk informasi selengkapnya tentang klaim grup, lihat Cara mengonfigurasi klaim grup. Digunakan dengan pengaturan GroupMembershipClaims dalam manifes aplikasi, yang harus diatur juga. | |
idtyp |
Jenis token | Token akses JWT | Khusus: hanya dalam token akses khusus aplikasi | Nilai adalah app ketika token merupakan token khusus aplikasi. Ini adalah cara paling akurat bagi API untuk menentukan jika token adalah token aplikasi atau token pengguna+aplikasi. |
login_hint |
Petunjuk login | JWT | MSA, Microsoft Azure AD | Klaim petunjuk masuk yang buram dan andal yang dikodekan base64. Jangan ubah nilai ini. Klaim ini adalah nilai terbaik yang digunakan untuk parameter OAuth login_hint di semua alur untuk mendapatkan SSO. Klaim ini dapat diteruskan di antara aplikasi untuk membantu melakukan SSO juga secara diam-diam - aplikasi A dapat membuat pengguna masuk, membaca klaim login_hint , lalu mengirim klaim dan konteks penyewa saat ini ke aplikasi B dalam string kueri atau fragmen ketika pengguna mengeklik link yang mengarahkan mereka ke aplikasi B. Untuk menghindari kondisi bersaing dan masalah keandalan, klaim login_hint tidak menyertakan penyewa saat ini untuk pengguna, dan default ke penyewa rumah pengguna saat digunakan. Jika Anda beroperasi dalam skenario tamu, di mana pengguna berasal dari penyewa lain, Anda harus memberikan pengidentifikasi penyewa dalam permintaan kredensial masuk, dan meneruskannya ke aplikasi yang bermitra dengan Anda. Klaim ini dimaksudkan untuk digunakan dengan fungsionalitas SDK login_hint Anda yang sudah ada, meskipun terbuka. |
sid |
ID sesi, digunakan untuk keluar pengguna per sesi. | JWT | Akun Microsoft Azure AD dan Pribadi. | |
tenant_ctry |
Negara/wilayah penyewa sumber daya | JWT | Sama seperti ctry kecuali diatur pada tingkat penyewa oleh admin. Juga harus merupakan nilai dua huruf standar. |
|
tenant_region_scope |
Wilayah penyewa sumber daya | JWT | ||
upn |
UserPrincipalName | JWT, SAML | Pengidentifikasi untuk pengguna yang dapat digunakan dengan parameter username_hint. Bukan pengidentifikasi yang tahan lama bagi pengguna dan tidak boleh digunakan untuk otorisasi atau untuk mengidentifikasi informasi pengguna secara unik (misalnya, sebagai kunci database). Sebagai gantinya, gunakan ID objek pengguna (oid ) sebagai kunci database. Untuk informasi selengkapnya, lihat Memvalidasi izin pengguna untuk mengakses data ini. Pengguna yang masuk dengan ID masuk alternatif tidak boleh menunjukkan Nama Prinsipal Pengguna (UPN) mereka. Sebagai gantinya, gunakan klaim token ID berikut untuk menampilkan status masuk kepada pengguna: preferred_username atau unique_name untuk token v1 dan preferred_username untuk token v2. Meskipun klaim ini disertakan secara otomatis, Anda dapat menentukannya sebagai klaim opsional untuk melampirkan properti tambahan guna memodifikasi sifatnya dalam kasus pengguna tamu. Anda harus menggunakan klaim login_hint untuk penggunaan login_hint - pengidentifikasi yang dapat dibaca manusia seperti UPN tidak dapat diandalkan. |
|
verified_primary_email |
Bersumber dari PrimaryAuthoritativeEmail pengguna | JWT | ||
verified_secondary_email |
Bersumber dari SecondaryAuthoritativeEmail pengguna | JWT | ||
vnet |
Informasi penentu VNET. | JWT | ||
xms_pdl |
Lokasi data pilihan | JWT | Untuk penyewa Multi-Lokasi, lokasi data pilihan adalah kode tiga huruf yang menunjukkan wilayah geografis tempat pengguna berada. Untuk informasi selengkapnya, lihat dokumentasi Microsoft Azure AD Connect tentang lokasi data pilihan. Contohnya: APC untuk Asia Pasifik. |
|
xms_pl |
Bahasa pilihan | JWT | Bahasa pilihan pengguna, jika diterapkan. Bersumber dari penyewa asal mereka, dalam skenario akses tamu. LL-CC yang diformat ("id-id"). | |
xms_tpl |
Bahasa pilihan penyewa | JWT | Bahasa pilihan penyewa sumber daya, jika ditetapkan. LL yang diformat ("id"). | |
ztdid |
ID Penyebaran Tanpa Sentuhan | JWT | Identitas perangkat yang digunakan untuk Windows AutoPilot |
Kumpulan klaim opsional tertentu v2.0
Klaim ini selalu disertakan dalam token Microsoft Azure AD v1.0, tetapi tidak termasuk dalam token v2.0 kecuali diminta. Klaim ini hanya berlaku untuk JWT (token ID dan Token Akses).
Tabel 3: Klaim opsional v2.0 saja
Klaim JWT | Nama | Deskripsi | Catatan |
---|---|---|---|
ipaddr |
Alamat IP | Alamat IP klien tempat masuk. | |
onprem_sid |
Pengenal Keamanan Lokal | ||
pwd_exp |
Kebijakan kedaluwarsa kata sandi | Jumlah detik setelah waktu dalam klaim iat di mana kata sandi kedaluwarsa. Klaim ini hanya disertakan ketika kata sandi akan segera kedaluwarsa (seperti yang didefinisikan oleh "hari pemberitahuan" dalam kebijakan kata sandi). | |
pwd_url |
Ubah URL kata sandi | URL yang dapat dikunjungi pengguna untuk mengubah kata sandi. Klaim ini hanya disertakan ketika kata sandi akan segera kedaluwarsa (seperti yang didefinisikan oleh "hari pemberitahuan" dalam kebijakan kata sandi). | |
in_corp |
Dalam Jaringan Perusahaan | Memberi sinyal jika klien masuk dari jaringan perusahaan. Jika tidak, klaim tidak disertakan. | Berdasarkan pengaturan IP tepercaya di MFA. |
family_name |
Nama Belakang | Memberi nama belakang, atau nama keluarga pengguna seperti yang ditentukan pada objek pengguna. "family_name":"Miller" |
Didukung di MSA dan Microsoft Azure AD. Membutuhkan cakupan profile . |
given_name |
Nama depan | Memberi nama pertama pengguna, seperti yang diatur pada objek pengguna. "given_name": "Frank" |
Didukung di MSA dan Microsoft Azure AD. Membutuhkan cakupan profile . |
upn |
Nama Utama Pengguna | Pengidentifikasi untuk pengguna yang dapat digunakan dengan parameter username_hint. Bukan pengidentifikasi yang tahan lama bagi pengguna dan tidak boleh digunakan untuk otorisasi atau untuk mengidentifikasi informasi pengguna secara unik (misalnya, sebagai kunci database). Untuk informasi selengkapnya, lihat Memvalidasi izin pengguna untuk mengakses data ini. Sebagai gantinya, gunakan ID objek pengguna (oid ) sebagai kunci database. Pengguna yang masuk dengan ID masuk alternatif tidak boleh menunjukkan Nama Prinsipal Pengguna (UPN) mereka. Sebagai gantinya, gunakan klaim preferred_username berikut untuk menampilkan status masuk kepada pengguna. |
Lihat properti tambahan berikut untuk konfigurasi klaim. Membutuhkan cakupan profile . |
Kumpulan klaim opsional tertentu v1.0
Beberapa peningkatan format token v2 tersedia untuk aplikasi yang menggunakan format token v1, karena mereka membantu meningkatkan keamanan dan keandalan. Peningkatan ini tidak akan berlaku untuk token ID yang diminta dari titik akhir v2, atau token akses untuk API yang menggunakan format token v2. Peningkatan ini hanya berlaku untuk JWT, bukan token SAML.
Tabel 4: Klaim opsional v1.0 saja
Klaim JWT | Nama | Deskripsi | Catatan |
---|---|---|---|
aud |
Audiens | Selalu hadir di JWT, tetapi dalam token akses v1 dapat dipancarkan dengan berbagai cara - semua jenis URI appID, dengan atau tanpa garis miring berikutnya, serta ID klien sumber daya. Pengacakan ini bisa sulit untuk dikodekan ketika melakukan validasi token. Gunakan properti tambahan untuk klaim ini guna memastikan properti selalu ditetapkan ke ID klien sumber daya dalam token akses v1. | Token akses v1 JWT saja |
preferred_username |
Nama pengguna pilihan | Memberikan klaim nama pengguna pilihan dalam token v1. Klaim ini memudahkan aplikasi untuk memberikan petunjuk nama pengguna dan menampilkan nama tampilan yang dapat dibaca manusia, terlepas dari jenis token mereka. Sebaiknya gunakan klaim opsional ini alih-alih menggunakan, misalnya,upn atau unique_name . |
token ID v1 dan token akses |
Properti tambahan dari klaim opsional
Beberapa klaim opsional dapat dikonfigurasi untuk mengubah cara klaim dihasilkan. Properti tambahan ini sebagian besar digunakan untuk membantu migrasi aplikasi lokal dengan harapan data yang berbeda. Misalnya, include_externally_authenticated_upn_without_hash
membantu klien yang tidak dapat menangani tanda hash (#
) di UPN.
Tabel 4: Nilai untuk mengonfigurasi klaim opsional
Nama properti | Nama properti Tambahan | Deskripsi |
---|---|---|
upn |
Dapat digunakan untuk respons SAML dan JWT, serta untuk token v1.0 dan v2.0. | |
include_externally_authenticated_upn |
Termasuk UPN tamu seperti yang disimpan di penyewa sumber daya. Contohnya, foo_hometenant.com#EXT#@resourcetenant.com |
|
include_externally_authenticated_upn_without_hash |
Sama seperti di atas, kecuali tanda pagar (# ) diganti dengan garis bawah (_ ), contohnya foo_hometenant.com_EXT_@resourcetenant.com |
|
aud |
Dalam token akses v1, klaim ini digunakan untuk mengubah format klaim aud . Klaim ini tidak berpengaruh pada token v2, atau token ID kedua versi, di mana klaim aud selalu merupakan ID klien. Gunakan konfigurasi ini untuk memastikan bahwa API Anda dapat melakukan validasi audiens dengan lebih mudah. Seperti semua klaim opsional yang memengaruhi token akses, sumber daya dalam permintaan harus menetapkan klaim opsional ini, karena sumber daya memiliki token akses. |
|
use_guid |
Mengeluarkan ID klien sumber daya (API) dalam format GUID selalu sebagai klaim aud alih-alih tergantung pada runtime. Misalnya, jika sumber daya mengatur tanda ini, dan ID kliennya adalah bb0a297b-6a42-4a55-ac40-09a501456577 , aplikasi apa pun yang meminta token akses untuk sumber daya tersebut akan menerima token akses dengan aud : bb0a297b-6a42-4a55-ac40-09a501456577 . Tanpa set klaim ini, API bisa mendapatkan token dengan klaim aud berupa api://MyApi.com , api://MyApi.com/ , api://myapi.com/AdditionalRegisteredField atau nilai lain yang ditetapkan sebagai URI ID aplikasi untuk API tersebut, serta ID klien sumber daya. |
Contoh properti tambahan
"optionalClaims": {
"idToken": [
{
"name": "upn",
"essential": false,
"additionalProperties": [
"include_externally_authenticated_upn"
]
}
]
}
Objek OptionalClaims ini menyebabkan token ID dihasilkan ke klien untuk menyertakan klaim upn
dengan penyewa asal tambahan dan informasi penyewa sumber daya. Klaim upn
hanya diubah dalam token jika pengguna adalah tamu di penyewa (yang menggunakan IDP yang berbeda untuk autentikasi).
Mengonfigurasi klaim opsional
Penting
Token akses selalu dihasilkan menggunakan manifes sumber daya, bukan klien. Sehingga, dalam ...scope=https://graph.microsoft.com/user.read...
permintaan, sumber daya merupakan API Microsoft Graph. Dengan demikian, token akses dibuat menggunakan manifes API Microsoft Graph, bukan manifes klien. Mengubah manifes untuk aplikasi Anda tidak akan menyebabkan token API Microsoft Graph terlihat berbeda. Untuk memvalidasi bahwa perubahan accessToken
bekerja, minta token untuk aplikasi Anda, bukan aplikasi lain.
Anda dapat mengonfigurasi klaim opsional untuk aplikasi dengan menyesuaikan manifes aplikasi.
- Buka portal Microsoft Azure.
- Cari dan pilih Microsoft Azure Active Directory.
- Di bagian Kelola, pilih Pendaftaran aplikasi.
- Pilih aplikasi dalam daftar tempat Anda ingin mengonfigurasi klaim opsional.
Mengonfigurasi klaim opsional melalui UI:
Di bagian Kelola, pilih Konfigurasi token.
- Opsi UI blade Konfigurasi token tidak tersedia untuk aplikasi yang terdaftar di penyewa Azure AD B2C, yang dapat dikonfigurasi dengan menyesuaikan manifes aplikasi. Untuk informasi selengkapnya, lihat Menambahkan klaim dan menyesuaikan input pengguna menggunakan kebijakan kustom di Azure Active Directory B2C
Pilih Tambahkan klaim opsional.
Pilih jenis token yang ingin Anda konfigurasi.
Pilih klaim opsional untuk ditambahkan.
Pilih Tambahkan.
Mengonfigurasi klaim opsional melalui manifes aplikasi:
Di bagian Kelola, pilih Manifes. Editor manifes berbasis web terbuka, yang memungkinkan Anda mengedit manifes. Secara opsional, Anda dapat memilih Unduh untuk mengedit manifes secara lokal, lalu gunakan Unggah untuk menerapkannya kembali ke aplikasi Anda. Untuk informasi selengkapnya tentang manifes aplikasi, lihat Artikel memahami aplikasi manifes Microsoft Azure AD.
Entri manifes aplikasi berikut menambahkan klaim opsional
auth_time
,ipaddr
, danupn
ke ID, akses, dan token SAML."optionalClaims": { "idToken": [ { "name": "auth_time", "essential": false } ], "accessToken": [ { "name": "ipaddr", "essential": false } ], "saml2Token": [ { "name": "upn", "essential": false }, { "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "source": "user", "essential": false } ] }
Setelah selesai, pilih Simpan. Sekarang klaim opsional yang ditentukan akan dimasukkan dalam token untuk aplikasi Anda.
Jenis OptionalClaims
Menyatakan klaim opsional yang diminta oleh aplikasi. Aplikasi dapat mengonfigurasi klaim opsional untuk dihasilkan dalam masing-masing dari tiga jenis token (token ID, token akses, token SAML 2) yang dapat diterima olehnya melalui layanan token keamanan. Aplikasi ini dapat mengonfigurasi set klaim opsional yang berbeda untuk dihasilkan dalam setiap jenis token. Properti OptionalClaims dari entitas Aplikasi adalah objek OptionalClaims.
Tabel 5: Properti jenis OptionalClaims
Nama | Jenis | Deskripsi |
---|---|---|
idToken |
Kumpulan (OptionalClaim) | Klaim opsional dihasilkan dalam token ID JWT. |
accessToken |
Kumpulan (OptionalClaim) | Klaim opsional dihasilkan dalam token akses JWT. |
saml2Token |
Kumpulan (OptionalClaim) | Klaim opsional dihasilkan dalam token SAML. |
Jenis OptionalClaim
Berisi klaim opsional yang terkait dengan aplikasi atau perwakilan layanan. Properti idToken, accessToken, dan saml2Token dari jenis OptionalClaims adalah kumpulan OptionalClaim. Jika didukung oleh klaim tertentu, Anda juga dapat menyesuaikan perilaku OptionalClaim menggunakan bidang AdditionalProperties.
Tabel 6: Properti jenis OptionalClaim
Nama | Jenis | Deskripsi |
---|---|---|
name |
Edm.String | Nama klaim opsional. |
source |
Edm.String | Sumber (objek direktori) klaim. Ada klaim yang ditentukan sebelumnya dan klaim yang ditentukan pengguna dari properti ekstensi. Jika nilai sumber null, klaimnya adalah klaim opsional yang ditentukan. Jika nilai sumber adalah pengguna, nilai dalam properti nama adalah properti ekstensi dari objek pengguna. |
essential |
Edm.Boolean | Jika nilai tersebut true, klaim yang ditentukan oleh klien diperlukan untuk memastikan pengalaman otorisasi yang lancar dengan tugas tertentu yang diminta oleh pengguna akhir. Nilai defaultnya adalah false. |
additionalProperties |
Kumpulan (Edm.String) | Properti tambahan klaim. Jika properti ada dalam kumpulan ini, properti akan menyesuaikan sifat klaim opsional yang ditentukan dalam properti nama. |
Mengonfigurasi klaim opsional ekstensi direktori
Selain klaim opsional standar yang ditetapkan, Anda juga dapat mengonfigurasi token untuk menyertakan ekstensi Microsoft Graph. Untuk informasi selengkapnya, lihat Menambahkan data kustom ke sumber daya menggunakan ekstensi.
Skema dan ekstensi terbuka tidak didukung oleh klaim opsional, hanya ekstensi direktori dan atribut ekstensi. Fitur ini berguna untuk melampirkan informasi pengguna tambahan yang dapat digunakan aplikasi Anda – contohnya, pengidentifikasi tambahan atau opsi konfigurasi penting yang telah ditetapkan pengguna. Lihat bagian bawah halaman ini sebagai contoh.
Ekstensi direktori adalah fitur khusus Azure AD. Jika manifes aplikasi Anda meminta ekstensi khusus, dan pengguna MSA masuk ke aplikasi Anda, ekstensi ini tidak akan dikembalikan.
Pembuatan format ekstensi direktori
Saat mengonfigurasi klaim opsional ekstensi direktori menggunakan manifes aplikasi, gunakan nama lengkap ekstensi (dalam format: extension_<appid>_<attributename>
). <appid>
adalah versi appId yang dilucuti (atau ID Klien) dari aplikasi yang meminta klaim.
Dalam JWT, klaim ini akan dikeluarkan dengan format nama berikut: extn.<attributename>
.
Dalam token SAML, klaim ini akan dikeluarkan dengan format URI berikut: http://schemas.microsoft.com/identity/claims/extn.<attributename>
Mengonfigurasi klaim opsional grup
Bagian ini mencakup opsi konfigurasi di bagian klaim opsional untuk mengubah atribut grup yang digunakan dalam klaim grup dari objectID grup default ke atribut yang disinkronkan dari Direktori Aktif Windows lokal. Anda dapat mengonfigurasi klaim opsional untuk aplikasi dengan menyesuaikan UI atau manifes aplikasi.
Penting
Azure AD membatasi jumlah grup yang akan dikeluarkannya dalam token hingga 150 untuk pernyataan SAML dan 200 untuk JWT, termasuk grup berlapis. Untuk detail selengkapnya tentang batas grup dan peringatan penting untuk klaim grup dari atribut lokal, lihat Mengonfigurasi klaim grup untuk aplikasi dengan Azure AD.
Mengonfigurasi klaim opsional grup melalui UI:
- Masuk ke portal Microsoft Azure.
- Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.
- Cari dan pilih Microsoft Azure Active Directory.
- Di bagian Kelola, pilih Pendaftaran aplikasi.
- Pilih aplikasi dalam daftar tempat Anda ingin mengonfigurasi klaim opsional.
- Di bagian Kelola, pilih Konfigurasi token.
- Pilih Tambah klaim grup.
- Pilih jenis grup yang akan dihasilkan (Grup keamanan, atau peran Direktori, Semua grup, dan/atau Grup yang ditetapkan ke aplikasi).
- Opsi Grup yang Ditetapkan ke aplikasi menyertakan hanya grup yang ditetapkan dalam aplikasi. Opsi Grup yang ditetapkan ke aplikasi direkomendasikan untuk organisasi besar karena batas nomor grup dalam token. Untuk mengubah grup yang ditetapkan ke aplikasi, pilih aplikasi dari daftar Aplikasi Enterprise. Pilih Pengguna dan grup, lalu pilih Tambahkan pengguna/grup. Pilih grup yang ingin Anda tambahkan ke aplikasi dari Pengguna dan grup.
- Opsi Semua Grup mencakup SecurityGroup, DirectoryRole, dan DistributionList, tetapi bukan Grup yang ditetapkan untuk aplikasi.
- Opsional: pilih properti jenis token tertentu untuk menyesuaikan nilai klaim grup yang dikandung pada atribut grup lokal atau untuk mengubah jenis klaim menjadi peran.
- Pilih Simpan.
Mengonfigurasi klaim opsional grup melalui manifes aplikasi:
Masuk ke portal Microsoft Azure.
Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.
Cari dan pilih Microsoft Azure Active Directory.
Pilih aplikasi dalam daftar tempat Anda ingin mengonfigurasi klaim opsional.
Di bagian Kelola, pilih Manifes.
Tambahkan entri berikut menggunakan editor manifes:
Nilai yang valid adalah:
- "Semua" (opsi ini mencakup SecurityGroup, DirectoryRole, dan DistributionList)
- "SecurityGroup"
- "DirectoryRole"
- "ApplicationGroup" (opsi ini hanya mencakup grup yang ditetapkan ke aplikasi)
Contohnya:
"groupMembershipClaims": "SecurityGroup"
Secara default ObjectID Grup akan dikeluarkan dalam nilai klaim grup. Untuk mengubah nilai klaim menjadi berisi atribut grup lokal, atau mengubah jenis klaim menjadi peran, gunakan konfigurasi OptionalClaims sebagai berikut:
Setel klaim opsional konfigurasi nama grup.
Jika Anda ingin grup dalam token terisi dengan atribut grup AD di bagian klaim opsional, tentukan klaim opsional tempat jenis token diterapkan, nama klaim opsional yang diminta, dan semua jenis properti tambahan yang diinginkan. Beberapa jenis token dapat dicantumkan:
- idToken untuk token ID OIDC
- accessToken untuk token akses OAuth
- Saml2Token untuk token SAML.
Jenis Saml2Token berlaku untuk token format SAML1.1 dan SAML2.0.
Untuk setiap jenis token yang relevan, ubah klaim grup untuk menggunakan bagian OptionalClaims dalam manifes. Skema OptionalClaims adalah sebagai berikut:
{ "name": "groups", "source": null, "essential": false, "additionalProperties": [] }
Skema klaim opsional Nilai nama: Harus "grup" sumber: Tidak digunakan. Hilangkan atau tentukan null esensial: Tidak digunakan. Hilangkan atau tentukan false additionalProperties: Daftar properti tambahan. Opsi yang valid adalah "sam_account_name", "dns_domain_and_sam_account_name", "netbios_domain_and_sam_account_name", "emit_as_roles" dan "cloud_displayname" Dalam additionalProperties hanya ada memerlukan satu dari "sam_account_name", “dns_domain_and_sam_account_name”, “netbios_domain_and_sam_account_name”. Jika ada lebih dari satu, yang pertama digunakan dan yang lain diabaikan. Selain itu, Anda dapat menambahkan "cloud_displayname" untuk memancarkan nama tampilan grup cloud. Perhatikan, bahwa opsi ini hanya berfungsi ketika
“groupMembershipClaims”
diatur ke“ApplicationGroup”
.Beberapa aplikasi memerlukan informasi grup tentang pengguna dalam klaim peran. Untuk mengubah jenis klaim dari klaim grup menjadi klaim peran, tambahkan "emit_as_roles" ke properti tambahan. Nilai grup akan dikeluarkan dalam klaim peran.
Jika "emit_as_roles" digunakan, semua jenis peran aplikasi yang dikonfigurasi bahwa pengguna ditetapkan tidak akan muncul dalam klaim peran.
Contoh:
Mengeluarkan grup sebagai nama grup dalam token akses OAuth dalam format dnsDomainName\sAMAccountName
Konfigurasi UI:
Entri manifes aplikasi:
"optionalClaims": { "accessToken": [ { "name": "groups", "additionalProperties": [ "dns_domain_and_sam_account_name" ] } ] }
Mengeluarkan nama grup yang akan dihasilkan dalam format netbiosDomain\sAMAccountName sebagai klaim peran dalam Token ID SAML dan OIDC
Konfigurasi UI:
Entri manifes aplikasi:
"optionalClaims": { "saml2Token": [ { "name": "groups", "additionalProperties": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ], "idToken": [ { "name": "groups", "additionalProperties": [ "netbios_domain_and_sam_account_name", "emit_as_roles" ] } ] }
Keluarkan nama grup dalam format samAccountName untuk grup yang disinkronkan lokal dan nama tampilan untuk grup cloud di Saml dan Token ID OIDC untuk grup yang ditetapkan ke aplikasi:
Entri manifes aplikasi:
"groupMembershipClaims": "ApplicationGroup", "optionalClaims": { "saml2Token": [ { "name": "groups", "additionalProperties": [ "sam_account_name", "cloud_displayname" ] } ], "idToken": [ { "name": "groups", "additionalProperties": [ "sam_account_name", "cloud_displayname" ] } ] }
Contoh klaim opsional
Di bagian ini, Anda dapat menelusuri skenario untuk melihat jika Anda dapat menggunakan fitur klaim opsional untuk aplikasi Anda. Ada beberapa opsi yang tersedia untuk memperbarui properti pada konfigurasi identitas aplikasi untuk mengaktifkan dan mengonfigurasi klaim opsional:
- Anda dapat menggunakan UI Konfigurasi token (lihat contoh di bawah)
- Anda dapat menggunakan Manifes (lihat contoh di bawah). Baca Memahami dokumen manifes aplikasi Microsoft Azure AD sebelumnya untuk pengenalan dengan manifes.
- Anda juga dapat menulis aplikasi yang menggunakan API Microsoft Graph untuk memperbarui aplikasi Anda. Jenis OptionalClaims dalam panduan referensi API Microsoft Graph dapat membantu Anda mengonfigurasi klaim opsional.
Contoh:
Dalam contoh berikut, Anda akan menggunakan UI Konfigurasi token dan Manifes untuk menambahkan klaim opsional ke token akses, ID, dan SAML yang ditujukan untuk aplikasi Anda. Beragam klaim opsional akan ditambahkan ke setiap jenis token yang dapat diterima aplikasi:
- Token ID sekarang akan berisi UPN untuk pengguna gabungan dalam bentuk lengkap (
<upn>_<homedomain>#EXT#@<resourcedomain>
). - Token akses yang diminta klien lain untuk aplikasi ini sekarang akan mencakup klaim auth_time.
- Token SAML sekarang akan berisi ekstensi skema direktori skypeId (dalam contoh ini, ID aplikasi untuk aplikasi ini adalah ab603c56068041afb2f6832e2a17e237). Token SAML akan mengekspos ID Skype sebagai
extension_ab603c56068041afb2f6832e2a17e237_skypeId
.
Konfigurasi UI:
Masuk ke portal Microsoft Azure.
Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.
Cari dan pilih Microsoft Azure Active Directory.
Di bagian Kelola, pilih Pendaftaran aplikasi.
Pilih aplikasi tempat Anda ingin mengonfigurasi klaim opsional dalam daftar.
Di bagian Kelola, pilih Konfigurasi token.
Pilih Tambah klaim opsional, pilih jenis token ID, pilih upn dari daftar klaim, lalu pilih Tambahkan.
Pilih Tambah klaim opsional, pilih jenis token Akses, pilih auth_time dari daftar klaim, lalu pilih Tambahkan.
Dari layar gambaran umum Konfigurasi Token, pilih ikon pensil di samping upn, pilih tombol Diautentikasi secara eksternal, lalu pilih Simpan.
Pilih Tambahkan klaim opsional, pilih jenis token SAML, pilih extn.skypeID dari daftar klaim (hanya berlaku jika Anda telah membuat objek pengguna Microsoft Azure AD yang disebut skypeID), lalu pilih Tambahkan.
Konfigurasi manifes:
Masuk ke portal Microsoft Azure.
Setelah mengautentikasi, pilih penyewa Microsoft Azure AD Anda dengan memilihnya dari sudut kanan atas halaman.
Cari dan pilih Microsoft Azure Active Directory.
Pilih aplikasi tempat Anda ingin mengonfigurasi klaim opsional dalam daftar.
Di bagian Kelola, pilih Manifes untuk membuka editor manifes sebaris.
Anda dapat langsung mengedit manifes menggunakan editor ini. Manifes mengikuti skema untuk Entitas aplikasi, dan membuat format manifes setelah disimpan secara otomatis. Elemen baru akan ditambahkan ke properti
OptionalClaims
."optionalClaims": { "idToken": [ { "name": "upn", "essential": false, "additionalProperties": [ "include_externally_authenticated_upn" ] } ], "accessToken": [ { "name": "auth_time", "essential": false } ], "saml2Token": [ { "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId", "source": "user", "essential": true } ] }
Setelah selesai memperbarui manifes, pilih Simpan untuk menyimpan manifes.
Langkah berikutnya
Pelajari selengkapnya tentang klaim standar yang disediakan Microsoft Azure AD.