Gambaran umum token - Azure Active Directory B2C

Artikel
04/24/2023

Azure Active Directory B2C (Azure AD B2C) memancarkan jenis token yang berbeda saat memproses setiap alur autentikasi. Artikel ini menjelaskan format, karakteristik keamanan, dan konten setiap jenis token.

Tipe token

Azure AD B2C mendukung protokol OAuth 2.0 dan OpenID Connect, yang menggunakan token untuk autentikasi dan akses aman ke sumber daya. Semua token yang digunakan di Azure AD B2C adalah token web JSON (JWTs) yang berisi pernyataan informasi tentang pembawa dan subjek token.

Token berikut digunakan dalam komunikasi dengan Azure AD B2C:

Token ID - JWT yang berisi klaim yang dapat Anda gunakan untuk mengidentifikasi pengguna di aplikasi Anda. Token ini dikirim dengan aman dalam permintaan HTTP untuk komunikasi antara dua komponen aplikasi atau layanan yang sama. Anda dapat menggunakan klaim dalam token ID sesuai keinginan Anda. Klaim tersebut biasanya digunakan untuk menampilkan informasi akun atau untuk membuat keputusan kontrol akses dalam aplikasi. Token ID yang dikeluarkan oleh Azure AD B2C ditandatangani, tetapi tidak dienkripsi. Ketika aplikasi atau API Anda menerima token ID, itu harus memvalidasi tanda tangan untuk membuktikan bahwa token tersebut asli. Aplikasi atau API Anda juga harus memvalidasi beberapa klaim dalam token untuk membuktikan bahwa itu valid. Tergantung pada persyaratan skenario, klaim yang divalidasi oleh aplikasi dapat bervariasi, tetapi aplikasi Anda harus melakukan beberapa validasi klaim umum dalam setiap skenario.
Token akses - JWT yang berisi klaim yang dapat digunakan untuk mengidentifikasi izin yang diberikan ke API Anda. Token akses ditandatangani, tetapi tidak dienkripsi. Token akses digunakan untuk menyediakan akses ke API dan server sumber daya. Ketika aplikasi atau API Anda menerima token akses, itu harus memvalidasi tanda tangan untuk membuktikan bahwa token tersebut asli. API Anda juga harus memvalidasi beberapa klaim dalam token untuk membuktikan bahwa itu valid. Tergantung pada persyaratan skenario, klaim yang divalidasi oleh aplikasi dapat bervariasi, tetapi aplikasi Anda harus melakukan beberapa validasi klaim umum dalam setiap skenario.
Token refresh - Token refresh digunakan untuk memperoleh token ID baru dan token akses dalam aliran OAuth 2.0. Mereka menyediakan aplikasi Anda dengan akses jangka panjang ke sumber daya atas nama pengguna tanpa memerlukan interaksi dengan pengguna tersebut. Token refresh buram untuk aplikasi Anda. Token tersebut dikeluarkan oleh Azure AD B2C dan hanya dapat diperiksa dan ditafsirkan oleh Azure AD B2C. Token berumur panjang, tetapi aplikasi Anda tidak boleh ditulis dengan harapan bahwa token refresh akan bertahan selama jangka waktu tertentu. Token refresh dapat dibatalkan kapan saja karena berbagai alasan. Satu-satunya cara agar aplikasi Anda mengetahui apakah token refresh valid adalah dengan mencoba menukarkannya dengan membuat permintaan token ke Azure AD B2C. Saat menukarkan token refresh dengan token baru, Anda akan menerima token refresh baru dalam respons token. Simpan token refresh baru. Ini menggantikan token refresh yang sebelumnya Anda gunakan dalam permintaan. Tindakan ini membantu menjamin bahwa token refresh Anda tetap berlaku selama mungkin. Perhatikan bahwa aplikasi satu halaman yang menggunakan aliran kode otorisasi dengan PKCE selalu memiliki masa pakai token refresh 24 jam. Pelajari lebih lanjut tentang implikasi keamanan token refresh di browser.

Titik akhir

