Alur autentikasi yang didukung di MSAL

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

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.

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 senyap, aplikasi mencoba mendapatkan token dengan menggunakan metode di mana server otorisasi mungkin tidak meminta input kepada pengguna.

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 sebelumnya, aplikasi:

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

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 satu kali.

  Jika Anda mencoba memperoleh token akses beberapa kali dengan kode otorisasi yang sama, kesalahan yang mirip dengan yang berikut ini 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 (S2S) yang harus berjalan di latar belakang, tanpa interaksi langsung dari pengguna. Jenis aplikasi ini sering disebut sebagai daemon atau 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 sebelumnya, aplikasi:

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

Sertifikat

Dalam diagram sebelumnya, aplikasi:

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

Jenis kredensial klien ini harus:

• 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 Platform Windows Universal (UWP). Aplikasi seluler dianggap sebagai aplikasi klien publik yang tidak mampu menjamin kerahasiaan rahasia autentikasi.

Kode perangkat

Alur kode perangkat OAuth 2 memungkinkan pengguna untuk masuk ke perangkat yang dibatasi input seperti TV pintar, perangkat Internet of Things (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 kemungkinan penggunaan 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.

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 melalui pengalaman autentikasi normal termasuk permintaan persetujuan dan autentikasi multifaktor, jika perlu.
2. Setelah autentikasi berhasil, aplikasi yang meminta menerima token yang diperlukan dari platform identitas Microsoft dan menggunakannya untuk melakukan panggilan API web yang dibutuhkannya.

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:
  • Berbasis penyewa: https://login.microsoftonline.com/{tenant}/, di mana {tenant} GUID mewakili ID penyewa atau nama domain yang terkait dengan penyewa.
  • 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).

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 memerlukan kemampuan tambahan untuk interaksi dengan platform desktop dan seluler asli tempat mereka berjalan.

Token yang dikeluarkan melalui mode alur implisit memiliki batasan panjang karena dikembalikan ke browser di URL (di mana 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 digunakan saat aplikasi memanggil layanan atau API web yang pada gilirannya perlu memanggil layanan atau API web lain menggunakan identitas dan izin pengguna yang didelegasikan yang perlu disebarluaskan melalui rantai permintaan. Agar layanan tingkat menengah membuat permintaan terautentikasi ke layanan hilir, layanan perlu mengamankan token akses dari platform identitas Microsoft atas nama pengguna yang meminta.

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

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 menemukan ROPC berguna, tetapi Anda harus menghindarinya dalam aplikasi apa pun di mana Anda menyediakan UI interaktif untuk masuk pengguna.

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 diam-diam pada komputer yang bergabung dengan domain Windows, sebaiknya gunakan Web Account Manager (WAM) alih-alih 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.
• ROPC tidak didukung dalam aplikasi Universal Windows Platform (UWP).
• ROPC di MICROSOFT Entra External ID hanya didukung untuk akun lokal.
  • Untuk informasi tentang ROPC di MSAL.NET dan ID Eksternal Microsoft Entra, lihat Info Masuk Kata Sandi Pemilik Sumber Daya (ROPC) Dengan B2C.

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 ID. Menggunakan IWA, aplikasi ini memperoleh token secara senyap tanpa memerlukan interaksi antarmuka pengguna oleh pengguna.

Dalam diagram sebelumnya, aplikasi:

1. Memperoleh token dengan menggunakan Integrated Windows Authentication.
2. Menggunakan token untuk membuat permintaan sumber daya.

Batasan untuk IWA

• Kompatibilitas. Autentikasi Windows terintegrasi (IWA) diaktifkan untuk aplikasi .NET desktop, .NET, dan Platform Windows Universal (UWP). IWA hanya mendukung pengguna federasi ADFS - 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 IWA (senyap) dapat gagal jika MFA diaktifkan di penyewa ID 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 MFA dan frekuensi tantangan mungkin berada di luar kendali Anda sebagai pengembang, aplikasi Anda harus menangani kegagalan akuisisi token senyap IWA dengan lancar.
• Pembatasan URI otoritas. Otoritas yang diteruskan 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 ID 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 ID Microsoft Entra mana pun.
• Akun pribadi. Nilai otoritas tidak boleh berisi /common atau /consumers karena akun Microsoft pribadi (MSA) tidak didukung oleh IWA.
• Persyaratan persetujuan. Karena IWA adalah alur senyap, pengguna aplikasi Anda sebelumnya harus menyetujui untuk menggunakan aplikasi atau admin penyewa sebelumnya harus telah menyetujui semua pengguna di penyewa untuk menggunakan aplikasi. Untuk memenuhi salah satu persyaratan, salah satu operasi ini harus telah diselesaikan:
  • Anda sebagai pengembang aplikasi telah memilih Grant 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 Gambaran umum izin dan persetujuan di platform identitas Microsoft.
  • Anda telah menyediakan cara bagi admin penyewa untuk menyetujui aplikasi; lihat Gambaran umum izin dan persetujuan di platform identitas Microsoft.

Langkah berikutnya

Sekarang setelah Anda meninjau alur autentikasi yang didukung oleh MSAL, pelajari tentang memperoleh dan menyimpan cache token yang digunakan dalam alur ini.