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

  • Artikel

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. Biasanya, metode yang digunakan untuk memperoleh token tergantung pada apakah aplikasi tersebut adalah aplikasi klien publik (desktop atau seluler), atau aplikasi klien rahasia (aplikasi web, API web, 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 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 untuk mengakses 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.

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

Tip

Jika sumber daya downstream tidak berada di bawah kendali Anda, Anda mungkin perlu mencoba format nilai cakupan yang berbeda (contohnya dengan/tanpa skema dan host) jika Anda menerima 401 atau kesalahan lain saat meneruskan token akses ke sumber daya.

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).

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.

Ada dua alur di mana Anda tidak boleh mencoba memperoleh token secara diam-diam:

  • Alur info masuk klien, yang tidak menggunakan cache token pengguna, melainkan 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.

Untuk aplikasi web yang menggunakan alur kode otorisasi OpenID Koneksi, pola yang direkomendasikan dalam pengontrol adalah untuk:

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

Memperoleh token

Metode memperoleh token tergantung pada apakah itu klien publik atau aplikasi klien rahasia.

Aplikasi klien publik

Di aplikasi klien publik (desktop dan seluler), 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 aplikasi klien desktop .NET Framework (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 Entra ID 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 info masuk 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. Token harus di-cache berdasarkan sesi, bukan berdasarkan pengguna.
  • Memperoleh token menggunakan alur kode otorisasi di aplikasi web setelah pengguna masuk melalui URL permintaan otorisasi. Aplikasi Koneksi OpenID biasanya menggunakan mekanisme ini, yang memungkinkan pengguna masuk menggunakan OpenID Koneksi lalu mengakses API web atas nama pengguna. Token dapat di-cache pada pengguna atau berdasarkan sesi. Jika penembolokan token berdasarkan pengguna, sebaiknya batasi masa pakai sesi, sehingga ID Microsoft Entra dapat sering memeriksa status kebijakan Akses Bersyariah.

Hasil autentikasi

Saat klien Anda meminta token akses, MICROSOFT Entra ID juga mengembalikan 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. String ini biasanya merupakan JWT yang dikodekan 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 Entra 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.

(Tingkat lanjut) Mengakses token cache milik pengguna di aplikasi dan layanan latar belakang

Anda dapat menggunakan implementasi cache token MSAL untuk memungkinkan aplikasi latar belakang, API, dan layanan menggunakan cache token akses untuk terus bertindak atas nama pengguna saat mereka tidak ada. Melakukan implementasi tersebut sangat berguna jika aplikasi dan layanan latar belakang perlu terus bekerja atas nama pengguna setelah pengguna keluar dari aplikasi web front-end.

Saat ini, sebagian besar proses latar belakang menggunakan izin aplikasi ketika mereka perlu bekerja dengan data pengguna tanpa mereka hadir untuk mengautentikasi atau mengotorisasi ulang. Karena izin aplikasi sering kali memerlukan izin admin, yang memerlukan peningkatan hak istimewa, gesekan yang tidak perlu terjadi karena pengembang tidak bermaksud untuk mendapatkan izin di luar izin yang awalnya disetujui pengguna untuk aplikasi mereka.

Contoh kode pada GitHub ini menunjukkan cara menghindari gesekan yang tidak perlu ini dengan mengakses cache token MSAL dari aplikasi latar belakang:

Mengakses cache token pengguna yang masuk dari aplikasi latar belakang, API, dan layanan

Lihat juga

Beberapa platform yang didukung oleh MSAL memiliki informasi terkait cache token tambahan dalam dokumentasi untuk pustaka platform itu. Misalnya: