Token ID platform identitas Microsoft

Token ID adalah ekstensi inti yang dibuat OpenID Connect untuk OAuth 2.0. Token ID diterbitkan oleh server otorisasi dan berisi klaim yang berisi informasi mengenai pengguna. Token ID dapat dikirim bersamaan dengan atau menggantikan token akses. Informasi dalam Token ID memungkinkan klien untuk memverifikasi bahwa pengguna tersebut sesuai dengan yang mereka sebutkan. Token ID dimaksudkan untuk dipahami oleh aplikasi pihak ketiga. Token ID tidak boleh digunakan untuk tujuan otorisasi. Token akses digunakan untuk otorisasi. Klaim yang disediakan oleh token ID dapat digunakan untuk UX di dalam aplikasi Anda, sebagai kunci di dalam database, dan menyediakan akses ke aplikasi klien.

Prasyarat

Artikel berikut akan bermanfaat sebelum menelusuri artikel ini:

Klaim dalam token ID

Token ID adalah token web JSON (JWT). Token ID ini 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. 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 sudah ada kemungkinan menggunakan titik akhir Microsoft Azure AD (v1.0), aplikasi baru harus menggunakan titik akhir "platform identitas Microsoft" (v2.0).

  • v1.0: titik akhir Microsoft Azure AD: https://login.microsoftonline.com/common/oauth2/authorize
  • v2.0: titik akhir Platform identitas Microsoft: https://login.microsoftonline.com/common/oauth2/v2.0/authorize

Contoh token ID v1.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyIsImtpZCI6IjdfWnVmMXR2a3dMeFlhSFMzcTZsVWpVWUlHdyJ9.eyJhdWQiOiJiMTRhNzUwNS05NmU5LTQ5MjctOTFlOC0wNjAxZDBmYzljYWEiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkvIiwiaWF0IjoxNTM2Mjc1MTI0LCJuYmYiOjE1MzYyNzUxMjQsImV4cCI6MTUzNjI3OTAyNCwiYWlvIjoiQVhRQWkvOElBQUFBcXhzdUIrUjREMnJGUXFPRVRPNFlkWGJMRDlrWjh4ZlhhZGVBTTBRMk5rTlQ1aXpmZzN1d2JXU1hodVNTajZVVDVoeTJENldxQXBCNWpLQTZaZ1o5ay9TVTI3dVY5Y2V0WGZMT3RwTnR0Z2s1RGNCdGsrTExzdHovSmcrZ1lSbXY5YlVVNFhscGhUYzZDODZKbWoxRkN3PT0iLCJhbXIiOlsicnNhIl0sImVtYWlsIjoiYWJlbGlAbWljcm9zb2Z0LmNvbSIsImZhbWlseV9uYW1lIjoiTGluY29sbiIsImdpdmVuX25hbWUiOiJBYmUiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMWRiNDcvIiwiaXBhZGRyIjoiMTMxLjEwNy4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJub25jZSI6IjEyMzUyMyIsIm9pZCI6IjA1ODMzYjZiLWFhMWQtNDJkNC05ZWMwLTFiMmJiOTE5NDQzOCIsInJoIjoiSSIsInN1YiI6IjVfSjlyU3NzOC1qdnRfSWN1NnVlUk5MOHhYYjhMRjRGc2dfS29vQzJSSlEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6IkFiZUxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJMeGVfNDZHcVRrT3BHU2ZUbG40RUFBIiwidmVyIjoiMS4wIn0=.UJQrCA6qn2bXq57qzGX_-D3HcPHqBMOKDPx4su1yKRLNErVD8xkxJLNLVRdASHqEcpyDctbdHccu6DPpkq5f0ibcaQFhejQNcABidJCTz0Bb2AbdUCTqAzdt9pdgQvMBnVH1xk3SCM6d4BbT4BkLLj10ZLasX7vRknaSjE_C5DI7Fg4WrZPwOhII1dB0HEZ_qpNaYXEiy-o94UJ94zCr07GgrqMsfYQqFR7kn-mn68AjvLcgwSfZvyR_yIK75S_K37vC3QryQ7cNoafDe9upql_6pB2ybMVlgWPs_DmbJ8g0om-sPlwyn74Cc1tW3ze-Xptw_2uVdPgWyqfuWAfq6Q

