Dukungan alur autentikasi di MSAL

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

Aliran autentikasi Aktifkan Jenis aplikasi yang didukung
Kode otorisasi Proses masuk pengguna dan akses ke API web atas nama pengguna. * Desktop
* Seluler
* Aplikasi satu halaman (SPA) (memerlukan PKCE)
* Web
Kredensial 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 Azure Active Directory (Azure AD) bergabung dengan komputer untuk memperoleh token secara senyap (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 x x x x
Informasi masuk klien x (khusus aplikasi)
Alur kode perangkat x x x
Alur implisit x x
Alur atas nama token akses x x x
Nama pengguna/kata sandi (ROPC) nama pengguna, kata sandi x x x
Alur OIDC hibrid x x
Penukaran token refresh token refresh x x x

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 izin akses sumber daya yang lebih banyak.
  • Non-interaktif - Pengguna mungkin tidak diminta untuk input. 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.

Diagram of authorization code flow

Dalam diagram sebelumnya, aplikasi:

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

Batasan untuk kode otorisasi

  • Aplikasi satu halaman memerlukan Kunci Bukti untuk Penukaran Kode (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 satu kali.

    Jika Anda mencoba memperoleh token akses beberapa kali dengan kode otorisasi yang sama, kesalahan yang mirip dengan yang berikut dikembalikan oleh platform identitas Microsoft. Perlu diingat bahwa beberapa pustaka dan kerangka kerja meminta kode otorisasi untuk Anda secara otomatis, dan meminta kode secara manual dalam kasus serupa 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 informasi masuk klien OAuth 2 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 untuk menggunakan sertifikat (bukan rahasia bersama) sebagai informasi masuk.

Rahasia aplikasi

Diagram of confidential client with password

Dalam diagram sebelumnya, aplikasi:

  1. Memperoleh token menggunakan rahasia kata sandi atau informasi masuk rahasia.
  2. Menggunakan token untuk membuat permintaan sumber daya.

Sertifikat

Diagram of confidential client with cert

Dalam diagram sebelumnya, aplikasi:

  1. Mendapat token menggunakan informasi masuk sertifikat.
  2. Menggunakan token untuk membuat permintaan sumber daya.

Informasi masuk klien ini perlu:

  • Didaftarkan di Azure AD.
  • Diteruskan saat membangun 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

Aliran kode perangkat OAuth 2 memungkinkan pengguna untuk masuk ke perangkat yang dibatasi inputnya seperti smart TV, perangkat IoT, dan printer. Autentikasi interaktif dengan Azure AD 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).

Diagram of device code flow

Pada diagram sebelumnya:

  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 proses pengalaman autentikasi normal termasuk prompt 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.

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:
    • Disewa: https://login.microsoftonline.com/{tenant}/, di mana {tenant} adalah GUID yang mewakili ID penyewa atau nama domain yang terkait dengan penyewa tersebut.
    • Akun kantor dan sekolah: https://login.microsoftonline.com/organizations/.

Pemberian implisit

Pemberian implisit telah digantikan oleh alur kode otorisasi dengan PKCE sebagai alur pemberian token yang disukai dan lebih aman untuk aplikasi satu halaman sisi klien (SPA). 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 memungkinkan aplikasi untuk mendapat token akses dari platform identitas Microsoft tanpa melakukan pertukaran info masuk 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 of implicit grant flow

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 OAuth 2 atas nama digunakan saat aplikasi memanggil layanan atau API web yang pada gilirannya perlu memanggil layanan lain atau API web. 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.

Diagram of on-behalf-of flow

Pada diagram sebelumnya:

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

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

Informasi masuk pemilik sumber daya OAuth 2 (ROPC) memungkinkan aplikasi untuk memasukkan pengguna dengan secara 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.

Diagram of the username/password flow

Dalam diagram sebelumnya, aplikasi:

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

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 dalam aplikasi .NET desktop dan .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 tergabung domain atau tergabung Microsoft Azure AD. Menggunakan IWA, aplikasi ini memperoleh token secara senyap tanpa memerlukan interaksi antarmuka pengguna oleh pengguna.

Diagram of integrated Windows authentication

Dalam diagram sebelumnya, aplikasi:

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

Batasan untuk IWA

Kompatibilitas

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

IWA hanya mendukung pengguna federasi AD FS - pengguna yang dibuat di Active Directory dan didukung oleh Microsoft Azure AD. Pengguna yang dibuat langsung di Azure AD tanpa dukungan Active Directory (pengguna terkelola) tidak dapat menggunakan alur autentikasi ini.

Autentikasi multifaktor (MFA)

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

Microsoft Azure AD 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 dengan audiens masuk yang dibatasi untuk pengguna di penyewa Microsoft Azure AD 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 dengan audiens masuk yang merupakan pengguna di penyewa Microsoft Azure AD 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.

    OR

  • 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 telah menyediakan cara bagi pengguna untuk menyetujui aplikasi; lihat Meminta persetujuan pengguna individu.
  • Anda telah menyediakan cara bagi admin penyewa untuk menyetujui aplikasi; lihat persetujuan admin.

Untuk informasi selengkapnya mengenai persetujuan, lihat Izin dan persetujuan.

Langkah berikutnya

Setelah Anda meninjau alur autentikasi yang didukung oleh MSAL, pelajari pengambilan dan penembolokan token yang digunakan dalam alur berikut:

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