Memperoleh dan membuat cache token menggunakan Microsoft Authentication Library (MSAL)

Token akses memungkinkan klien untuk memanggil API web dengan aman yang dilindungi oleh Azure. Ada beberapa cara untuk memperoleh token dengan menggunakan Microsoft Authentication Library (MSAL). Beberapa mengharuskan interaksi pengguna melalui browser web, sementara yang lain tidak memerlukan interaksi pengguna. Secara umum, metode yang digunakan untuk memperoleh token tergantung pada apakah aplikasi tersebut adalah aplikasi klien publik seperti aplikasi desktop atau seluler, atau aplikasi klien rahasia seperti aplikasi web, web API, atau aplikasi daemon.

MSAL membuat cache token setelah diperoleh. Kode aplikasi Anda harus pertama mencoba untuk mendapatkan token senyap dari cache sebelum mencoba memperoleh token dengan cara lain.

Anda juga dapat menghapus cache token, yang dilakukan dengan menghapus akun dari cache. Namun, ini tidak menghapus cookie sesi yang ada di browser.

Cakupan saat memperoleh token

Cakupan adalah izin yang diekspos oleh API web dan aksesnya dapat diminta oleh aplikasi klien. Aplikasi klien meminta persetujuan pengguna untuk cakupan ini saat membuat permintaan autentikasi untuk mendapatkan token guna mengakses API web. MSAL memungkinkan Anda mendapatkan token guna mengakses Microsoft Azure AD untuk pengembang (v1.0) dan API platform identitas Microsoft. Protokol v2.0 menggunakan cakupan alih-alih sumber daya dalam permintaan. Berdasarkan konfigurasi web API dari versi token yang diterimanya, titik akhir v2.0 menghasilkan token akses ke MSAL.

Beberapa metode akuisisi token MSAL memerlukan parameter scopes. Parameter scopes adalah daftar untai (karakter) yang menyatakan izin yang diinginkan dan sumber daya yang diminta. Cakupan yang terkenal adalah izin Microsoft Graph.

Anda juga dapat mengakses sumber daya v1.0m di MSAL. Untuk informasi selengkapnya, lihat Cakupan untuk aplikasi v1.0.

Meminta cakupan untuk API web

Ketika aplikasi Anda perlu meminta token akses dengan izin tertentu untuk sumber daya API, melewati cakupan yang berisi URI ID aplikasi API dalam format <app ID URI>/<scope>.

Beberapa contoh nilai cakupan untuk sumber daya yang berbeda:

• API Microsoft Graph: https://graph.microsoft.com/User.Read
• API web kustom: api://11111111-1111-1111-1111-111111111111/api.read

Format nilai cakupan tergantung pada sumber daya (API) yang menerima token akses dan nilai klaim aud yang diterimanya.

Hanya untuk Microsoft Graph, pemetaan cakupan user.read ke https://graph.microsoft.com/User.Read, dan kedua format cakupan dapat digunakan secara bergantian.

