Mengonfigurasi dan mengelola klaim opsional dalam token ID, token akses, dan token SAML

2025-01-27

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

Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
Telusuri Entra ID>pendaftaran Aplikasi.
Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya berdasarkan skenario dan hasil yang diinginkan.

Lanjutkan dengan UI aplikasi
Lanjutkan dengan daftar manifes

Di bawah Kelola, pilih Konfigurasi token.
Pilih Tambahkan klaim opsional.
Pilih jenis token yang ingin Anda konfigurasi, seperti Access.
Pilih klaim opsional untuk ditambahkan.
Pilih Tambahkan.

Di bawah Kelola, pilih Manifes. Editor manifes berbasis web terbuka, yang memungkinkan Anda mengedit manifes. Secara opsional, Anda dapat memilih Unduh dan edit 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
        }
    ]
}

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

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:

Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.
Di bawah Kelola, pilih Konfigurasi token.
Pilih Tambahkan klaim grup.
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 hanya menyertakan grup yang ditetapkan ke 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 perusahaan . Pilih Pengguna dan grup lalu 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 ke 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.

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

Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.
Di bawah Kelola, pilih Manifes.
Tambahkan entri berikut menggunakan editor manifes:

Nilai yang valid adalah:
- "Semua" (opsi ini mencakup SecurityGroup, DirectoryRole, dan DistributionList)
- Grup Keamanan
- "Peran Direktori"
- "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:

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 Microsoft Graph API untuk memperbarui aplikasi Anda. Jenis OptionalClaims dalam panduan referensi Microsoft Graph API 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:

Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.
Di bawah Kelola, pilih Konfigurasi token.
Pilih Tambahkan klaim opsional, pilih jenis token ID , pilih upn dari daftar klaim, lalu pilih Tambahkan.
Pilih Tambahkan klaim opsional, pilih Jenis token akses , pilih auth_time dari daftar klaim, lalu pilih Tambahkan.
Dari layar Ringkasan Konfigurasi Token, pilih ikon pensil di samping upn, pilih tombol Diautentikasi 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 Entra yang disebut skypeID), lalu pilih Tambahkan.

Konfigurasikan klaim dalam manifes:

Pilih aplikasi yang ingin Anda konfigurasikan klaim opsionalnya.
Di bawah Kelola, pilih Manifes untuk membuka editor manifes sebaris.

Anda dapat langsung mengedit manifes menggunakan editor ini. Manifes mengikuti skema untuk entitas Aplikasi, dan secara otomatis memformat manifes setelah disimpan. 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
        }
    ]
}

Setelah selesai memperbarui manifes, pilih Simpan untuk menyimpan manifes.

Pembatasan

Aplikasi dapat mengeluarkan jumlah maksimum 10 atribut ekstensi sebagai klaim opsional.

Bagikan melalui