Token akses dalam Platform identitas Microsoft

Artikel
04/10/2024

Token akses memungkinkan klien memanggil API web yang dilindungi dengan aman. API Web menggunakan token akses untuk melakukan autentikasi dan otorisasi.

Sesuai spesifikasi OAuth, token akses adalah string buram tanpa format yang ditetapkan. Beberapa penyedia identitas (IDP) menggunakan GUID, dan yang lain menggunakan blob terenkripsi. Format token akses dapat bergantung pada konfigurasi API yang menerimanya.

API kustom yang didaftarkan oleh pengembang pada platform identitas Microsoft dapat memilih dari dua format berbeda dari JSON Web Token (JWT) yang disebut v1.0 dan v2.0. API yang dikembangkan Microsoft seperti Microsoft Graph atau API di Azure memiliki format token kepemilikan lainnya. Format kepemilikan ini yang tidak dapat divalidasi mungkin merupakan token terenkripsi, JWT, atau JWT khusus seperti.

Konten token hanya ditujukan untuk API, yang berarti bahwa token akses harus diperlakukan sebagai string buram. Hanya untuk tujuan validasi dan debugging, pengembang dapat mendekode JWT menggunakan situs seperti jwt.ms. Token yang diterima Microsoft API mungkin tidak selalu menjadi JWT yang dapat didekodekan.

Klien harus menggunakan data respons token yang dikembalikan dengan token akses untuk detail tentang apa yang ada di dalamnya. Saat klien Anda meminta token akses, platform identitas Microsoft juga mengembalikan beberapa metadata tentang token akses untuk konsumsi aplikasi Anda. Informasi ini mencakup waktu kedaluwarsa token akses dan cakupan yang valid. Data ini memungkinkan aplikasi Anda untuk membuat chache cerdas terhadap token akses tanpa harus mengurai token akses itu sendiri.

Lihat bagian berikut untuk mempelajari bagaimana API Anda dapat memvalidasi dan menggunakan klaim di dalam token akses.

Catatan

Semua dokumentasi di halaman ini, kecuali jika disebutkan, hanya berlaku untuk token yang diterbitkan untuk API terdaftar. Hal ini tidak berlaku untuk token yang dikeluarkan untuk API milik Microsoft, juga tidak dapat digunakan untuk memvalidasi bagaimana platform identitas Microsoft mengeluarkan token untuk API terdaftar.

Format token

Ada dua versi token akses yang tersedia di platform identitas Microsoft: v1.0 dan v2.0. Versi ini menentukan klaim yang ada dalam token dan memastikan bahwa API web dapat mengontrol konten token.

Web API memiliki salah satu versi berikut yang dipilih sebagai default selama pendaftaran:

v1.0 untuk aplikasi khusus Microsoft Entra. Contoh berikut menunjukkan token v1.0 (kunci diubah dan informasi pribadi dihapus, yang mencegah validasi token):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiJlZjFkYTlkNC1mZjc3LTRjM2UtYTAwNS04NDBjM2Y4MzA3NDUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC9mYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTUyMjIyOS8iLCJpYXQiOjE1MzcyMzMxMDYsIm5iZiI6MTUzNzIzMzEwNiwiZXhwIjoxNTM3MjM3MDA2LCJhY3IiOiIxIiwiYWlvIjoiQVhRQWkvOElBQUFBRm0rRS9RVEcrZ0ZuVnhMaldkdzhLKzYxQUdyU091TU1GNmViYU1qN1hPM0libUQzZkdtck95RCtOdlp5R24yVmFUL2tES1h3NE1JaHJnR1ZxNkJuOHdMWG9UMUxrSVorRnpRVmtKUFBMUU9WNEtjWHFTbENWUERTL0RpQ0RnRTIyMlRJbU12V05hRU1hVU9Uc0lHdlRRPT0iLCJhbXIiOlsid2lhIl0sImFwcGlkIjoiNzVkYmU3N2YtMTBhMy00ZTU5LTg1ZmQtOGMxMjc1NDRmMTdjIiwiYXBwaWRhY3IiOiIwIiwiZW1haWwiOiJBYmVMaUBtaWNyb3NvZnQuY29tIiwiZmFtaWx5X25hbWUiOiJMaW5jb2xuIiwiZ2l2ZW5fbmFtZSI6IkFiZSAoTVNGVCkiLCJpZHAiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83MmY5ODhiZi04NmYxLTQxYWYtOTFhYi0yZDdjZDAxMjIyNDcvIiwiaXBhZGRyIjoiMjIyLjIyMi4yMjIuMjIiLCJuYW1lIjoiYWJlbGkiLCJvaWQiOiIwMjIyM2I2Yi1hYTFkLTQyZDQtOWVjMC0xYjJiYjkxOTQ0MzgiLCJyaCI6IkkiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJzdWIiOiJsM19yb0lTUVUyMjJiVUxTOXlpMmswWHBxcE9pTXo1SDNaQUNvMUdlWEEiLCJ0aWQiOiJmYTE1ZDY5Mi1lOWM3LTQ0NjAtYTc0My0yOWYyOTU2ZmQ0MjkiLCJ1bmlxdWVfbmFtZSI6ImFiZWxpQG1pY3Jvc29mdC5jb20iLCJ1dGkiOiJGVnNHeFlYSTMwLVR1aWt1dVVvRkFBIiwidmVyIjoiMS4wIn0.D3H6pMUtQnoJAGq6AHd