API web tertentu seperti Azure Resource Manager API (https://management.core.windows.net/) mengharapkan garis miring berikutnya (/) dalam klaim audiens (aud) token akses. Dalam hal ini, berikan cakupan sebagai https://management.core.windows.net//user_impersonation, termasuk garis miring ke depan ganda (//).

API lain mungkin mengharuskan bahwa tidak ada skema atau host yang disertakan dalam nilai cakupan, dan hanya mengharapkan ID aplikasi (GUID) dan nama cakupan, contohnya:

11111111-1111-1111-1111-111111111111/api.read

Meminta cakupan dinamis untuk persetujuan bertahap

Ketika fitur yang disediakan oleh aplikasi atau persyaratannya berubah, Anda dapat meminta izin tambahan sesuai kebutuhan dengan menggunakan parameter cakupan. Cakupan dinamis tersebut memungkinkan pengguna Anda untuk memberikan persetujuan bertahap pada cakupan.

Contohnya, Anda mungkin memasukkan pengguna tetapi awalnya tidak memberikan akses ke sumber daya apa pun kepada pengguna. Nanti, Anda dapat memberi kemampuan kepada pengguna untuk melihat kalender dengan meminta cakupan kalender dalam metode memperoleh token dan mendapatkan persetujuan pengguna untuk melakukannya. Contohnya, dengan meminta cakupan https://graph.microsoft.com/User.Read dan https://graph.microsoft.com/Calendar.Read.

Memperoleh token secara senyap (dari cache)

MSAL memiliki cache token (atau dua cache untuk aplikasi klien rahasia) dan membuat cache token setelah diperoleh. Dalam banyak kasus, mencoba untuk mendapatkan token secara senyap akan memperoleh token lain dengan lebih banyak cakupan berdasarkan token di cache. MSAL juga mampu menyegarkan token ketika mendekati waktu kedaluwarsa (karena cache token juga berisi token refresh).

Pola panggilan yang disarankan untuk aplikasi klien publik

Kode sumber aplikasi harus terlebih dahulu mencoba mendapatkan token secara diam-diam dari cache. Jika panggilan metode menghasilkan kesalahan atau pengecualian "UI diperlukan", coba peroleh token dengan cara lain.

Namun, ada dua alur di mana Anda tidak boleh mencoba untuk memperoleh token secara senyap:

• Alur kredensial klien yang tidak menggunakan cache token pengguna tetapi cache token aplikasi. Metode ini mengurus verifikasi cache token aplikasi sebelum mengirim permintaan ke layanan token keamanan (STS).
• Alur kode otorisasi di aplikasi web, karena menukarkan kode yang diperoleh aplikasi dengan memasukkan pengguna dan meminta pengguna menyetujui lebih banyak cakupan. Karena kode, dan bukan akun, diteruskan sebagai parameter, metode ini tidak dapat melihat dalam cache sebelum menukarkan kode, yang membuat panggilan ke layanan.

Pola panggilan yang disarankan di aplikasi web menggunakan alur kode otorisasi

Untuk aplikasi Web yang menggunakan alur kode otorisasi OpenID Connect, pola yang disarankan dalam pengontrol adalah:

• Membuat instans aplikasi klien rahasia melalui cache token dengan serialisasi yang disesuaikan.
• Memperoleh token menggunakan alur kode otorisasi

Memperoleh token

Umumnya, metode memperoleh token tergantung jika itu aplikasi klien publik atau klien rahasia.

Aplikasi klien publik

Pada aplikasi klien publik seperti aplikasi seluler dan desktop, Anda dapat:

• Dapatkan token secara interaktif dengan meminta pengguna untuk masuk melalui antarmuka pengguna atau jendela pop-up.
• Dapatkan token secara senyap untuk pengguna yang masuk menggunakan autentikasi Windows terintegrasi (IWA/Kerberos) jika aplikasi desktop berjalan pada komputer Windows yang tergabung ke domain atau ke Azure.
• Dapatkan token dengan nama pengguna dan kata sandi di kerangka kerja .NET aplikasi klien desktop (tidak disarankan). Jangan gunakan nama pengguna/kata sandi di aplikasi klien rahasia.
• Dapatkan token melalui alur kode perangkat di aplikasi yang berjalan pada perangkat yang tidak memiliki browser web. Pengguna diberikan URL dan kode, yang kemudian membuka browser web di perangkat lain lalu memasukkan kode dan masuk. Microsoft Azure AD kemudian mengirim token kembali ke perangkat tanpa browser.

Aplikasi klien rahasia

Untuk aplikasi klien rahasia (aplikasi web, API web, atau aplikasi daemon seperti layanan Windows), Anda dapat;

• Memperoleh token untuk aplikasi itu sendiri dan bukan untuk pengguna, menggunakan alur kredensial klien. Teknik ini dapat digunakan untuk alat sinkronisasi, atau alat yang memproses pengguna secara umum dan bukan pengguna tertentu.
• Menggunakan alur atas nama (OBO) untuk API web guna memanggil API yang mewakili pengguna. Aplikasi ini teridentifikasi dengan info masuk klien untuk memperoleh token berdasarkan pernyataan pengguna (contohnya SAML, atau token JWT). Alur ini digunakan oleh aplikasi yang perlu mengakses sumber daya dari pengguna tertentu dalam panggilan layanan ke layanan.
• Memperoleh token menggunakan alur kode otorisasi di aplikasi web setelah pengguna masuk melalui URL permintaan otorisasi. Aplikasi OpenID Connect umumnya menggunakan mekanisme ini, yang memungkinkan pengguna untuk masuk menggunakan Open ID connect lalu mengakses API web atas nama pengguna.

Hasil autentikasi

Saat klien Anda meminta token akses, Microsoft Azure AD juga menghasilkan hasil autentikasi yang menyertakan metadata tentang token akses. Informasi ini mencakup waktu kedaluwarsa token akses dan cakupan yang valid. Data ini memungkinkan aplikasi Anda untuk melakukan penembolokan cerdas terhadap token akses tanpa harus memilah token akses itu sendiri. Hasil autentikasi mengekspos:

• Token akses untuk API web guna mengakses sumber daya. Untai (karakter) ini umumnya merupakan JWT berkode Base64, tetapi klien tidak boleh melihat ke dalam token akses. Formatnya tidak dijamin tetap stabil, dan dapat dienkripsi untuk sumber daya. Orang menulis kode yang bergantung pada konten token akses pada klien adalah salah satu sumber kesalahan yang paling umum dan kerusakan logika klien.
• Token ID untuk pengguna (JWT).
• Kedaluwarsa token, yang memberi tahu tanggal/waktu saat token kedaluwarsa.
• ID penyewa berisi penyewa tempat pengguna ditemukan. Untuk pengguna tamu (skenario Microsoft Azure AD B2B), ID penyewa adalah penyewa tamu, bukan penyewa unik. Ketika token dikirimkan atas nama pengguna, hasil autentikasi juga berisi informasi tentang pengguna ini. Untuk alur klien rahasia di mana token diminta tanpa pengguna (untuk aplikasi), informasi pengguna ini null.
• Cakupan yang diminta token.
• ID unik untuk pengguna.