Aplikasi terdaftar menerima token dan berkomunikasi dengan Azure AD B2C dengan mengirim permintaan ke titik akhir ini:

https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/authorize
https://<tenant-name>.b2clogin.com/<tenant-name>.onmicrosoft.com/<policy-name>/oauth2/v2.0/token

Token keamanan yang diterima aplikasi Anda dari Azure AD B2C dapat berasal dari /authorize atau /token titik akhir. Ketika token ID diperoleh dari:

/authorize titik akhir, ini dilakukan dengan menggunakan alur implisit, yang sering digunakan untuk pengguna yang masuk ke aplikasi web berbasis JavaScript. Tetapi, jika aplikasi Anda menggunakan MSAL.js 2.0 atau yang lebih baru, jangan aktifkan persetujuan alur implisit dalam pendaftaran aplikasi Anda karena MSAL.js 2.0+ mendukung alur kode otorisasi dengan PKCE.
/token titik akhir, ini dilakukan dengan menggunakan alur kode otorisasi, yang membuat token tetap tersembunyi dari browser.

Klaim

Saat Anda menggunakan Azure AD B2C, Anda memiliki kontrol yang halus atas konten token Anda. Anda dapat mengonfigurasi alur pengguna dan kebijakan kustom untuk mengirim kumpulan data pengguna tertentu dalam klaim yang diperlukan untuk aplikasi Anda. Klaim ini dapat mencakup properti standar seperti displayName dan emailAddress. Aplikasi Anda dapat menggunakan klaim ini untuk mengautentikasi pengguna dan permintaan dengan aman.

Klaim dalam token ID tidak dikembalikan dalam urutan tertentu. Klaim baru dapat diperkenalkan dalam token ID kapan saja. Aplikasi Anda tidak boleh rusak saat klaim baru diperkenalkan. Anda juga dapat menyertakan atribut pengguna khusus dalam klaim Anda.

Tabel berikut mencantumkan klaim yang bisa Anda harapkan dalam token ID dan token akses yang dikeluarkan oleh Azure AD B2C.