v2.0 untuk aplikasi yang mendukung akun konsumen. Contoh berikut menunjukkan token v2.0 (kunci diubah dan informasi pribadi dihapus, yang mencegah validasi token):

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk2bEdrM0ZaenhSY1ViMkMzbkVRN3N5SEpsWSJ9.eyJhdWQiOiI2ZTc0MTcyYi1iZTU2LTQ4NDMtOWZmNC1lNjZhMzliYjEyZTMiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3L3YyLjAiLCJpYXQiOjE1MzcyMzEwNDgsIm5iZiI6MTUzNzIzMTA0OCwiZXhwIjoxNTM3MjM0OTQ4LCJhaW8iOiJBWFFBaS84SUFBQUF0QWFaTG8zQ2hNaWY2S09udHRSQjdlQnE0L0RjY1F6amNKR3hQWXkvQzNqRGFOR3hYZDZ3TklJVkdSZ2hOUm53SjFsT2NBbk5aY2p2a295ckZ4Q3R0djMzMTQwUmlvT0ZKNGJDQ0dWdW9DYWcxdU9UVDIyMjIyZ0h3TFBZUS91Zjc5UVgrMEtJaWpkcm1wNjlSY3R6bVE9PSIsImF6cCI6IjZlNzQxNzJiLWJlNTYtNDg0My05ZmY0LWU2NmEzOWJiMTJlMyIsImF6cGFjciI6IjAiLCJuYW1lIjoiQWJlIExpbmNvbG4iLCJvaWQiOiI2OTAyMjJiZS1mZjFhLTRkNTYtYWJkMS03ZTRmN2QzOGU0NzQiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJhYmVsaUBtaWNyb3NvZnQuY29tIiwicmgiOiJJIiwic2NwIjoiYWNjZXNzX2FzX3VzZXIiLCJzdWIiOiJIS1pwZmFIeVdhZGVPb3VZbGl0anJJLUtmZlRtMjIyWDVyclYzeERxZktRIiwidGlkIjoiNzJmOTg4YmYtODZmMS00MWFmLTkxYWItMmQ3Y2QwMTFkYjQ3IiwidXRpIjoiZnFpQnFYTFBqMGVRYTgyUy1JWUZBQSIsInZlciI6IjIuMCJ9.pj4N-w_3Us9DrBLfpCt

Atur versi untuk aplikasi dengan memberikan nilai yang sesuai ke accessTokenAcceptedVersion pengaturan dalam manifes aplikasi. Nilai null dan 1 menghasilkan token v1.0, dan nilai 2 menghasilkan token v2.0.

Kepemilikan token

Permintaan token akses melibatkan dua pihak: klien, yang meminta token, dan sumber daya (Web API) yang menerima token. Sumber daya yang dimaksudkan untuk token (audiensnya) didefinisikan dalam aud klaim dalam token. Klien menggunakan token tetapi tidak boleh memahami atau mencoba mengurainya. Sumber daya menerima token.