Lihat token sampel v1.0 ini di jwt.ms.

Contoh token ID v2.0

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjFMVE16YWtpaGlSbGFfOHoyQkVKVlhlV01xbyJ9.eyJ2ZXIiOiIyLjAiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vOTEyMjA0MGQtNmM2Ny00YzViLWIxMTItMzZhMzA0YjY2ZGFkL3YyLjAiLCJzdWIiOiJBQUFBQUFBQUFBQUFBQUFBQUFBQUFJa3pxRlZyU2FTYUZIeTc4MmJidGFRIiwiYXVkIjoiNmNiMDQwMTgtYTNmNS00NmE3LWI5OTUtOTQwYzc4ZjVhZWYzIiwiZXhwIjoxNTM2MzYxNDExLCJpYXQiOjE1MzYyNzQ3MTEsIm5iZiI6MTUzNjI3NDcxMSwibmFtZSI6IkFiZSBMaW5jb2xuIiwicHJlZmVycmVkX3VzZXJuYW1lIjoiQWJlTGlAbWljcm9zb2Z0LmNvbSIsIm9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC02NmYzLTMzMzJlY2E3ZWE4MSIsInRpZCI6IjkxMjIwNDBkLTZjNjctNGM1Yi1iMTEyLTM2YTMwNGI2NmRhZCIsIm5vbmNlIjoiMTIzNTIzIiwiYWlvIjoiRGYyVVZYTDFpeCFsTUNXTVNPSkJjRmF0emNHZnZGR2hqS3Y4cTVnMHg3MzJkUjVNQjVCaXN2R1FPN1lXQnlqZDhpUURMcSFlR2JJRGFreXA1bW5PcmNkcUhlWVNubHRlcFFtUnA2QUlaOGpZIn0.1AFWW-Ck5nROwSlltm7GzZvDwUkqvhSQpm55TQsmVo9Y59cLhRXpvB8n-55HCr9Z6G_31_UbeUkoz612I2j_Sm9FFShSDDjoaLQr54CreGIJvjtmS3EkK9a7SJBbcpL1MpUtlfygow39tFjY7EVNW9plWUvRrTgVk7lYLprvfzw-CIqw3gHC-T7IK_m_xkr08INERBtaecwhTeN4chPC4W3jdmw_lIxzC48YoQ0dB1L9-ImX98Egypfrlbm0IBL5spFzL6JDZIRRJOu8vecJvj1mq-IUhGt0MacxX8jdxYLP-KUu2d9MbNKpCKJuZ7p8gwTL5B7NlUdh_dmSviPWrw

Lihat token sampel v2.0 ini di jwt.ms.

Semua klaim JWT yang terdaftar di bawah ini muncul pada token v1.0 dan v2.0 kecuali dinyatakan sebaliknya.

Klaim header

Tabel di bawah ini menunjukkan klaim header yang ada pada token ID.

Klaim Format Deskripsi
typ String - selalu "JWT" Menunjukkan bahwa token adalah JWT.
alg String Menunjukkan algoritma yang digunakan untuk menandatangani token. Contoh: "RS256"
kid String Menentukan thumbprint untuk kunci publik yang dapat digunakan untuk memvalidasi tanda tangan token ini. 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 di bawah ini menunjukkan klaim yang ada di sebagian besar token ID secara default (kecuali jika disebutkan). 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. Selain itu juga mengidentifikasi penyewa Microsoft Azure AD tempat pengguna diautentikasi. Jika token dikeluarkan oleh titik akhir v2.0, URI akan 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 "Issued At" (Dikeluarkan Pada) menunjukkan kapan autentikasi untuk token ini terjadi.
idp String, biasanya STS URI Merekam penyedia identitas yang mengautentikasi subjek token. Nilai ini identik dengan nilai klaim Penerbit kecuali akun pengguna tidak berada dalam penyewa yang sama dengan penerbit - tamu, misalnya. Jika klaim tidak ada, itu berarti bahwa nilai iss dapat digunakan sebagai gantinya. Untuk akun personal yang digunakan dalam konteks organisasi (misalnya, akun personal yang diundang ke penyewa Microsoft Azure AD), klaim idp mungkin 'live.com' atau STS URI yang berisi penyewa akun Microsoft 9188040d-6c67-4c5b-b112-36a304b66dad.
nbf int, tanda waktu Unix Klaim "nbf" (bukan sebelumnya) mengidentifikasi waktu sebelumnya yang di mana JWT TIDAK BOLEH diterima untuk diproses.
exp int, tanda waktu Unix Klaim "exp" (waktu kedaluwarsa) mengidentifikasi waktu kedaluwarsa yang pada atau setelahnya JWT tidak boleh diterima untuk pemrosesan. Harap diingat bahwa dalam situasi 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.
at_hash Untai (karakter) 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. Ini tidak dikembalikan pada token ID dari titik akhir /token.
aio String Buram Klaim internal yang digunakan Microsoft Azure AD 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 boleh digunakan untuk membuat keputusan otorisasi. Namun, ini dapat digunakan untuk petunjuk nama pengguna, dan dalam UI yang dapat dibaca manusia sebagai nama pengguna. Cakupan profile diperlukan untuk menerima klaim ini. Hanya ada dalam token v2.0.
email String Klaim email ini hadir secara default untuk akun tamu yang memiliki alamat email. Aplikasi Anda dapat meminta klaim email untuk pengguna terkelola (pengguna yang berasal dari penyewa yang sama dengan sumber daya) menggunakan emailklaim opsional. 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 tersebut tidak dijamin unik, dapat diubah, dan dirancang untuk digunakan hanya untuk tujuan tampilan. Cakupan profile diperlukan untuk menerima klaim ini.
nonce String Nonce cocok dengan parameter yang disertakan dalam permintaan asli /otorisasi ke IDP. Jika tidak cocok, aplikasi Anda harus menolak token.
oid String, GUID Pengidentifikasi yang tidak dapat diubah untuk objek dalam sistem identitas Microsoft, dalam hal ini, akun pengguna. ID ini secara unik mengidentifikasi perwakilan di seluruh aplikasi - dua aplikasi yang berbeda yang masuk dalam pengguna yang sama akan menerima nilai yang sama dalam klaim oid. Microsoft Graph akan mengembalikan ID ini sebagai properti id untuk akun pengguna tertentu. Karena oid memungkinkan beberapa aplikasi untuk menghubungkan pengguna, cakupan profile diperlukan untuk menerima klaim ini. Perhatikan bahwa jika satu pengguna ada di beberapa penyewa, pengguna akan berisi ID objek yang berbeda di setiap penyewa - mereka dianggap akun yang berbeda, meskipun pengguna masuk ke setiap akun dengan informasi masuk yang sama. Klaim oid tersebut 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 azure untuk memrevalidasi ulang token. Harus diabaikan.
sub String Ini adalah perwakilan yang tokennya menegaskan informasi, seperti pengguna aplikasi. Nilai ini tidak dapat diubah dan tidak dapat ditetapkan ulang atau digunakan kembali. Namun, subjeknya adalah pengidentifikasi berdasarkan pasangan - ini 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. Ini mungkin atau mungkin tidak diinginkan 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 id_token.
hasgroups Boolean Jika ada, selalu benar, yang menunjukkan pengguna berada di setidaknya satu grup. Digunakan sebagai ganti klaim grup untuk JWTs dalam alur pemberian implisit jika klaim grup lengkap akan memperluas fragmen URI di luar batas panjang URL (saat ini 6 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 panjangnya tidak dibatasi (lihat hasgroups di atas) namun masih terlalu besar untuk token tersebut, tautan ke daftar grup lengkap untuk pengguna akan 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 (Subjek dan ID Objek)

Saat mengidentifikasi pengguna (misalnya, mencarinya dalam database, atau memutuskan izin apa yang mereka miliki), sangat penting untuk menggunakan informasi yang akan tetap konstan dan unik sepanjang waktu. Aplikasi lama terkadang menggunakan bidang seperti alamat email, nomor telepon, atau UPN. Semua ini dapat berubah seiring waktu, dan juga dapat digunakan kembali seiring waktu. Contohnya, saat seorang karyawan mengubah nama mereka, atau seorang karyawan diberikan alamat email yang cocok dengan karyawan sebelumnya yang sudah tidak bekerja. Dengan demikian, sangat penting bahwa aplikasi Anda tidak menggunakan data yang dapat dibaca oleh manusia untuk mengidentifikasi pengguna - dapat dibaca oleh manusia umumnya berarti seseorang akan 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 antar layanan, oid+tid adalah yang terbaik karena semua aplikasi mendapatkan klaim oid dan tid yang sama untuk pengguna tertentu yang bertindak dalam penyewa yang ditentukan. Klaim sub dalam platform identitas Microsoft "pasangan-bijaksana" - itu unik berdasarkan kombinasi penerima token, penyewa, dan pengguna. Oleh karena itu, dua aplikasi yang meminta token ID untuk pengguna tertentu akan menerima klaim sub yang berbeda, namun menerima klaim oid yang sama untuk pengguna tersebut.

Catatan

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

Skenario tamu, di mana pengguna berada di rumah dalam satu penyewa, dan mengautentikasi di penyewa lain, harus memperlakukan pengguna seolah-olah mereka adalah pengguna baru untuk layanan. Dokumen dan hak istimewa Anda di penyewa Contoso tidak boleh berlaku di penyewa Fabrikam. Anda perlu 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, Microsoft Azure AD membatasi jumlah ID objek yang disertakan dalam klaim groups. Jika pengguna adalah anggota dari lebih banyak grup dibandingkan batas ekses (150 untuk token SAML, 200 untuk token JWT), maka Microsoft Azure AD tidak mengeluarkan klaim grup 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]"
        }
       }
     }
  ...
}

Masa pakai token ID

Secara default, token ID valid selama satu jam - setelah satu jam, klien tersebut harus mendapatkan token ID baru.

Anda dapat menyesuaikan masa hidup token ID untuk mengontrol seberapa sering aplikasi klien mengakhiri sesi aplikasi, dan seberapa sering token ID mengharuskan pengguna untuk mengautentikasi ulang, baik secara diam-diam maupun secara interaktif. Untuk informasi selengkapnya, baca Masa pakai token yang dapat dikonfigurasi.

Memvalidasi token ID

Memvalidasi token ID mirip dengan langkah pertama memvalidasi token akses. Klien Anda dapat memeriksa apakah token telah dirusak. Klien Anda juga dapat memvalidasi penerbit untuk memastikan bahwa penerbit yang benar telah mengirimkan kembali token tersebut. Karena token ID selalu merupakan token JWT, terdapat banyak pustaka untuk memvalidasi token ini - kami sarankan untuk menggunakan salah satu pustaka ini dan tidak melakukannya sendiri. Perhatikan bahwa hanya klien rahasia (yang memiliki rahasia) yang harus memvalidasi token ID. Aplikasi publik (kode sepenuhnya dijalankan pada perangkat atau jaringan yang tidak Anda kendalikan seperti browser pengguna atau jaringan rumah mereka) tidak mendapat keuntungan dari validasi token ID. Hal ini karena pengguna yang berbahaya dapat mencegat dan mengedit kunci yang digunakan untuk validasi token.

Untuk memvalidasi token secara manual, lihat detail langkah-langkah dalam memvalidasi token akses. Klaim JWT berikut ini harus divalidasi pada token ID Setelah memvalidasi tanda tangan pada token tersebut. Klaim ini juga dapat divalidasi oleh pustaka validasi token Anda:

  • Stempel waktu: stempel waktu iat, nbf, dan exp semua harus jatuh sebelum atau sesudah waktu saat ini, sebagaimana mestinya.
  • Audiens: klaim aud harus sesuai dengan ID aplikasi untuk aplikasi Anda.
  • Nonce: klaim nonce dalam muatan harus sesuai dengan parameter nonce yang diteruskan ke /authorize endpoint selama permintaan awal.

Langkah berikutnya