Nama	Klaim	Contoh nilai	Deskripsi
Audiens	`aud`	`90c0fe63-bcf2-44d5-8fb7-b8bbc0b29dc6`	Mengidentifikasi penerima token yang dimaksud. Untuk Azure AD B2C, audiens adalah ID aplikasi. Aplikasi Anda harus memvalidasi nilai ini dan menolak token jika tidak cocok. Audiens sinonim dengan sumber daya.
Pengeluar sertifikat	`iss`	`https://<tenant-name>.b2clogin.com/775527ff-9a37-4307-8b3d-cc311f58d925/v2.0/`	Mengidentifikasi layanan token keamanan (STS) yang membangun dan mengembalikan token. Ini juga mengidentifikasi direktori di mana pengguna diautentikasi. Aplikasi Anda harus memvalidasi klaim pengeluar sertifikat untuk memastikan bahwa token berasal dari titik akhir yang sesuai.
Diterbitkan pada	`iat`	`1438535543`	Waktu di mana token diterbitkan, dinyatakan dalam satuan waktu epoch.
Waktu kedaluwarsa	`exp`	`1438539443`	Waktu di mana token menjadi tidak valid, dinyatakan dalam satuan waktu epoch. Aplikasi Anda harus menggunakan klaim ini untuk memverifikasi validitas masa pakai token.
Tidak sebelum	`nbf`	`1438535543`	Waktu di mana token menjadi valid, dinyatakan dalam satuan waktu epoch. Waktu yang dipakai ini biasanya sama dengan waktu saat token dikeluarkan. Aplikasi Anda harus menggunakan klaim ini untuk memverifikasi validitas masa pakai token.
Versi	`ver`	`1.0`	Versi token ID, seperti yang didefinisikan oleh Azure AD B2C.
Hash kode	`c_hash`	`SGCPtt01wxwfgnYZy2VJtQ`	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 informasi selengkapnya tentang cara melakukan validasi ini, lihat spesifikasi OpenID Connect.
Hash token akses	`at_hash`	`SGCPtt01wxwfgnYZy2VJtQ`	Hash token akses yang disertakan dalam token ID hanya ketika token diterbitkan bersama dengan token akses OAuth 2.0. Hash token akses dapat digunakan untuk memvalidasi keaslian token akses. Untuk informasi selengkapnya tentang cara melakukan validasi ini, lihat spesifikasi OpenID Connect
Nonce	`nonce`	`12345`	Nonce adalah strategi yang digunakan untuk mengurangi serangan replay token. Aplikasi Anda dapat menentukan nonce dalam permintaan otorisasi dengan menggunakan `nonce` parameter kueri. Nilai yang Anda berikan dalam permintaan dipancarkan tanpa modifikasi dalam `nonce` klaim token ID saja. Klaim ini memungkinkan aplikasi Anda untuk memverifikasi nilai terhadap nilai yang ditentukan pada permintaan. Aplikasi Anda harus melakukan validasi ini selama proses validasi token ID.
Subjek	`sub`	`884408e1-2918-4cz0-b12d-3aa027d7563b`	Ini adalah prinsipal yang tokennya menegaskan informasi, seperti pengguna aplikasi. Nilai ini tidak berubah dan tidak dapat ditetapkan atau digunakan kembali. Ini dapat digunakan untuk melakukan pemeriksaan otorisasi dengan aman, seperti saat token digunakan untuk mengakses sumber daya. Secara default, klaim subjek diisi dengan ID objek pengguna di direktori.
Menyertakan referensi kelas konteks autentikasi	`acr`	Tidak berlaku	Hanya digunakan dengan kebijakan yang lebih lama.
Kebijakann kerangka kerja	`tfp`	`b2c_1_signupsignin1`	Nama kebijakan yang digunakan untuk memperoleh token ID.
Waktu autentikasi	`auth_time`	`1438535543`	Waktu di mana pengguna terakhir kali memasukkan info masuk, dinyatakan dalam satuan waktu epoch. Tidak ada diskriminasi antara autentikasi tersebut menjadi rincian masuk baru, sesi akses menyeluruh (SSO), atau jenis masuk lainnya. Ini `auth_time` adalah terakhir kalinya aplikasi (atau pengguna) memulai upaya autentikasi terhadap Azure AD B2C. Metode yang digunakan untuk mengautentikasi tidak dibedakan.
Cakupan	`scp`	`Read`	Izin yang diberikan ke sumber daya untuk token akses. Beberapa izin yang diberikan dipisahkan oleh spasi.
Pihak yang berwenang	`azp`	`975251ed-e4f5-4efd-abcb-5f1a8f566ab7`	ID aplikasi dari aplikasi klien yang memulai permintaan.

Konfigurasi

Properti berikut digunakan untuk mengelola token keamanan seumur hidup yang dipancarkan oleh Azure AD B2C:

Akses & masa berlaku token ID (menit) - Masa berlaku token pembawa OAuth 2.0 yang digunakan untuk mendapatkan akses ke sumber daya yang dilindungi. Defaultnya adalah 60 menit. Minimum (inklusif) 5 menit. Maksimum (inklusif) 1440 menit.
Refresh masa pakai token (hari) - Periode waktu maksimum sebelum token refresh dapat digunakan untuk memperoleh akses baru atau token ID. Periode waktu juga mencakup memperoleh token refresh baru jika aplikasi Anda telah diberikan offline_access cakupan. Defaultnya 14 hari. Minimum (inklusif) satu hari. Maksimum (inklusif) 90 hari.
Panjang masa pakai jendela geser token Refresh (hari) - Setelah periode waktu ini berlalu, pengguna dipaksa untuk mengautentikasi ulang, terlepas dari masa berlaku token refresh terbaru yang diperoleh oleh aplikasi. Ini hanya dapat disediakan jika sakelar diset ke Terbatas. Nilai harus lebih besar dari atau sama dengan nilai masa pakai token Refresh. Jika sakelar diatur ke Tidak ada kedaluwarsa, Anda tidak dapat memberikan nilai tertentu. Defaultnya 90 hari. Minimum (inklusif) satu hari. Maksimum (inklusif) 365 hari.

