Bagikan melalui

Referensi klaim token ID

  • Artikel

Token ID adalah token web JSON (JWT). Token ID v1.0 dan v2.0 memiliki perbedaan pada informasi yang dibawa. Versi ini didasarkan pada titik akhir dari mana ia diminta. Meskipun aplikasi yang ada kemungkinan menggunakan titik akhir Azure AD v1.0, aplikasi baru harus menggunakan titik akhir v2.0.

  • v1.0: https://login.microsoftonline.com/common/oauth2/authorize
  • v2.0: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Semua klaim JWT yang tercantum di bagian berikut muncul di token v1.0 dan v2.0 kecuali dinyatakan sebaliknya. Token ID terdiri dari header, payload, dan tanda tangan. Header dan tanda tangan digunakan untuk memverifikasi keaslian token, sementara payload berisi informasi tentang pengguna yang diminta oleh klien Anda.

Klaim header

Tabel berikut ini memperlihatkan klaim header yang ada dalam token ID.

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 dapat digunakan untuk memvalidasi tanda tangan token. Dikeluarkan dalam token akses v1.0 dan v2.0 ID.
x5t String Fungsi yang sama (dalam penggunaan dan nilai) sebagai kid. x5t adalah klaim warisan yang hanya dikeluarkan dalam token akses v1.0 ID untuk tujuan kompatibilitas.

Klaim payload

Tabel berikut menunjukkan klaim yang berada di sebagian besar token ID secara default (kecuali jika dicatat). Namun, aplikasi Anda dapat menggunakan klaim opsional untuk meminta klaim tambahan pada token ID. Klaim tambahan dapat berkisar antara klaim groups hingga informasi mengenai nama pengguna.

