Dukungan alur autentikasi di MSAL

  • Artikel

Pustaka Autentikasi Microsoft (MSAL) mendukung beberapa pemberian otorisasi dan alur token terkait untuk digunakan oleh berbagai jenis aplikasi dan skenario berbeda.

Alur autentikasi Aktifkan Jenis aplikasi yang didukung
Kode otorisasi Proses masuk pengguna dan akses ke API web atas nama pengguna. Desktop
Platform
Aplikasi satu halaman (SPA) (memerlukan PKCE)
Web
Informasi masuk klien Akses ke API web menggunakan identitas aplikasi itu sendiri. Biasanya digunakan untuk komunikasi server-ke-server dan skrip otomatis yang tidak memerlukan interaksi pengguna. Daemon
Kode perangkat Proses masuk pengguna dan akses ke API web atas nama pengguna pada perangkat yang dibatasi input seperti smart TV dan perangkat IoT. Juga digunakan oleh aplikasi antarmuka tingkat panggilan (CLI). Desktop, Seluler
Pemberian implisit Proses masuk pengguna dan akses ke API web atas nama pengguna. Alur pemberian implisit tidak lagi direkomendasikan - gunakan kode otorisasi dengan PKCE sebagai gantinya. * Aplikasi satu halaman (SPA)
* Web
Atas nama (OBO) Akses dari API web "upstream" ke API web "downstream" atas nama pengguna. Identitas pengguna dan izin yang didelegasikan diteruskan ke API downstream dari API upstream. API Web
Nama pengguna/kata sandi (ROPC) Memungkinkan aplikasi untuk masuk ke pengguna dengan langsung menangani kata sandinya. Alur ROPC TIDAK disarankan. Desktop, Seluler
Autentikasi Windows terintegrasi (IWA) Memungkinkan aplikasi pada domain atau komputer yang bergabung dengan Microsoft Entra untuk memperoleh token secara diam-diam (tanpa interaksi UI dari pengguna). Desktop, Seluler

Token

Aplikasi Anda dapat menggunakan satu alur autentikasi atau lebih. Setiap alur menggunakan jenis token tertentu untuk autentikasi, otorisasi, dan refresh token, dan beberapa juga menggunakan kode otorisasi.

Alur atau tindakan autentikasi Memerlukan Token ID Token akses Token refresh Kode otorisasi
Alur kode otorisasi Alur autentikasi berfungsi untuk token ID Alur autentikasi berfungsi untuk token akses Alur autentikasi berfungsi untuk token refresh Kode otorisasi berfungsi
Informasi masuk klien Alur autentikasi berfungsi untuk token akses (khusus aplikasi)
Aliran kode perangkat Alur autentikasi berfungsi untuk token ID Alur autentikasi berfungsi untuk token akses Alur autentikasi berfungsi untuk token refresh
Alur implisit Alur autentikasi berfungsi untuk token ID Alur autentikasi berfungsi untuk token akses
Alur atas nama token akses Alur autentikasi berfungsi untuk token ID Alur autentikasi berfungsi untuk token akses Alur autentikasi berfungsi untuk token refresh
Nama pengguna/kata sandi (ROPC) nama pengguna, kata sandi Alur autentikasi berfungsi untuk token ID Alur autentikasi berfungsi untuk token akses Alur autentikasi berfungsi untuk token refresh
Alur OIDC hibrid Alur autentikasi berfungsi untuk token ID Kode otorisasi berfungsi
Penukaran token refresh token refresh Alur autentikasi berfungsi untuk token ID Alur autentikasi berfungsi untuk token akses Alur autentikasi berfungsi untuk token refresh

Autentikasi interaktif dan non-interaktif

Beberapa alur ini mendukung akuisisi token interaktif dan non-interaktif.

  • Interaktif - Pengguna dapat diminta input oleh server otorisasi. Misalnya, untuk masuk, lakukan autentikasi multifaktor (MFA), atau untuk memberikan persetujuan untuk lebih banyak izin akses sumber daya.
  • Non-interaktif (diam) - Pengguna mungkin tidak dimintai masukan. Juga disebut akuisisi token "diam", aplikasi mencoba untuk mendapatkan token menggunakan metode di mana server otorisasi mungkin tidak meminta pengguna untuk input.

