Konfigurasikan klaim opsional

Token yang dikembalikan Microsoft Entra disimpan lebih kecil untuk memastikan performa optimal oleh klien yang memintanya. Akibatnya, beberapa klaim tidak lagi ada dalam token secara default dan harus diminta secara khusus per aplikasi.

Anda dapat mengonfigurasi klaim opsional untuk aplikasi Anda melalui UI atau manifes aplikasi pusat admin Microsoft Entra.

Prasyarat

• Akun Azure dengan langganan aktif. Buat akun secara gratis.
• Penyelesaian Mulai Cepat: Mendaftarkan aplikasi

Mengonfigurasi klaim opsional di aplikasi Anda

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
2. Telusuri Aplikasi >Identitas>Pendaftaran aplikasi.
3. Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya berdasarkan skenario dan hasil yang diinginkan.

Lanjutkan dengan UI aplikasi

1. Di bagian Kelola, pilih Konfigurasi token.
2. Pilih Tambahkan klaim opsional.
3. Pilih jenis token yang ingin Anda konfigurasi, seperti Access.
4. Pilih klaim opsional untuk ditambahkan.
5. Pilih Tambahkan.

Lanjutkan dengan manifes

1. 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. Jika file tidak berisi optionalClaims properti, Anda dapat menambahkannya.

   Entri manifes aplikasi berikut menambahkan klaim opsional auth_time, ipaddr, dan upn 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
           }
       ]
   }
   

2. Setelah selesai, pilih Simpan. Sekarang klaim opsional yang ditentukan disertakan dalam token untuk aplikasi Anda.

Objek optionalClaims menyatakan klaim opsional yang diminta oleh aplikasi. Aplikasi dapat mengonfigurasi klaim opsional yang dikembalikan dalam token ID, token akses, dan token SAML 2. Aplikasi ini dapat mengonfigurasi set klaim opsional yang berbeda untuk dihasilkan dalam setiap jenis token.

Nama	Tipe	Deskripsi
idToken	Koleksi	Klaim opsional dihasilkan dalam token ID JWT.
accessToken	Koleksi	Klaim opsional dihasilkan dalam token akses JWT.
saml2Token	Koleksi	Klaim opsional dihasilkan dalam token SAML.

Jika didukung oleh klaim tertentu, Anda juga dapat memodifikasi perilaku klaim opsional menggunakan additionalProperties bidang .

Nama	Tipe	Description
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 klaim lainnya. 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.

Penting

Token akses selalu dihasilkan menggunakan manifes sumber daya, bukan klien. Dalam permintaan ...scope=https://graph.microsoft.com/user.read..., sumber dayanya adalah Microsoft Graph API. Token akses dibuat menggunakan manifes Microsoft Graph API, bukan manifes klien. Mengubah manifes untuk aplikasi Anda tidak pernah menyebabkan token untuk Microsoft Graph API terlihat berbeda. Untuk memvalidasi bahwa perubahan Anda accessToken berlaku, minta token untuk aplikasi Anda, bukan aplikasi lain.

Klaim opsional mendukung atribut ekstensi dan ekstensi direktori. Fitur ini berguna untuk melampirkan lebih banyak informasi pengguna yang dapat digunakan aplikasi Anda. Misalnya, pengidentifikasi lain atau opsi konfigurasi penting yang telah ditetapkan pengguna. Jika manifes aplikasi Anda meminta ekstensi kustom dan pengguna MSA masuk ke aplikasi Anda, ekstensi ini tidak 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 dipancarkan dengan format nama berikut: extn.<attributename>. Dalam token SAML, klaim ini dipancarkan dengan format URI berikut: http://schemas.microsoft.com/identity/claims/extn.<attributename>

Mengonfigurasi klaim opsional grup

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

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 grup untuk aplikasi Anda melalui manifes portal Azure atau aplikasi. Klaim opsional grup hanya dipancarkan di JWT untuk prinsipal pengguna. Perwakilan layanan tidak disertakan dalam klaim opsional grup yang dikeluarkan dalam JWT.

Penting

Jumlah grup yang dikeluarkan dalam token dibatasi hingga 150 untuk pernyataan SAML dan 200 untuk JWT, termasuk grup bersarang. Untuk informasi selengkapnya tentang batas grup dan peringatan penting untuk klaim grup dari atribut lokal, lihat Mengonfigurasi klaim grup untuk aplikasi.

Selesaikan langkah-langkah berikut untuk mengonfigurasi klaim opsional grup menggunakan portal Azure:

1. Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.
2. Di bagian Kelola, pilih Konfigurasi token.
3. Pilih Tambah klaim grup.
4. Pilih jenis grup yang akan dikembalikan (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.
5. Opsional: pilih properti jenis token tertentu untuk menyesuaikan nilai klaim grup yang dikandung pada atribut grup lokal atau untuk mengubah jenis klaim menjadi peran.
6. Pilih Simpan.

Selesaikan langkah-langkah berikut untuk mengonfigurasi klaim opsional grup melalui manifes aplikasi:

1. Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.

2. Di bagian Kelola, pilih Manifes.

3. 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 ID objek grup dipancarkan dalam nilai klaim grup. Untuk mengubah nilai klaim agar berisi atribut grup lokal, atau untuk mengubah jenis klaim menjadi peran, gunakan optionalClaims konfigurasi sebagai berikut:

4. Setel klaim opsional konfigurasi nama grup.

   Jika Anda ingin grup dalam token berisi atribut grup lokal di bagian klaim opsional, tentukan klaim opsional jenis token mana yang harus diterapkan. Anda juga menentukan nama klaim opsional yang diminta dan properti lain yang diinginkan.

   Beberapa jenis token dapat dicantumkan:

   • idToken untuk token ID OIDC
   • accessToken untuk token akses OAuth
   • Saml2Token untuk token SAML.

   Jenis ini Saml2Token berlaku untuk token format SAML1.1 dan SAML2.0.

   Untuk setiap jenis token yang relevan, ubah klaim grup untuk menggunakan optionalClaims bagian dalam manifes. Skema optionalClaims adalah sebagai berikut:

   {
       "name": "groups",
       "source": null,
       "essential": false,
       "additionalProperties": []
   }
   

   Skema klaim opsional	Nilai
   name	Harus berupa groups
   source	Tidak digunakan. Hilangkan atau tentukan null.
   essential	Tidak digunakan. Hilangkan atau tentukan false.
   additionalProperties	Daftar properti lainnya. 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.

   Hanya additionalProperties di salah sam_account_namesatu dari , dns_domain_and_sam_account_name, netbios_domain_and_sam_account_name diperlukan. Jika ada lebih dari satu, yang pertama digunakan dan yang lain diabaikan. Anda juga dapat menambahkan cloud_displayname untuk memancarkan nama tampilan grup cloud. 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 additionalProperties. Nilai grup dipancarkan dalam klaim peran.

   Jika emit_as_roles digunakan, peran aplikasi apa pun yang dikonfigurasi bahwa pengguna (atau aplikasi sumber daya) ditetapkan tidak berada dalam klaim peran.

Contoh berikut menunjukkan konfigurasi manifes untuk klaim grup:

Keluarkan grup sebagai nama grup dalam token akses OAuth dalam dnsDomainName\sAMAccountName format.

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

Keluarkan nama grup yang akan dikembalikan dalam netbiosDomain\sAMAccountName format sebagai klaim peran dalam token ID SAML dan OIDC.

"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 sam_account_name untuk grup dan cloud_display nama yang disinkronkan lokal untuk grup cloud dalam token ID SAML dan OIDC untuk grup yang ditetapkan ke 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

Ada beberapa opsi yang tersedia untuk memperbarui properti pada konfigurasi identitas aplikasi untuk mengaktifkan dan mengonfigurasi klaim opsional:

• Anda dapat menggunakan portal Azure
• Anda dapat menggunakan 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.

Dalam contoh berikut, portal Azure dan manifes digunakan untuk menambahkan klaim opsional ke token akses, ID, dan SAML yang ditujukan untuk aplikasi Anda. Klaim opsional yang berbeda ditambahkan ke setiap jenis token yang dapat diterima aplikasi:

• Token ID berisi UPN untuk pengguna federasi dalam bentuk lengkap (<upn>_<homedomain>#EXT#@<resourcedomain>).
• Token akses yang diminta klien lain untuk aplikasi ini menyertakan auth_time klaim.
• Token SAML berisi skypeId ekstensi skema direktori (dalam contoh ini, ID aplikasi untuk aplikasi ini adalah ab603c56068041afb2f6832e2a17e237). Token SAML mengekspos ID Skype sebagai extension_ab603c56068041afb2f6832e2a17e237_skypeId.

Konfigurasikan klaim di portal Azure:

1. Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.
2. Di bagian Kelola, pilih Konfigurasi token.
3. Pilih Tambah klaim opsional, pilih jenis token ID, pilih upn dari daftar klaim, lalu pilih Tambahkan.
4. Pilih Tambah klaim opsional, pilih jenis token Akses, pilih auth_time dari daftar klaim, lalu pilih Tambahkan.
5. Dari layar gambaran umum Konfigurasi Token, pilih ikon pensil di samping upn, pilih tombol Diautentikasi secara eksternal, lalu pilih Simpan.
6. Pilih Tambahkan klaim opsional, pilih jenis token SAML , pilih extn.skypeID dari daftar klaim (hanya berlaku jika Anda telah membuat objek pengguna Microsoft Entra yang disebut skypeID), lalu pilih Tambahkan.

Konfigurasikan klaim dalam manifes:

1. Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.

2. Di bagian Kelola, pilih Manifes untuk membuka editor manifes sebaris.

3. Anda dapat langsung mengedit manifes menggunakan editor ini. Manifes mengikuti skema untuk Entitas aplikasi, dan membuat format manifes setelah disimpan secara otomatis. Elemen baru ditambahkan ke optionalClaims properti .

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

4. Setelah selesai memperbarui manifes, pilih Simpan untuk menyimpan manifes.

Konten terkait

• Token akses
• Manifes aplikasi
• Token ID
• Referensi klaim opsional