Kasus penggunaan berikut diaktifkan menggunakan properti ini:

Izinkan pengguna untuk tetap masuk ke aplikasi seluler tanpa batas waktu, selama pengguna terus aktif pada aplikasi. Anda dapat mengatur masa pakai jendela geser token Refresh (hari) ke Tidak Terbatas di aliran pengguna masuk Anda.
Penuhi persyaratan keamanan dan kepatuhan industri Anda dengan mengatur masa pakai token akses yang sesuai.

Pengaturan ini tidak tersedia untuk alur pengguna pengaturan ulang kata sandi.

Kompatibilitas

Properti berikut digunakan untuk mengelola kompatibilitas token:

Klaim penerbit (iss) - Properti ini mengidentifikasi penyewa Azure AD B2C yang menerbitkan token. Nilai defaultnya adalah https://<domain>/{B2C tenant GUID}/v2.0/. Nilai https://<domain>/tfp/{B2C tenant GUID}/{Policy ID}/v2.0/ termasuk ID untuk penyewa Azure AD B2C dan alur pengguna yang digunakan dalam permintaan token. Jika aplikasi atau pustaka Anda memerlukan Azure AD B2C agar sesuai dengan spesifikasi OpenID Connect Discovery 1.0, gunakan nilai ini.
Subjek (sub) klaim - Properti ini mengidentifikasi entitas yang tokennya menegaskan informasi. Nilai default adalah ObjectID, yang mengisi sub klaim dalam token dengan ID objek pengguna. Nilai Tidak didukung hanya disediakan untuk kompatibilitas mundur. Sebaiknya Anda beralih ke ObjectID segera setelah Anda dapat melakukannya.
Klaim yang mewakili ID kebijakan - Properti ini mengidentifikasi jenis klaim tempat nama kebijakan yang digunakan dalam permintaan token diisi. Nilai defaultnya adalah tfp. Nilai acr hanya disediakan untuk kompatibilitas mundur.

Pass-through

Saat perjalanan dimulai, Azure AD B2C menerima token akses dari IdP. Azure AD B2C menggunakan token itu untuk mengambil informasi tentang pengguna. Anda mengaktifkan klaim dalam alur pengguna Anda untuk meneruskan token ke aplikasi yang Anda daftarkan di Azure AD B2C. Aplikasi Anda harus menggunakan alur pengguna yang direkomendasikan untuk memanfaatkan melewati token sebagai klaim.

Azure AD B2C saat ini hanya mendukung penerusan token akses IdP OAuth 2.0, yang mencakup Facebook dan Google. Untuk semua IdP lainnya, klaim dikembalikan kosong.

Validasi

Untuk memvalidasi token, aplikasi Anda harus memeriksa tanda tangan dan klaim token. Banyak pustaka sumber terbuka tersedia untuk memvalidasi JWTs, sesuai dengan bahasa yang Anda pilih. Disarankan agar Anda mengeksplorasi opsi tersebut daripada menerapkan logika validasi Anda sendiri.

Memvalidasi tanda tangan

JWT berisi tiga segmen, header, isi, dan tanda tangan. Segmen tanda tangan dapat digunakan untuk memvalidasi keaslian token sehingga dapat dipercaya oleh aplikasi Anda. Token Azure AD B2C ditandatangani dengan menggunakan algoritme enkripsi asimetris standar industri, seperti RSA 256.

Header token berisi informasi tentang kunci dan metode enkripsi yang digunakan untuk menandatangani token:

{
        "typ": "JWT",
        "alg": "RS256",
        "kid": "GvnPApfWMdLRi8PDmisFn7bprKg"
}

Nilai klaim alg adalah algoritma yang digunakan untuk menandatangani token. Nilai klaim kid adalah kunci umum yang digunakan untuk menandatangani token. Pada waktu tertentu, Azure AD B2C dapat menandatangani token dengan menggunakan salah satu dari satu set pasangan kunci publik-pribadi. Azure AD B2C memutar kumpulan kunci yang mungkin secara berkala. Aplikasi Anda harus ditulis untuk menangani perubahan kunci tersebut secara otomatis. Frekuensi yang wajar untuk memeriksa pembaruan kunci umum yang digunakan oleh Azure AD B2C adalah setiap 24 jam. Untuk menangani perubahan kunci yang tidak terduga, aplikasi Anda harus ditulis untuk mengambil kembali kunci umum jika menerima nilai kid yang tak terduga.

Azure AD B2C memiliki titik akhir metadata OpenID Connect. Dengan menggunakan titik akhir ini, aplikasi dapat meminta informasi tentang Azure AD B2C pada waktu proses. Informasi ini meliputi titik akhir, konten token, dan kunci penandatanganan token. Penyewa Azure AD B2C Anda berisi dokumen metadata JSON untuk setiap kebijakan. Dokumen metadata adalah objek JSON yang berisi beberapa informasi yang berguna. Metadata berisi jwks_uri, yang memberikan lokasi set kunci umum yang digunakan untuk menandatangani token. Lokasi itu disediakan di sini, tetapi yang terbaik adalah mengambil lokasi secara dinamis dengan menggunakan dokumen metadata dan menguraikan jwks_uri:

https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_signupsignin1/discovery/v2.0/keys

Dokumen JSON yang terletak di URL ini berisi semua informasi kunci umum yang digunakan pada saat tertentu. Aplikasi Anda dapat menggunakan kid klaim di header JWT untuk memilih kunci umum di dokumen JSON yang digunakan untuk menandatangani token tertentu. Kemudian dapat melakukan validasi tanda tangan dengan menggunakan kunci umum yang benar dan algoritma yang ditunjukkan.

Dokumen metadata untuk B2C_1_signupsignin1 kebijakan dalam contoso.onmicrosoft.com penyewa terletak di:

https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_signupsignin1/v2.0/.well-known/openid-configuration

Untuk menentukan kebijakan apa yang digunakan untuk menandatangani token (dan tempat untuk meminta metadata), Anda memiliki dua opsi. Pertama, nama kebijakan disertakan dalam tfp (default) atau acr klaim (sebagaimana dikonfigurasi) dalam token. Anda dapat memilah klaim keluar dari tubuh JWT dengan basis-64 mendekroding tubuh dan mendeserialisasi string JSON yang menghasilkan. tfp Atau acr klaim adalah nama kebijakan yang digunakan untuk menerbitkan token. Pilihan Anda yang lain adalah menyandikan aliran pengguna dalam nilai state parameter saat Anda menerbitkan permintaan, lalu mendekodenya untuk menentukan aliran pengguna mana yang digunakan. Masing-masing metode tersebut adalah valid.

Azure AD B2C menggunakan algoritma RS256, yang didasarkan pada spesifikasi RFC 3447. Kunci umum terdiri dari dua komponen: modulus RSA (n) dan eksponen publik RSA (e). Anda dapat secara terprogram mengonversi nilai n dan e ke format sertifikat untuk validasi token.

Deskripsi tentang cara melakukan validasi tanda tangan berada di luar cakupan dokumen ini. Banyak pustaka sumber terbuka tersedia untuk membantu Anda memvalidasi token.

Memvalidasi klaim

Ketika aplikasi atau API Anda menerima token ID, aplikasi atau API juga harus melakukan beberapa pemeriksaan terhadap klaim dalam token ID. Klaim berikut harus diperiksa:

audiens - Memverifikasi bahwa token ID dimaksudkan untuk diberikan ke aplikasi Anda.
tidak sebelum dan waktu kedaluwarsa - Memverifikasi bahwa token ID belum kedaluwarsa.
pengeluar sertifikat - Memverifikasi bahwa token dikeluarkan untuk aplikasi Anda oleh Azure AD B2C.
nonce - Strategi untuk mitigasi serangan replay token.

Untuk daftar lengkap validasi yang harus dilakukan aplikasi Anda, lihat spesifikasi OpenID Connect.

Langkah berikutnya

Pelajari lebih lanjut tentang cara menggunakan token akses.