Aplikasi berbasis MSAL Anda harus terlebih dahulu mencoba memperoleh token secara senyap dan kembali ke metode interaktif hanya jika upaya non-interaktif gagal. Untuk informasi selengkapnya tentang pola ini, lihat Memperoleh dan menyimpan token menggunakan Microsoft Authentication Library (MSAL).

Kode otorisasi

Pemberian kode otorisasi OAuth 2.0 dapat digunakan oleh aplikasi web, aplikasi satu halaman (SPA), dan aplikasi asli (seluler dan desktop) untuk mendapatkan akses ke sumber daya yang dilindungi seperti API web.

Ketika pengguna masuk ke aplikasi web, aplikasi menerima kode otorisasi yang dapat ditukarkan dengan token akses untuk memanggil API web.

Dalam diagram berikut, aplikasi:

  1. Meminta kode otorisasi yang ditukarkan untuk token akses
  2. Menggunakan token akses untuk memanggil API web, Microsoft Graph

Diagram alur kode otorisasi.

Batasan untuk kode otorisasi

  • Aplikasi satu halaman memerlukan Proof Key for Code Exchange (PKCE) saat menggunakan alur pemberian kode otorisasi. PKCE didukung oleh MSAL.

  • Spesifikasi OAuth 2.0 mengharuskan Anda menggunakan kode otorisasi untuk menukarkan token akses hanya sekali.

    Jika Anda mencoba memperoleh token akses beberapa kali dengan kode otorisasi yang sama, kesalahan yang mirip dengan yang berikut dikembalikan oleh platform identitas Microsoft. Beberapa pustaka dan kerangka kerja meminta kode otorisasi untuk Anda secara otomatis, dan meminta kode secara manual dalam kasus seperti itu juga akan mengakibatkan kesalahan ini.

    AADSTS70002: Error validating credentials. AADSTS54005: OAuth2 Authorization code was already redeemed, please retry with a new valid code or use an existing refresh token.

Informasi masuk klien

Alur kredensial klien OAuth 2.0 memungkinkan Anda mengakses sumber daya yang dihosting web dengan menggunakan identitas aplikasi. Jenis pemberian ini umumnya digunakan untuk interaksi server-ke-server yang harus dijalankan di latar belakang, tanpa interaksi langsung dengan pengguna. Jenis aplikasi ini sering disebut sebagai daemon atau akun layanan.

Alur pemberian info masuk mengizinkan layanan web (klien rahasia) untuk menggunakan info masuknya sendiri, bukan meniru identitas pengguna, untuk mengautentikasi saat memanggil layanan web lain. Dalam skenario ini, klien biasanya adalah layanan web tingkat menengah, layanan daemon, atau situs web. Untuk tingkat jaminan yang lebih tinggi, platform identitas Microsoft juga memungkinkan layanan panggilan menggunakan sertifikat (bukan rahasia bersama) sebagai informasi masuk.

Rahasia aplikasi

Dalam diagram berikut, aplikasi:

  1. Memperoleh token dengan menggunakan rahasia aplikasi atau kredensial kata sandi
  2. Menggunakan token untuk membuat permintaan sumber daya

Diagram klien rahasia dengan kata sandi.

Sertifikat

Dalam diagram berikut, aplikasi:

  1. Memperoleh token dengan menggunakan kredensial sertifikat
  2. Menggunakan token untuk membuat permintaan sumber daya

Diagram klien rahasia dengan sertifikasi.

Informasi masuk klien ini perlu:

  • Terdaftar dengan MICROSOFT Entra ID
  • Diteruskan saat membuat objek aplikasi klien rahasia dalam kode Anda

Batasan untuk info masuk klien

Alur klien rahasia tidak didukung pada platform seluler seperti Android, iOS, atau UWP. Aplikasi seluler dianggap sebagai aplikasi klien publik yang tidak mampu menjamin kerahasiaan info masuk mereka.

