Bagikan melalui


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 groupMembershipClaims manifes aplikasi mengonfigurasi klaim ini berdasarkan per aplikasi. Atur klaim ke All atau DirectoryRole. 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 groupMembershipClaims manifes aplikasi mengonfigurasi klaim grup berdasarkan per aplikasi. Nilai null mengecualikan semua grup, nilai SecurityGroup termasuk peran direktori dan keanggotaan Grup Keamanan Direktori Aktif, dan nilai All termasuk Grup Keamanan dan Daftar Distribusi Microsoft 365. 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. 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.

Catatan

rolesKlaim , , scpgroups, dan wids bukan daftar lengkap tentang bagaimana sumber daya dapat mengotorisasi pengguna atau aplikasi, juga bukan daftar lengkap izin yang diberikan kepada pemanggil. Sumber daya target dapat menggunakan metode lain untuk mengotorisasi akses ke sumber daya yang dilindungi.

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), 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 Grafik Azure AD (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