Klaim Format Deskripsi
aud String, GUID ID Aplikasi Mengidentifikasi penerima token yang dimaksud. Dalam id_tokens, audiens adalah ID Aplikasi dari aplikasi Anda, yang ditetapkan untuk aplikasi Anda di portal Microsoft Azure. Nilai ini harus divalidasi. Token harus ditolak jika gagal untuk mencocokkan dengan ID Aplikasi dari aplikasi Anda.
iss String, URI penerbit Mengidentifikasi penerbit, atau "server otorisasi" yang membangun dan mengembalikan token. Ini juga mengidentifikasi penyewa tempat pengguna diautentikasi. Jika token dikeluarkan oleh titik akhir v2.0, URI berakhir di /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.
iat int, tanda waktu Unix Menunjukkan kapan autentikasi untuk token terjadi.
idp String, biasanya STS URI Merekam penyedia identitas yang mengautentikasi subjek token. Nilai ini identik dengan nilai klaim pengeluar sertifikat kecuali akun pengguna tidak berada di penyewa yang sama dengan penerbit - tamu, misalnya. Jika klaim tidak ada, itu berarti bahwa nilai iss dapat digunakan sebagai gantinya. Untuk akun pribadi yang digunakan dalam konteks organisasi (misalnya, akun pribadi yang diundang ke penyewa), idp klaimnya mungkin 'live.com' atau URI STS yang berisi penyewa 9188040d-6c67-4c5b-b112-36a304b66dadakun Microsoft .
nbf int, tanda waktu Unix Mengidentifikasi waktu sebelum JWT tidak dapat diterima untuk diproses.
exp int, tanda waktu Unix Mengidentifikasi waktu kedaluwarsa pada atau setelah itu JWT tidak dapat diterima untuk diproses. Dalam keadaan tertentu, sumber daya dapat menolak token sebelum waktu ini. Contohnya, jika perubahan pada autentikasi diperlukan atau pencabutan token telah terdeteksi.
c_hash String Hash kode yang disertakan dalam token ID hanya ketika token dikeluarkan bersama dengan kode otorisasi OAuth 2.0. Hash kode dapat digunakan untuk memvalidasi keaslian kode otorisasi. Untuk memahami cara melakukan validasi ini, lihat Spesifikasi OpenID Connect. Klaim ini tidak dikembalikan pada token ID dari titik akhir /token.
at_hash String Hash token akses termasuk dalam token ID hanya ketika token ID dikeluarkan dari /authorize titik akhir dengan token akses OAuth 2.0. Hash token akses dapat digunakan untuk memvalidasi keaslian token akses. Untuk memahami cara melakukan validasi ini, lihat Spesifikasi OpenID Connect. Klaim ini tidak dikembalikan pada token ID dari /token titik akhir.
aio String Buram Klaim internal yang digunakan untuk merekam data untuk penggunaan kembali token. Harus diabaikan.
preferred_username String Nama pengguna utama yang merepresentasikan pengguna. Ini bisa berupa alamat email, nomor telepon, atau nama pengguna generik tanpa format yang ditentukan. Nilainya dapat diubah dan mungkin berubah seiring waktu. Karena dapat diubah, nilai ini tidak dapat digunakan untuk membuat keputusan otorisasi. Ini dapat digunakan untuk petunjuk nama pengguna dan di UI yang dapat dibaca manusia sebagai nama pengguna. Cakupan profile diperlukan untuk menerima klaim ini. Hanya ada dalam token v2.0.
email String Sajikan secara default untuk akun tamu yang memiliki alamat email. Aplikasi Anda dapat meminta klaim email untuk pengguna terkelola (dari penyewa yang sama dengan sumber daya) menggunakan email klaim opsional. Nilai ini tidak dijamin benar dan dapat diubah dari waktu ke waktu. Jangan pernah menggunakannya untuk otorisasi atau menyimpan data untuk pengguna. Jika Anda memerlukan alamat email yang dapat diatasi di aplikasi Anda, minta data ini dari pengguna secara langsung dengan menggunakan klaim ini sebagai saran atau awalan di UX Anda. Pada titik akhir v2.0, aplikasi Anda juga dapat meminta email cakupan OpenID Connect - Anda tidak perlu meminta klaim opsional dan cakupan untuk mendapatkan klaim.
name String Klaim name Memberi nilai yang dapat dibaca manusia yang mengidentifikasi subjek token. Nilai tidak dijamin unik, dapat diubah, dan harus digunakan hanya untuk tujuan tampilan. Cakupan profile diperlukan untuk menerima klaim ini.
nonce String Nonce cocok dengan parameter yang disertakan dalam permintaan otorisasi asli ke IDP. Jika tidak cocok, aplikasi Anda harus menolak token.
oid String, GUID Pengidentifikasi yang tidak dapat diubah untuk objek, dalam hal ini, akun pengguna. ID ini secara unik mengidentifikasi pengguna di seluruh aplikasi - dua aplikasi berbeda yang masuk ke pengguna yang sama menerima nilai yang sama dalam oid klaim. Microsoft Graph mengembalikan ID ini sebagai id properti untuk akun pengguna. Karena oid memungkinkan beberapa aplikasi untuk menghubungkan pengguna, cakupan profile diperlukan untuk menerima klaim ini. Jika satu pengguna ada di beberapa penyewa, pengguna berisi ID objek yang berbeda di setiap penyewa - mereka dianggap akun yang berbeda, meskipun pengguna masuk ke setiap akun dengan kredensial yang sama. Klaim oid adalah GUID dan tidak dapat digunakan kembali.
roles Array string Kumpulan peran yang ditetapkan untuk pengguna yang masuk.
rh String Buram Klaim internal yang digunakan untuk memvalidasi ulang token. Harus diabaikan.
sub String Subjek informasi dalam token. Misalnya, pengguna aplikasi. Nilai ini tidak berubah dan tidak dapat ditetapkan atau digunakan kembali. Subjek adalah pengidentifikasi berpasangan dan unik untuk ID aplikasi. Jika satu pengguna masuk ke dua aplikasi berbeda menggunakan dua ID klien yang berbeda, aplikasi tersebut menerima dua nilai berbeda untuk klaim subjek. Anda mungkin atau mungkin tidak menginginkan dua nilai tergantung pada arsitektur dan persyaratan privasi Anda.
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.
unique_name String Hanya ada dalam token v1.0. Memberi nilai yang dapat dibaca manusia yang mengidentifikasi subjek token. Nilai ini tidak dijamin unik dalam penyewa dan harus digunakan hanya untuk tujuan tampilan.
uti String Klaim pengidentifikasi token, setara dengan jti dalam spesifikasi JWT. Pengidentifikasi unik per-token yang peka huruf besar/kecil.
ver String, baik 1.0 atau 2.0 Menunjukkan versi token ID.
hasgroups Boolean Jika ada, selalu benar, yang menunjukkan pengguna berada di setidaknya satu grup. Digunakan sebagai pengganti klaim grup untuk JWT dalam alur pemberian implisit ketika klaim grup lengkap memperluas fragmen URI di luar batas panjang URL (saat ini enam grup atau lebih). Menunjukkan bahwa klien harus menggunakan Microsoft Graph API untuk menentukan grup pengguna (https://graph.microsoft.com/v1.0/users/{userID}/getMemberObjects).
groups:src1 Objek JSON Untuk permintaan token yang tidak dibatasi panjangnya (lihat hasgroups) tetapi masih terlalu besar untuk token, tautan ke daftar grup lengkap untuk pengguna disertakan. 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" }

Untuk informasi selengkapnya, lihat Klaim kelebihan grup.

Menggunakan klaim untuk mengidentifikasi pengguna dengan andal

Saat mengidentifikasi pengguna, sangat penting untuk menggunakan informasi yang tetap konstan dan unik sepanjang waktu. Aplikasi warisan terkadang menggunakan bidang seperti alamat email, nomor telepon, atau UPN. Semua bidang ini dapat berubah dari waktu ke waktu, dan juga dapat digunakan kembali dari waktu ke waktu. Contohnya, saat seorang karyawan mengubah nama mereka, atau seorang karyawan diberikan alamat email yang cocok dengan karyawan sebelumnya yang sudah tidak bekerja. Aplikasi Anda tidak boleh menggunakan data yang dapat dibaca manusia untuk mengidentifikasi pengguna - dapat dibaca manusia umumnya berarti seseorang dapat membacanya, dan ingin mengubahnya. Sebagai gantinya, gunakan klaim yang diberikan oleh standar OIDC, atau klaim ekstensi yang diberikan oleh Microsoft - klaim sub dan klaim oid.

Untuk menyimpan informasi per pengguna dengan benar, gunakan sub atau oid saja (sebagai GUID yang unik), dengan tid digunakan untuk perutean atau sharding jika diperlukan. Jika Anda perlu berbagi data di seluruh layanan, oid dan tid terbaik karena semua aplikasi mendapatkan hal yang sama oid dan tid klaim untuk pengguna yang bertindak dalam penyewa. Klaim sub adalah nilai sepasang bijaksana yang unik. Nilai didasarkan pada kombinasi penerima token, penyewa, dan pengguna. Dua aplikasi yang meminta token ID untuk pengguna menerima klaim yang berbeda sub , tetapi klaim yang sama oid untuk pengguna tersebut.

Catatan

Jangan gunakan idp klaim untuk menyimpan informasi tentang pengguna dalam upaya menghubungkan pengguna di seluruh penyewa. Ini tidak berfungsi, karena oid klaim dan sub untuk perubahan pengguna di seluruh penyewa, berdasarkan desain, untuk memastikan bahwa aplikasi tidak dapat melacak pengguna di seluruh penyewa.

Skenario tamu, di mana pengguna berada di satu penyewa, dan mengautentikasi di penyewa lain, harus memperlakukan pengguna seolah-olah mereka adalah pengguna baru untuk layanan. Dokumen dan hak istimewa Anda dalam satu penyewa tidak boleh berlaku di penyewa lain. Pembatasan ini penting untuk mencegah kebocoran data yang tidak disengaja di seluruh penyewa, dan penerapan siklus hidup data. Mengeluarkan tamu dari penyewa juga akan menghapus akses mereka ke data yang mereka buat di penyewa tersebut.

Klaim ekses grup

Untuk memastikan bahwa ukuran token tidak melebihi batas ukuran header HTTP, jumlah ID objek yang disertakannya dalam groups klaim terbatas. Jika pengguna adalah anggota lebih banyak grup daripada batas kelebihan (150 untuk token SAML, 200 untuk token JWT), klaim grup tidak disertakan dalam token. Sebaliknya, ini termasuk klaim ekses 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]"
        }
       }
     }
  ...
}

Langkah berikutnya