Kode perangkat

Alur kode perangkat OAuth 2.0 memungkinkan pengguna untuk masuk ke perangkat yang dibatasi input seperti TV pintar, perangkat IoT, dan printer. Autentikasi interaktif dengan MICROSOFT Entra ID memerlukan browser web. Jika perangkat atau sistem operasi tidak menyediakan browser web, alur kode perangkat memungkinkan pengguna menggunakan perangkat lain seperti komputer atau ponsel untuk masuk secara interaktif.

Menggunakan alur kode perangkat, aplikasi memperoleh token melalui proses dua langkah yang dirancang untuk perangkat dan sistem operasi ini. Contoh aplikasi tersebut termasuk yang berjalan pada perangkat IoT dan alat antarmuka baris perintah (CLI).

Dalam diagram berikut:

  1. Setiap kali autentikasi pengguna diperlukan, aplikasi menyediakan kode dan meminta pengguna untuk menggunakan perangkat lain seperti smartphone yang tersambung ke internet untuk mengunjungi URL (misalnya, https://microsoft.com/devicelogin). Pengguna kemudian diminta untuk memasukkan kode, dan melanjutkan melalui pengalaman autentikasi normal termasuk permintaan persetujuan dan autentikasi multifaktor, jika perlu.
  2. Setelah autentikasi berhasil, aplikasi baris perintah menerima token yang diperlukan melalui saluran belakang, dan menggunakannya untuk melakukan panggilan API web yang diperlukan.

Diagram alur kode perangkat.

Batasan untuk kode perangkat

  • Alur kode perangkat hanya tersedia untuk aplikasi klien publik.
  • Saat Anda menginisialisasi aplikasi klien publik di MSAL, gunakan salah satu format otoritas ini:
    • Penyewa: https://login.microsoftonline.com/{tenant}/, di mana {tenant} adalah ID penyewa atau nama domain yang terkait dengan penyewa.
    • Akun kantor dan sekolah: https://login.microsoftonline.com/organizations/.

Pemberian implisit

Alur pemberian implisit telah digantikan oleh alur kode otorisasi dengan PKCE sebagai alur pemberian token yang lebih disukai dan lebih aman untuk aplikasi halaman tunggal (SPAs) sisi klien. Tidak disarankan lagi untuk menggunakan alur pemberian implisit. Jika Anda sedang membangun SPA, gunakan alur kode otorisasi dengan PKCE sebagai gantinya.

Aplikasi web satu halaman yang ditulis dalam JavaScript (termasuk kerangka kerja seperti Angular, Vue.js, atau React.js) diunduh dari server dan kodenya berjalan langsung di browser. Karena kode sisi klien mereka berjalan di browser dan bukan di server web, mereka memiliki karakteristik keamanan yang berbeda dari aplikasi web sisi server tradisional. Sebelum ketersediaan Kunci Bukti untuk Penukaran Kode (PKCE) untuk alur kode otorisasi, alur pemberian implisit digunakan oleh SPA untuk meningkatkan responsivitas dan efisiensi dalam mendapatkan token akses.

Alur pemberian implisit OAuth 2.0 memungkinkan aplikasi untuk mendapatkan token akses dari platform identitas Microsoft tanpa melakukan pertukaran kredensial server back-end. Alur pemberian implisit memungkinkan aplikasi untuk memasukkan pengguna, mempertahankan sesi, dan mendapatkan token untuk API web lainnya dari dalam kode JavaScript yang diunduh dan dijalankan oleh agen pengguna (biasanya browser web).

Diagram alur pemberian hibah

Batasan untuk pemberian implisit

Alur pemberian implisit tidak termasuk skenario aplikasi yang menggunakan kerangka kerja JavaScript lintas platform seperti Electron atau React Native. Kerangka kerja lintas platform seperti ini membutuhkan kemampuan lebih lanjut untuk interaksi dengan platform desktop dan seluler asli tempat mereka dijalankan.

Token yang dikeluarkan melalui mode alur implisit memiliki batasan panjang karena dikembalikan ke browser berdasarkan URL (dengan response_mode adalah query atau fragment). Beberapa browser membatasi panjang URL di bilah browser dan gagal ketika terlalu panjang. Dengan demikian, token alur implisit ini tidak berisi klaim groups atau wids.

Atas Nama (OBO)

Alur autentikasi atas nama OAuth 2.0 digunakan saat aplikasi memanggil layanan atau API web yang pada gilirannya perlu memanggil layanan atau API web lain. Idenya adalah untuk menyebarluaskan identitas pengguna dan izin yang didelegasikan melalui rantai permintaan. Agar layanan tingkat menengah membuat permintaan terautentikasi ke layanan hilir, perlu mengamankan token akses dari platform identitas Microsoft atas nama pengguna.

Dalam diagram berikut:

  1. Aplikasi ini memperoleh token akses untuk API web.
  2. Klien (aplikasi web, desktop, seluler, atau halaman tunggal) memanggil API web yang dilindungi, menambahkan token akses sebagai token pembawa di header autentikasi permintaan HTTP. API web mengautentikasi pengguna.
  3. Ketika klien memanggil API web, API web meminta token lain atas nama pengguna.
  4. API web yang dilindungi menggunakan token ini untuk memanggil API web hilir atas nama pengguna. Api web juga nantinya dapat meminta token untuk API hilir lainnya (tetapi masih atas nama pengguna yang sama).

Diagram aliran atas nama.

Nama pengguna/kata sandi (ROPC)

Peringatan

Alur info masuk kata sandi pemilik sumber daya (ROPC) TIDAK disarankan. ROPC membutuhkan tingkat kepercayaan dan paparan info masuk yang tinggi. Beralih menggunakan ROPC hanya jika alur yang lebih aman tidak dapat digunakan. Untuk informasi selengkapnya, lihat Apa solusi untuk masalah kata sandi yang berkembang?.

Pemberian info masuk kata sandi pemilik sumber daya OAuth 2.0 (ROPC) memungkinkan aplikasi untuk masuk ke pengguna dengan langsung menangani kata sandi mereka. Di aplikasi desktop, Anda dapat menggunakan alur nama pengguna/kata sandi untuk memperoleh token secara senyap. UI tidak diperlukan saat menggunakan aplikasi.

Beberapa skenario aplikasi seperti DevOps mungkin menganggap ROPC berguna, tetapi Anda harus menghindarinya di aplikasi apa pun di mana Anda menyediakan UI interaktif untuk proses masuk pengguna.

Dalam diagram berikut, aplikasi:

  1. Memperoleh token dengan mengirim nama pengguna dan kata sandi ke idP
  2. Memanggil API web dengan menggunakan token

Diagram alur nama pengguna/kata sandi.

Untuk memperoleh token secara senyap di mesin yang bergabung dengan domain Windows, kami merekomendasikan autentikasi Windows terintegrasi (IWA) sebagai ganti ROPC. Untuk skenario lainnya, gunakan alur kode perangkat.

Batasan untuk ROPC

Batasan berikut berlaku untuk aplikasi menggunakan alur ROPC:

  • Akses menyeluruh tidak didukung.
  • Autentikasi multifaktor (MFA) tidak didukung.
    • Periksa dengan admin penyewa Anda sebelum menggunakan alur ini - MFA adalah fitur yang umum digunakan.
  • Akses Bersyarat tidak didukung.
  • ROPC hanya berfungsi untuk akun kantor dan sekolah.
  • Akun Microsoft Pribadi (MSA) tidak didukung oleh ROPC.
  • ROPC didukung di desktop .NET dan aplikasi ASP.NET Core.
  • ROPC tidak didukung dalam aplikasi Universal Windows Platform (UWP).
  • ROPC di Azure AD B2C hanya didukung untuk akun lokal.

Autentikasi Windows terintegrasi (IWA)

MSAL mendukung autentikasi Windows terintegrasi (IWA) untuk aplikasi desktop dan seluler yang berjalan pada komputer Windows yang bergabung dengan domain atau Microsoft Entra. Menggunakan IWA, aplikasi ini memperoleh token secara senyap tanpa memerlukan interaksi antarmuka pengguna oleh pengguna.

Dalam diagram berikut, aplikasi:

  1. Memperoleh token dengan menggunakan autentikasi Windows terintegrasi
  2. Menggunakan token untuk membuat permintaan sumber daya

Diagram autentikasi Windows terintegrasi.

Batasan untuk IWA

Kompatibilitas

Autentikasi Windows Terintegrasi (IWA) diaktifkan untuk aplikasi .NET desktop, .NET, dan Windows Universal Platform.

IWA hanya mendukung pengguna federasi Layanan Federasi Direktori Aktif - pengguna yang dibuat di Direktori Aktif dan didukung oleh ID Microsoft Entra. Pengguna yang dibuat langsung di MICROSOFT Entra ID tanpa dukungan Direktori Aktif (pengguna terkelola) tidak dapat menggunakan alur autentikasi ini.

Autentikasi multifaktor (MFA)

Autentikasi non-interaktif (senyap) IWA dapat gagal jika MFA diaktifkan di penyewa Microsoft Entra dan tantangan MFA dikeluarkan oleh ID Microsoft Entra. Jika IWA gagal, Anda harus kembali ke metode autentikasi interaktif seperti yang dijelaskan sebelumnya.

MICROSOFT Entra ID menggunakan AI untuk menentukan kapan autentikasi dua faktor diperlukan. Autentikasi dua faktor biasanya diperlukan ketika pengguna masuk dari negara/wilayah yang berbeda, ketika terhubung ke jaringan perusahaan tanpa menggunakan VPN, dan terkadang ketika mereka terhubung melalui VPN. Karena konfigurasi dan frekuensi tantangan MFA mungkin berada di luar kendali Anda sebagai pengembang, aplikasi Anda harus dengan anggun menangani kegagalan akuisisi token senyap IWA.

Batasan URI otoritas

Otoritas yang disahkan saat membangun aplikasi klien publik harus salah satu dari:

  • https://login.microsoftonline.com/{tenant}/ - Otoritas ini menunjukkan aplikasi penyewa tunggal yang audiens masuknya dibatasi untuk pengguna di penyewa Microsoft Entra yang ditentukan. Nilai {tenant} dapat berupa ID penyewa dalam formulir GUID atau nama domain yang terkait dengan penyewa tersebut.
  • https://login.microsoftonline.com/organizations/ - Otoritas ini menunjukkan aplikasi multi-penyewa yang audiens masuknya adalah pengguna di penyewa Microsoft Entra mana pun.

Nilai otoritas TIDAK boleh berisi /common atau /consumers karena akun Microsoft pribadi (MSA) tidak didukung oleh IWA.

Persyaratan persetujuan

Karena IWA merupakan alur senyap:

  • Pengguna aplikasi Anda sebelumnya harus setuju untuk menggunakan aplikasi.

    ATAU

  • Admin penyewa sebelumnya harus telah menyetujui semua pengguna dalam penyewa untuk menggunakan aplikasi.

Untuk memenuhi salah satu persyaratan, salah satu operasi ini harus sudah diselesaikan:

  • Anda sebagai pengembang aplikasi telah memilih Berikan di portal Microsoft Azure untuk Anda sendiri.
  • Admin penyewa telah memilih Berikan/cabut izin admin untuk {tenant domain} pada tab Izin API dari pendaftaran aplikasi di portal Microsoft Azure; lihat Menambahkan izin untuk mengakses API web Anda.
  • Anda menyediakan cara bagi pengguna untuk menyetujui aplikasi; lihat Persetujuan pengguna.
  • Anda menyediakan cara bagi admin penyewa untuk menyetujui aplikasi; lihat Persetujuan administrator.

Untuk informasi selengkapnya mengenai persetujuan, lihat Izin dan persetujuan.

Langkah selanjutnya

Pelajari tentang memperoleh dan menyimpan cache token yang digunakan dalam alur ini:

Memperoleh dan meng-cache-kan token menggunakan Microsoft Authentication Library (MSAL)