platform identitas Microsoft mendukung penerbitan versi token apa pun dari titik akhir versi apa pun. Misalnya, ketika nilai accessTokenAcceptedVersion adalah 2, klien yang memanggil titik akhir v1.0 untuk mendapatkan token untuk sumber daya tersebut menerima token akses v2.0.

Sumber daya selalu memiliki tokennya menggunakan klaim aud dan merupakan satu-satunya aplikasi yang dapat mengubah detail tokennya.

Masa pakai token

Masa pakai default token akses adalah variabel. Ketika dikeluarkan, platform identitas Microsoft menetapkan nilai acak berkisar antara 60-90 menit (rata-rata 75 menit) sebagai masa pakai default token akses. Variasi meningkatkan ketahanan layanan dengan menyebarkan permintaan token akses selama satu waktu, yang mencegah lonjakan lalu lintas per jam ke ID Microsoft Entra.

Penyewa yang tidak menggunakan Akses Bersyariah memiliki masa pakai token akses default selama dua jam untuk klien seperti Microsoft Teams dan Microsoft 365.

Sesuaikan masa pakai token akses untuk mengontrol seberapa sering aplikasi klien kedaluwarsa sesi aplikasi, dan seberapa sering mengharuskan pengguna untuk mengautentikasi ulang (baik secara diam-diam atau interaktif). Untuk mengambil alih variasi masa pakai token akses default, gunakan Configurable token lifetime (CTL).

Terapkan variasi masa pakai token default ke organisasi yang mengaktifkan Evaluasi Akses Berkelanjutan (CAE). Terapkan variasi masa pakai token default meskipun organisasi menggunakan kebijakan CTL. Masa pakai token default untuk masa pakai token yang berumur panjang berkisar antara 20 hingga 28 jam. Saat token akses kedaluwarsa, klien harus menggunakan token refresh untuk mendapatkan token refresh dan token akses baru secara diam-diam.

Organisasi yang menggunakan Frekuensi masuk Akses Bersyarat (SIF) untuk menerapkan seberapa sering proses masuk tidak dapat menggantikan variasi masa pakai token akses default. Saat organisasi menggunakan SIF, waktu antara permintaan kredensial untuk klien adalah masa pakai token sekitar 60 - 90 menit ditambah interval frekuensi masuk.

Berikut adalah contoh cara kerja variasi masa pakai token default dengan frekuensi masuk. Misalnya, sebuah organisasi mangatur frekuensi masuk agar terjadi setiap jam. Ketika token memiliki masa pakai mulai dari 60-90 menit karena variasi masa pakai token, interval masuk aktual terjadi di mana saja antara 1 jam hingga 2,5 jam.

Jika pengguna dengan token dengan masa pakai satu jam melakukan masuk interaktif pada 59 menit, tidak ada permintaan kredensial karena rincian masuk berada di bawah ambang batas SIF. Jika token baru memiliki masa pakai 90 menit, pengguna tidak akan melihat permintaan kredensial selama satu setengah jam. Selama upaya perpanjangan senyap, ID Microsoft Entra memerlukan permintaan kredensial karena total panjang sesi telah melebihi pengaturan frekuensi masuk 1 jam. Dalam contoh ini, perbedaan waktu antara permintaan informasi masuk karena interval SIF dan variasi masa pakai token adalah 2,5 jam.

Memvalidasi token

Tidak semua aplikasi harus memvalidasi token. Aplikasi harus memvalidasi token dalam skenario tertentu saja:

API Web harus memvalidasi token akses yang dikirim kepada mereka oleh klien. Mereka hanya boleh menerima token yang berisi salah satu URI AppId mereka sebagai aud klaim.
Aplikasi web harus memvalidasi token ID yang dikirimkan kepada mereka dengan menggunakan browser pengguna dalam alur hibrid, sebelum mengizinkan akses ke data pengguna atau membuat sesi.

Jika tidak ada skenario yang dijelaskan sebelumnya yang berlaku, tidak perlu memvalidasi token. Klien publik seperti aplikasi asli, desktop, atau satu halaman tidak mendapat manfaat dari memvalidasi token ID karena aplikasi berkomunikasi langsung dengan IDP di mana perlindungan SSL memastikan token ID valid. Mereka tidak boleh memvalidasi token akses, karena agar API web memvalidasi, bukan klien.

