Referensi klaim token akses
Token akses adalah token web JSON (JWT). JWT berisi potongan-potongan berikut:
- Header - Menyediakan informasi tentang cara memvalidasi token termasuk informasi tentang jenis token dan metode penandatanganannya.
- Payload - Berisi semua data penting tentang pengguna atau aplikasi yang mencoba memanggil layanan.
- Tanda tangan - Apakah bahan baku digunakan untuk memvalidasi token.
Setiap bagian dipisahkan oleh titik (.) dan dikodekan secara terpisah Base 64.
Klaim hanya ada jika ada nilai untuk mengisinya. Aplikasi tidak boleh bergantung pada klaim yang ada. Contohnya termasuk pwd_exp (tidak setiap penyewa memerlukan kata sandi untuk kedaluwarsa) dan alur family_name (informasi masuk klien atas nama aplikasi yang tidak memiliki nama). Token akses akan selalu berisi klaim yang memadai untuk evaluasi akses.
platform identitas Microsoft menggunakan beberapa klaim untuk membantu mengamankan token untuk digunakan kembali. Deskripsi Opaque menandai klaim ini sebagai bukan untuk konsumsi publik. Klaim ini mungkin atau mungkin tidak muncul dalam token, dan yang baru dapat ditambahkan tanpa pemberitahuan.
Klaim header
| Klaim | Format | Deskripsi |
|---|---|---|
typ |
String - selalu JWT |
Menunjukkan bahwa token adalah JWT. |
alg |
String | Menunjukkan algoritma yang digunakan untuk menandatangani token, misalnya, RS256. |
kid |
String | Menentukan thumbprint untuk kunci publik yang digunakan untuk memvalidasi tanda tangan token. Dipancarkan dalam token akses v1.0 dan v2.0. |
x5t |
String | Fungsi yang sama (dalam penggunaan dan nilai) sebagai kid. x5t merupakan klaim warisan yang dikeluarkan hanya dalam token akses v1.0 untuk tujuan kompatibilitas. |
Klaim payload
| Klaim | Format | Deskripsi | Pertimbangan otorisasi |
|---|---|---|---|
acrs |
String array JSON | Menunjukkan ID Konteks Autentikasi operasi yang memenuhi syarat untuk dilakukan oleh pembawa. ID Konteks Autentikasi dapat digunakan untuk memicu permintaan autentikasi peningkatan dari dalam aplikasi dan layanan Anda. Sering digunakan bersama dengan xms_cc klaim. |
|
aud |
String, URI atau GUID ID Aplikasi | Mengidentifikasi audiens token yang dimaksud. Dalam token v2.0, nilai ini selalu berupa ID klien API. Dalam token v1.0, nilai tersebut bisa berupa ID klien atau URI sumber daya yang digunakan dalam permintaan. Nilai dapat bergantung pada cara klien meminta token. | Nilai ini harus divalidasi, tolak token jika nilainya tidak cocok dengan audiens yang dimaksud. |
iss |
String, URI layanan token keamanan (STS) | Mengidentifikasi STS yang membangun dan mengembalikan token, dan penyewa Microsoft Entra dari pengguna yang diautentikasi. Jika token yang dikeluarkan adalah token v2.0 (lihat klaim ver), URI akan berakhir pada /v2.0. GUID yang menunjukkan bahwa pengguna adalah pengguna konsumen dari akun Microsoft adalah 9188040d-6c67-4c5b-b112-36a304b66dad. |
Aplikasi Anda dapat menggunakan bagian GUID klaim untuk membatasi kumpulan penyewa yang dapat masuk ke aplikasi, jika berlaku. |
idp |
String, biasanya STS URI | Merekam penyedia identitas yang mengautentikasi subjek token. Nilai ini identik dengan nilai klaim Penerbit kecuali jika akun pengguna tidak berada di penyewa yang sama dengan penerbit, seperti tamu. Gunakan nilai iss jika klaim tidak ada. Untuk akun pribadi yang digunakan dalam konteks organisasi (misalnya, akun pribadi yang diundang ke penyewa Microsoft Entra), idp klaimnya mungkin 'live.com' atau URI STS yang berisi penyewa 9188040d-6c67-4c5b-b112-36a304b66dadakun Microsoft . |
|
iat |
int, tanda waktu Unix | Menentukan kapan autentikasi untuk token ini terjadi. | |
nbf |
int, tanda waktu Unix | Menentukan waktu setelah JWT dapat diproses. | |
exp |
int, tanda waktu Unix | Menentukan waktu kedaluwarsa sebelum JWT dapat diterima untuk diproses. Sumber daya juga dapat menolak token sebelum waktu ini. Penolakan dapat terjadi untuk perubahan autentikasi yang diperlukan atau ketika token dicabut. | |
aio |
String Buram | Klaim internal yang digunakan oleh ID Microsoft Entra untuk merekam data untuk penggunaan kembali token. Sumber daya tidak boleh menggunakan klaim ini. | |
acr |
String, 0 atau 1, hanya ada dalam token v1.0 |
Nilai 0 untuk klaim "Kelas konteks autentikasi" menunjukkan autentikasi pengguna akhir tidak memenuhi persyaratan ISO/IEC 29115. |
|
amr |
Array string JSON hanya ada dalam token v1.0 | Mengidentifikasi metode autentikasi subjek token. | |
appid |
String dan sebuah GUID hanya ada dalam token v1.0 | ID aplikasi klien yang menggunakan token. Aplikasi dapat bertindak sebagai dirinya sendiri atau atas nama pengguna. ID aplikasi biasanya mewakili objek aplikasi, tetapi juga dapat mewakili objek perwakilan layanan di ID Microsoft Entra. | appid dapat digunakan dalam keputusan otorisasi. |
azp |
String dan sebuah GUID hanya ada dalam token v2.0 | Pengganti untuk appid. ID aplikasi klien yang menggunakan token. Aplikasi dapat bertindak sebagai dirinya sendiri atau atas nama pengguna. ID aplikasi biasanya mewakili objek aplikasi, tetapi juga dapat mewakili objek perwakilan layanan di ID Microsoft Entra. |
azp dapat digunakan dalam keputusan otorisasi. |
appidacr |
String, 0, 1, atau 2, hanya ada dalam token v1.0 |
Menunjukkan metode autentikasi klien. Untuk klien publik, nilainya adalah 0. Saat Anda menggunakan ID klien dan rahasia klien, nilainya adalah 1. Saat Anda menggunakan sertifikat klien untuk autentikasi, nilainya adalah 2. |
|
azpacr |
String, 0, 1, atau 2, hanya ada dalam token v2.0 |
Pengganti untuk appidacr. Menunjukkan metode autentikasi klien. Untuk klien publik, nilainya adalah 0. Saat Anda menggunakan ID klien dan rahasia klien, nilainya adalah 1. Saat Anda menggunakan sertifikat klien untuk autentikasi, nilainya adalah 2. |
|
preferred_username |
String hanya ada dalam token v2.0. | Nama pengguna utama yang merepresentasikan pengguna. Ini bisa berupa alamat email, nomor telepon, atau nama pengguna generik tanpa format tertentu. Gunakan nilai untuk petunjuk nama pengguna dan di UI yang dapat dibaca manusia sebagai nama pengguna. Untuk menerima klaim ini, gunakan profile cakupan. |
Karena nilai ini dapat diubah, jangan gunakan untuk membuat keputusan otorisasi. |
name |
String | Memberi nilai yang dapat dibaca manusia yang mengidentifikasi subjek token. Nilainya dapat bervariasi, dapat diubah, dan hanya untuk tujuan tampilan. Untuk menerima klaim ini, gunakan profile cakupan. |
Jangan gunakan nilai ini untuk membuat keputusan otorisasi. |
scp |
Daftar cakupan yang dipisah spasi | Kumpulan cakupan yang diekspos oleh aplikasi yang telah diminta (dan diterima) oleh aplikasi klien. Hanya disertakan untuk token pengguna. | Aplikasi harus memverifikasi bahwa cakupan ini valid yang diekspos oleh aplikasi, dan membuat keputusan otorisasi berdasarkan nilai cakupan ini. |
roles |
Array string, daftar izin | Kumpulan izin yang diekspos oleh aplikasi yang telah diberi izin untuk dipanggil oleh aplikasi atau pengguna yang meminta. Alur kredensial klien menggunakan sekumpulan izin ini sebagai pengganti cakupan pengguna untuk token aplikasi. Untuk token pengguna, kumpulan nilai ini berisi peran pengguna yang ditetapkan pada aplikasi target. | Nilai-nilai ini dapat digunakan untuk mengelola akses, seperti memberlakukan otorisasi untuk mengakses sumber daya. |
wids |
Array RoleTemplateID GUID | Menunjukkan peran seluruh penyewa yang ditetapkan untuk pengguna ini, dari bagian peran yang ada dalam peran bawaan Microsoft Entra. Properti groupMembershipClaimsmanifes aplikasi mengonfigurasi klaim ini berdasarkan per aplikasi. Atur klaim ke All atau DirectoryRole. Mungkin tidak ada dalam token yang diperoleh melalui alur implisit karena kekhawatiran panjang token. |
Nilai-nilai ini dapat digunakan untuk mengelola akses, seperti memberlakukan otorisasi untuk mengakses sumber daya. |
groups |
Array JSON dari GUID | Menyediakan ID objek yang mewakili keanggotaan grup subjek. Properti groupMembershipClaimsmanifes aplikasi mengonfigurasi klaim grup berdasarkan per aplikasi. Nilai null mengecualikan semua grup, nilai SecurityGroup hanya mencakup keanggotaan Kelompok Keamanan Active Directory, dan nilai All mencakup Kelompok Keamanan dan Daftar Distribusi Microsoft 365. Lihat klaim hasgroups di bawah ini untuk detail tentang penggunaan klaim groups dengan pemberian implisit. Untuk alur lain, jika jumlah grup yang digunakan pengguna melebihi 150 untuk SAML dan 200 untuk JWT, maka MICROSOFT Entra ID menambahkan klaim kelebihan penggunaan ke sumber klaim. Sumber klaim mengarah ke titik akhir Microsoft Graph yang berisi daftar grup untuk pengguna. |
Nilai-nilai ini dapat digunakan untuk mengelola akses, seperti memberlakukan otorisasi untuk mengakses sumber daya. |
hasgroups |
Boolean | Jika ada, selalu true, menunjukkan apakah pengguna berada dalam setidaknya satu grup. Digunakan sebagai pengganti klaim groups untuk JWT dalam alur pemberian izin implisit jika klaim grup penuh akan memperluas fragmen URI melampaui batas panjang URL (saat ini enam grup atau lebih). Menunjukkan bahwa klien harus menggunakan API Microsoft Graph untuk menentukan grup (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects) pengguna. |
|
groups:src1 |
Objek JSON | Menyertakan tautan ke daftar grup lengkap untuk pengguna saat permintaan token terlalu besar untuk token. Untuk JWTs sebagai klaim terdistribusi, untuk SAML sebagai klaim baru yang menggantikan klaim groups. Contoh Nilai JWT: "groups":"src1" "_claim_sources: "src1" : { "endpoint" : "https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects" } |
|
sub |
String | Prinsipal yang terkait dengan token. Misalnya, pengguna aplikasi. Nilai ini tidak dapat diubah, jangan menetapkan ulang atau menggunakan kembali. Subjek adalah pengidentifikasi berpasangan yang unik untuk ID aplikasi tertentu. Jika satu pengguna masuk ke dua aplikasi yang berbeda menggunakan dua ID klien yang berbeda, aplikasi tersebut akan menerima dua nilai berbeda untuk klaim subjek. Menggunakan dua nilai yang berbeda tergantung pada arsitektur dan persyaratan privasi. Lihat juga oid klaim, yang tetap sama di seluruh aplikasi dalam penyewa. |
Nilai ini dapat digunakan untuk melakukan pemeriksaan otorisasi, seperti ketika token digunakan untuk mengakses sumber daya, dan dapat digunakan sebagai kunci dalam tabel database. |
oid |
String, GUID | Pengidentifikasi yang tidak dapat diubah untuk pemohon, yang merupakan identitas terverifikasi pengguna atau perwakilan layanan. ID ini secara unik mengidentifikasi pemohon di seluruh aplikasi. Dua aplikasi berbeda yang masuk ke pengguna yang sama menerima nilai yang sama dalam klaim oid. Karena itu, oid dapat digunakan saat membuat kueri ke layanan online Microsoft, seperti Microsoft Graph. Microsoft Graph akan mengembalikan ID ini sebagai properti id untuk akun pengguna tertentu. oid Karena memungkinkan beberapa aplikasi untuk menghubungkan prinsipal, untuk menerima klaim ini bagi pengguna menggunakan profile cakupan. Jika pengguna tunggal ada di beberapa penyewa, pengguna berisi ID objek yang berbeda di setiap penyewa. Meskipun pengguna masuk ke setiap akun dengan kredensial yang sama, akunnya berbeda. |
Nilai ini dapat digunakan untuk melakukan pemeriksaan otorisasi, seperti ketika token digunakan untuk mengakses sumber daya, dan dapat digunakan sebagai kunci dalam tabel database. |
tid |
String, GUID | Mewakili penyewa tempat pengguna masuk. Untuk akun kantor dan sekolah, GUID adalah ID penyewa yang tidak dapat diubah dari organisasi tempat pengguna masuk. Untuk aktivitas masuk ke penyewa akun Microsoft pribadi (layanan seperti Xbox, Teams for Life, atau Outlook), nilainya adalah 9188040d-6c67-4c5b-b112-36a304b66dad. Untuk menerima klaim ini, aplikasi Anda harus meminta cakupan profile. |
Nilai ini harus dipertimbangkan dalam kombinasi dengan klaim lain dalam keputusan otorisasi. |
unique_name |
String hanya ada dalam token v1.0 | Memberi nilai yang dapat dibaca manusia yang mengidentifikasi subjek token. | Nilai ini dapat berbeda dalam penyewa dan menggunakannya hanya untuk tujuan tampilan. |
uti |
String | Klaim pengidentifikasi token, setara dengan jti dalam spesifikasi JWT. Pengidentifikasi unik per-token yang peka huruf besar/kecil. |
|
rh |
String Buram | Klaim internal yang digunakan azure untuk memrevalidasi ulang token. Sumber daya tidak boleh menggunakan klaim ini. | |
ver |
String, baik 1.0 atau 2.0 |
Menunjukkan versi token akses. | |
xms_cc |
String array JSON | Menunjukkan apakah aplikasi klien yang memperoleh token mampu menangani tantangan klaim. Ini sering digunakan bersama dengan klaim acrs. Klaim ini umumnya digunakan dalam skenario Akses Bersyariah dan Evaluasi Akses Berkelanjutan. Server sumber daya atau aplikasi layanan yang dikeluarkan token untuk mengontrol keberadaan klaim ini dalam token. Nilai cp1 dalam token akses adalah cara otoritatif untuk mengidentifikasi bahwa aplikasi klien mampu menangani tantangan klaim. Untuk informasi selengkapnya, lihat Tantangan klaim, permintaan klaim, dan kemampuan klien. |
Klaim ekses grup
ID Microsoft Entra membatasi jumlah ID objek yang disertakan dalam klaim grup untuk tetap berada dalam batas ukuran header HTTP. Jika pengguna adalah anggota lebih banyak grup daripada batas kelebihan penggunaan (150 untuk token SAML, 200 untuk token JWT, dan hanya 6 jika dikeluarkan dengan menggunakan alur implisit), maka ID Microsoft Entra tidak mengeluarkan klaim grup dalam token. Sebaliknya, ini mencakup klaim ekses penggunaan dalam token yang menunjukkan kepada aplikasi untuk meminta Microsoft Graph API untuk mengambil keanggotaan grup pengguna.
{
...
"_claim_names": {
"groups": "src1"
},
"_claim_sources": {
"src1": {
"endpoint": "[Url to get this user's group membership from]"
}
}
...
}
Gunakan BulkCreateGroups.ps1 yang disediakan di folder App Creation Scripts untuk membantu menguji skenario ekses.
Catatan
URL yang dikembalikan akan menjadi URL Azure AD Graph (yaitu, graph.windows.net). Alih-alih mengandalkan URL ini, layanan harus menggunakan idtyp klaim opsional (yang mengidentifikasi apakah token adalah token aplikasi atau aplikasi+pengguna) untuk membuat URL Microsoft Graph untuk mengkueri daftar lengkap grup.
v1.0 klaim dasar
Token v1.0 mencakup klaim berikut jika berlaku, tetapi bukan token v2.0 secara default. Untuk menggunakan klaim ini dalam v2.0, aplikasi meminta mereka menggunakan klaim opsional.
| Klaim | Format | Deskripsi |
|---|---|---|
ipaddr |
String | Alamat IP dari mana pengguna diautentikasi. |
onprem_sid |
String, dalam format SID | Dalam kasus saat pengguna memiliki autentikasi lokal, klaim ini menyediakan SID-nya. Gunakan klaim ini untuk otorisasi dalam aplikasi lama. |
pwd_exp |
int, tanda waktu Unix | Menunjukkan kapan kata sandi pengguna kedaluwarsa. |
pwd_url |
String | URL tempat pengguna dapat mengatur ulang kata sandi mereka. |
in_corp |
Boolean | Beri sinyal jika klien masuk dari jaringan perusahaan. |
nickname |
String | Nama tambahan untuk pengguna, terpisah dari nama depan atau belakang. |
family_name |
String | Menyediakan nama belakang, nama keluarga, atau nama keluarga pengguna seperti yang ditentukan pada objek pengguna. |
given_name |
String | Menyediakan nama pengguna pertama atau yang diberikan, sebagaimana diatur pada objek pengguna. |
upn |
String | Nama pengguna dari pengguna. Mungkin nomor telepon, alamat email, atau string yang tidak diformat. Hanya gunakan untuk tujuan tampilan dan memberikan petunjuk nama pengguna dalam skenario autentikasi ulang. |
klaim amr
Identitas dapat diautentikasi dengan cara yang berbeda, yang mungkin relevan dengan aplikasi Anda. Klaim amr adalah array yang dapat berisi beberapa item, seperti ["mfa", "rsa", "pwd"], untuk autentikasi yang menggunakan kata sandi dan aplikasi Authenticator.
| Nilai | Deskripsi |
|---|---|
pwd |
Autentikasi kata sandi, kata sandi Microsoft pengguna atau rahasia klien aplikasi. |
rsa |
Autentikasi didasarkan pada bukti kunci RSA, misalnya dengan aplikasi Microsoft Authenticator. Nilai ini juga menunjukkan penggunaan JWT yang ditandatangani sendiri dengan sertifikat X509 milik layanan dalam autentikasi. |
otp |
Kode sandi satu kali menggunakan email atau pesan teks. |
fed |
Menunjukkan penggunaan pernyataan autentikasi federasi (seperti JWT atau SAML). |
wia |
Windows Integrated Authentication |
mfa |
Menunjukkan penggunaan autentikasi Multifaktor. Termasuk metode autentikasi lainnya saat klaim ini ada. |
ngcmfa |
Setara dengan mfa, digunakan untuk penyediaan jenis informasi masuk tingkat lanjut tertentu. |
wiaormfa |
Pengguna menggunakan Windows atau mandat MFA untuk mengautentikasi. |
none |
Menunjukkan tidak ada autentikasi yang selesai. |
Langkah berikutnya
- Pelajari selengkapnya tentang token akses yang digunakan dalam ID Microsoft Entra.