API dan aplikasi web hanya boleh memvalidasi token yang memiliki klaim aud yang cocok dengan aplikasi. Sumber daya lain mungkin memiliki aturan validasi token kustom. Misalnya, Anda tidak dapat memvalidasi token untuk Microsoft Graph sesuai dengan aturan ini karena format kepemilikannya. Memvalidasi dan menerima token yang dimaksudkan untuk sumber daya lain adalah contoh dari masalah confused deputi.

Jika aplikasi perlu memvalidasi token ID atau token akses, aplikasi harus terlebih dahulu memvalidasi tanda tangan token dan penerbit terhadap nilai dalam dokumen penemuan OpenID.

Middleware Microsoft Entra memiliki kemampuan bawaan untuk memvalidasi token akses, lihat sampel untuk menemukannya dalam bahasa yang sesuai. Ada juga beberapa pustaka sumber terbuka pihak ketiga yang tersedia untuk validasi JWT. Untuk informasi selengkapnya tentang pustaka autentikasi dan sampel kode, lihat pustaka autentikasi. Jika aplikasi web atau API web Anda berada di ASP.NET atau ASP.NET Core, gunakan Microsoft.Identity.Web, yang menangani validasi untuk Anda.

Token v1.0 dan v2.0

Saat aplikasi/API web Anda memvalidasi token v1.0 (ver klaim ="1.0"), aplikasi web Anda perlu membaca dokumen metadata OpenID Koneksi dari titik akhir v1.0 (https://login.microsoftonline.com/{example-tenant-id}/.well-known/openid-configuration), bahkan jika otoritas yang dikonfigurasi untuk API web Anda adalah otoritas v2.0.
Saat aplikasi/API web Anda memvalidasi token v2.0 (ver claim ="2.0"), aplikasi web Anda perlu membaca dokumen metadata OpenID Koneksi dari titik akhir v2.0 (https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration), bahkan jika otoritas yang dikonfigurasi untuk API web Anda adalah otoritas v1.0.

Contoh berikut menandakan bahwa aplikasi Anda memvalidasi token akses v2.0 (dan karenanya mereferensikan versi v2.0 dari dokumen dan kunci metadata OIDC). Cukup hapus "/v2.0" di URL jika Anda memvalidasi token v1.0.

Memvalidasi penerbit

OpenID Koneksi Core mengatakan "Pengenal Pengeluar Sertifikat [...] HARUS sama persis dengan nilai Klaim iss (penerbit). Untuk aplikasi yang menggunakan titik akhir metadata khusus penyewa (seperti https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0/.well-known/openid-configuration atau https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration), ini saja yang diperlukan.

MICROSOFT Entra ID memiliki versi dokumen independen penyewa yang tersedia di https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Titik akhir ini mengembalikan nilai https://login.microsoftonline.com/{tenantid}/v2.0pengeluar sertifikat . Aplikasi dapat menggunakan titik akhir independen penyewa ini untuk memvalidasi token dari setiap penyewa dengan modifikasi berikut:

Alih-alih mengharapkan klaim pengeluar sertifikat dalam token sama persis dengan nilai penerbit dari metadata, aplikasi harus mengganti {tenantid} nilai dalam metadata penerbit dengan tenantid yang merupakan target permintaan saat ini, lalu memeriksa kecocokan yang tepat.

Aplikasi harus menggunakan properti yang issuer dikembalikan dari titik akhir kunci untuk membatasi cakupan kunci.

Kunci yang memiliki nilai pengeluar sertifikat seperti https://login.microsoftonline.com/{tenantid}/v2.0 dapat digunakan dengan penerbit token yang cocok.
Kunci yang memiliki nilai pengeluar sertifikat seperti https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 hanya boleh digunakan dengan kecocokan yang tepat.

Titik akhir kunci independen penyewa Microsoft Entra (https://login.microsoftonline.com/common/discovery/v2.0/keys) mengembalikan dokumen seperti:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Aplikasi yang menggunakan klaim Microsoft Entra tenantid (tid) sebagai batas kepercayaan alih-alih klaim penerbit standar harus memastikan bahwa klaim id penyewa adalah panduan dan bahwa penerbit dan penyewa cocok.

Menggunakan metadata independen penyewa lebih efisien untuk aplikasi yang menerima token dari banyak penyewa.

Catatan

Dengan metadata independen penyewa Microsoft Entra, klaim harus ditafsirkan dalam penyewa, sama seperti di bawah Koneksi OpenID standar, klaim ditafsirkan dalam penerbit. Artinya, {"sub":"ABC123","iss":"https://login.microsoftonline.com/aaaabbbb-0000-cccc-1111-dddd2222eeee/v2.0","tid":"aaaabbbb-0000-cccc-1111-dddd2222eeee"} dan {"sub":"ABC123","iss":"https://login.microsoftonline.com/bbbbcccc-1111-dddd-2222-eeee3333ffff/v2.0","tid":"bbbbcccc-1111-dddd-2222-eeee3333ffff"} menjelaskan pengguna yang berbeda, meskipun sub sama, karena klaim seperti sub ditafsirkan dalam konteks penerbit/penyewa.

Memvalidasi tanda tangan

JWT berisi tiga segmen yang dipisahkan . oleh karakter. Segmen pertama adalah header, yang kedua adalah isi, dan yang ketiga adalah tanda tangan. Gunakan segmen tanda tangan untuk mengevaluasi keaslian token.

MICROSOFT Entra ID mengeluarkan token yang ditandatangani menggunakan algoritma enkripsi asimetris standar industri, seperti RS256. Header JWT berisi informasi tentang kunci dan metode enkripsi yang digunakan untuk menandatangani token:

{
  "typ": "JWT",
  "alg": "RS256",
  "x5t": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk",
  "kid": "iBjL1Rcqzhiy4fpxIxdZqohM2Yk"
}

alg Klaim menunjukkan algoritma yang digunakan untuk menandatangani token, sementara kid klaim menunjukkan kunci publik tertentu yang digunakan untuk memvalidasi token.

Pada titik waktu tertentu, ID Microsoft Entra dapat menandatangani token ID menggunakan salah satu dari sekumpulan pasangan kunci publik-privat tertentu. MICROSOFT Entra ID memutar kumpulan kunci yang mungkin secara berkala, jadi tulis aplikasi untuk menangani perubahan kunci tersebut secara otomatis. Frekuensi yang wajar untuk memeriksa pembaruan kunci publik yang digunakan oleh ID Microsoft Entra adalah setiap 24 jam.

Anda dapat memperoleh data kunci penandatanganan yang diperlukan untuk memvalidasi tanda tangan menggunakan dokumen metadata OpenID Connect yang terletak di:

https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration

Tip

Coba ini di browser: URL

Informasi berikut menjelaskan dokumen metadata:

Adalah objek JSON yang berisi beberapa informasi berguna, seperti lokasi berbagai titik akhir yang diperlukan untuk melakukan autentikasi OpenID Connect.
Menyertakan jwks_uri, yang memberi lokasi set kunci umum sesuai dengan kunci privat yang digunakan kunci privat untuk menandatangani token. JSON Web Key (JWK) yang terletak di jwks_uri berisi semua informasi kunci umum yang digunakan pada saat tertentu pada waktunya. RFC 7517 menjelaskan format JWK. Aplikasi dapat menggunakan klaim kid di header JWT untuk memilih kunci publik dari dokumen ini, yang sesuai dengan kunci privat yang telah digunakan untuk menandatangani token tertentu. Kemudian dapat melakukan validasi tanda tangan menggunakan kunci umum yang benar dan algoritma yang ditunjukkan.

Catatan

Gunakan klaim kid untuk memvalidasi token. Meskipun token v1.0 berisi kedua klaim x5t dan kid, token v2.0 hanya berisi klaim kid.

Melakukan validasi tanda tangan berada di luar cakupan dokumen ini. Ada banyak pustaka sumber terbuka yang tersedia untuk membantu validasi tanda tangan jika perlu. Namun, platform identitas Microsoft memiliki satu ekstensi penandatanganan token ke standar, yang merupakan kunci penandatanganan kustom.

Jika aplikasi memiliki kunci penandatanganan kustom sebagai hasil dari penggunaan fitur pemetaan klaim, tambahkan appid parameter kueri yang berisi ID aplikasi. Untuk validasi, gunakan jwks_uri yang menunjuk ke informasi kunci penandatanganan aplikasi. Misalnya: https://login.microsoftonline.com/{tenant}/.well-known/openid-configuration?appid=00001111-aaaa-2222-bbbb-3333cccc4444 berisi jwks_uri dari https://login.microsoftonline.com/{tenant}/discovery/keys?appid=00001111-aaaa-2222-bbbb-3333cccc4444.

Memvalidasi penerbit

Aplikasi web yang memvalidasi token ID, dan API web yang memvalidasi token akses perlu memvalidasi penerbit token (iss klaim) terhadap:

penerbit yang tersedia dalam dokumen metadata openID connect yang terkait dengan konfigurasi aplikasi (otoritas). Dokumen metadata yang akan diverifikasi bergantung pada:
- versi token
- akun yang didukung oleh aplikasi Anda.
ID penyewa (tid klaim) token,
penerbit kunci penandatanganan.

Aplikasi penyewa tunggal

OpenID Koneksi Core mengatakan "Pengenal Pengeluar Sertifikat [...] HARUS sama persis dengan nilai iss Klaim (penerbit). Untuk aplikasi yang menggunakan titik akhir metadata khusus penyewa, seperti https://login.microsoftonline.com/{example-tenant-id}/v2.0/.well-known/openid-configuration atau https://login.microsoftonline.com/contoso.onmicrosoft.com/v2.0/.well-known/openid-configuration.

Aplikasi penyewa tunggal adalah aplikasi yang mendukung:

Akun dalam satu direktori organisasi (hanya contoh-penyewa-id ): https://login.microsoftonline.com/{example-tenant-id}
Hanya akun Microsoft pribadi: https://login.microsoftonline.com/consumers (konsumen menjadi nama panggilan untuk penyewa 9188040d-6c67-4c5b-b112-36a304b66dad)

Aplikasi multipenyewa

MICROSOFT Entra ID juga mendukung aplikasi multi-penyewa. Aplikasi ini mendukung:

Akun di direktori organisasi apa pun (direktori Microsoft Entra apa pun): https://login.microsoftonline.com/organizations
Akun di direktori organisasi apa pun (direktori Microsoft Entra apa pun) dan akun Microsoft pribadi (misalnya, Skype, XBox): https://login.microsoftonline.com/common

Untuk aplikasi ini, MICROSOFT Entra ID mengekspos versi independen penyewa dari dokumen OIDC di https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration dan https://login.microsoftonline.com/organizations/v2.0/.well-known/openid-configuration masing-masing. Titik akhir ini mengembalikan nilai pengeluar sertifikat, yang merupakan templat yang diparmetris oleh tenantid: https://login.microsoftonline.com/{tenantid}/v2.0. Aplikasi dapat menggunakan titik akhir independen penyewa ini untuk memvalidasi token dari setiap penyewa dengan ketentuan berikut:

Memvalidasi penerbit kunci penandatanganan
Alih-alih mengharapkan klaim penerbit dalam token sama persis dengan nilai penerbit dari metadata, aplikasi harus mengganti {tenantid} nilai dalam metadata penerbit dengan ID penyewa yang merupakan target permintaan saat ini, lalu memeriksa kecocokan yang tepat (tid klaim token).
Validasi bahwa tid klaim adalah GUID dan iss klaimnya adalah formulir https://login.microsoftonline.com/{tid}/v2.0 di mana {tid} adalah klaim yang tepat tid . Validasi ini mengikat penyewa kembali ke penerbit dan kembali ke cakupan kunci penandatanganan yang membuat rantai kepercayaan.
Gunakan tid klaim saat mereka menemukan data yang terkait dengan subjek klaim. Dengan kata lain, tid klaim harus menjadi bagian dari kunci yang digunakan untuk mengakses data pengguna.

Memvalidasi penerbit kunci penandatanganan

Aplikasi yang menggunakan metadata independen penyewa v2.0 perlu memvalidasi penerbit kunci penandatanganan.

Dokumen kunci dan pengeluar sertifikat kunci penandatanganan

Seperti yang dibahas, dari dokumen OpenID Koneksi, aplikasi Anda mengakses kunci yang digunakan untuk menandatangani token. Ini mendapatkan dokumen kunci yang sesuai dengan mengakses URL yang diekspos di properti jwks_uri dokumen OpenId Koneksi.

 "jwks_uri": "https://login.microsoftonline.com/{example-tenant-id}/discovery/v2.0/keys",

Nilai {example-tenant-id} dapat digantikan oleh GUID, nama domain, atau umum, organisasi , dan konsumen

Dokumen keys yang diekspos oleh Azure AD v2.0 berisi, untuk setiap kunci, penerbit yang menggunakan kunci penandatanganan ini. Misalnya, titik https://login.microsoftonline.com/common/discovery/v2.0/keys akhir kunci "umum" independen penyewa mengembalikan dokumen seperti:

{
  "keys":[
    {"kty":"RSA","use":"sig","kid":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","x5t":"jS1Xo1OWDj_52vbwGNgvQO2VzMc","n":"spv...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","x5t":"2ZQpJ3UpbjAYXYGaXEJl8lV0TOI","n":"wEM...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/{tenantid}/v2.0"},
    {"kty":"RSA","use":"sig","kid":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","x5t":"yreX2PsLi-qkbR8QDOmB_ySxp8Q","n":"rv0...","e":"AQAB","x5c":["MIID..."],"issuer":"https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0"}
  ]
}

Validasi penerbit kunci penandatanganan

Aplikasi harus menggunakan issuer properti dokumen kunci, yang terkait dengan kunci yang digunakan untuk menandatangani token, untuk membatasi cakupan kunci:

Kunci yang memiliki nilai pengeluar sertifikat dengan GUID seperti https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0 hanya boleh digunakan ketika iss klaim dalam token cocok dengan nilai dengan tepat.
Kunci yang memiliki nilai pengeluar sertifikat yang di-template seperti https://login.microsoftonline.com/{tenantid}/v2.0 hanya boleh digunakan ketika iss klaim dalam token cocok dengan nilai ini setelah mengganti tid klaim dalam token untuk {tenantid} tempat penampung.

Menggunakan metadata independen penyewa lebih efisien untuk aplikasi yang menerima token dari banyak penyewa.

Catatan

Dengan metadata independen penyewa Microsoft Entra, klaim harus ditafsirkan dalam penyewa, sama seperti di bawah Koneksi OpenID standar, klaim ditafsirkan dalam penerbit. Artinya, {"sub":"ABC123","iss":"https://login.microsoftonline.com/{example-tenant-id}/v2.0","tid":"{example-tenant-id}"} dan {"sub":"ABC123","iss":"https://login.microsoftonline.com/{another-tenand-id}/v2.0","tid":"{another-tenant-id}"} menjelaskan pengguna yang berbeda, meskipun sub sama, karena klaim seperti sub ditafsirkan dalam konteks penerbit/penyewa.

Rekap

Berikut adalah beberapa kode semu yang merekapitulasi ulang cara memvalidasi penerbit dan menandatangani penerbit kunci:

Mengambil kunci dari URL metadata yang dikonfigurasi
Periksa token jika ditandatangani dengan salah satu kunci yang diterbitkan, gagal jika tidak

Identifikasi kunci dalam metadata berdasarkan header anak. Periksa properti "penerbit" yang dilampirkan ke kunci dalam dokumen metadata:

var issuer = metadata["kid"].issuer;
if (issuer.contains("{tenantId}", CaseInvariant)) issuer = issuer.Replace("{tenantid}", token["tid"], CaseInvariant);
if (issuer != token["iss"]) throw validationException;
if (configuration.allowedIssuer != "*" && configuration.allowedIssuer != issuer) throw validationException;
var issUri = new Uri(token["iss"]);
if (issUri.Segments.Count < 1) throw validationException;
if (issUri.Segments[1] != token["tid"]) throw validationException;

Lihat juga

Langkah berikutnya

Pelajari selengkapnya tentang token keamanan yang digunakan dalam ID Microsoft Entra.

Bagikan melalui

Token akses dalam Platform identitas Microsoft

Format token

Kepemilikan token

Masa pakai token

Memvalidasi token

Token v1.0 dan v2.0

Memvalidasi penerbit

Memvalidasi tanda tangan

Memvalidasi penerbit

Aplikasi penyewa tunggal

Aplikasi multipenyewa

Memvalidasi penerbit kunci penandatanganan

Dokumen kunci dan pengeluar sertifikat kunci penandatanganan

Validasi penerbit kunci penandatanganan

Rekap

Lihat juga

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: