Platform identitas Microsoft dan Informasi masuk Kata Sandi Pemilik Sumber Daya OAuth 2.0

Artikel
04/08/2024

Platform identitas Microsoft mendukung pemberian Informasi masuk Kata Sandi Pemilik Sumber Daya (ROPC) OAuth 2.0, yang memungkinkan aplikasi untuk membawa masuk pengguna dengan langsung menangani kata sandinya. Artikel ini menjelaskan cara memprogram langsung terhadap protokol di aplikasi Anda. Jika memungkinkan, sebaiknya Anda menggunakan Pustaka Autentikasi Microsoft (MSAL) yang didukung, bukan untuk memperoleh token dan memanggil API web aman. Lihat juga sampel aplikasi yang menggunakan MSAL.

Peringatan

Microsoft menyarankan agar Anda tidak menggunakan alur ROPC. Dalam sebagian besar skenario, alternatif yang lebih aman tersedia dan direkomendasikan. Alur ini membutuhkan tingkat kepercayaan yang sangat tinggi dalam aplikasi, dan membawa risiko yang tidak ada dalam alur-alur lain. Anda seharusnya hanya menggunakan alur ini saat alur lain yang lebih aman tidak dapat digunakan.

Penting

platform identitas Microsoft hanya mendukung pemberian ROPC dalam penyewa Microsoft Entra, bukan akun pribadi. Ini berarti Anda harus menggunakan titik akhir khusus penyewa (https://login.microsoftonline.com/{TenantId_or_Name}) atau titik akhir organizations.
Akun pribadi yang diundang ke penyewa Microsoft Entra tidak dapat menggunakan alur ROPC.
Akun yang tidak memiliki kata sandi tidak dapat masuk dengan ROPC, yang berarti fitur seperti masuk dengan SMS, FIDO, dan aplikasi Authenticator tidak akan berfungsi dengan aliran itu. Jika aplikasi atau pengguna Anda memerlukan fitur ini, gunakan jenis pemberian izin selain ROPC.
Jika pengguna perlu menggunakan autentikasi multifaktor (MFA) untuk masuk ke aplikasi, mereka akan diblokir.
ROPC tidak didukung dalam skenario federasi identitas hibrid (misalnya, MICROSOFT Entra ID dan AD FS yang digunakan untuk mengautentikasi akun lokal). Jika pengguna halaman penuh dialihkan ke penyedia identitas lokal, Microsoft Entra ID tidak dapat menguji nama pengguna dan kata sandi terhadap penyedia identitas tersebut. Namun, autentikasi pass-through didukung dengan ROPC.
Pengecualian untuk skenario gabungan identitas hibrid adalah sebagai berikut: Kebijakan Home Realm Discovery dengan AllowCloudPasswordValidation yang diatur ke TRUE akan memungkinkan alur ROPC berfungsi untuk pengguna gabungan saat kata sandi lokal disinkronkan ke cloud. Untuk informasi lebih lanjut, lihat Mengaktifkan autentikasi ROPC langsung dari pengguna gabungan untuk aplikasi warisan.
Kata sandi dengan spasi kosong di depan atau di belakang tidak didukung oleh alur ROPC.

Diagram protokol

Diagram berikut menunjukkan alur ROPC.

Diagram showing the resource owner password credential flow

Permintaan otorisasi

Alur ROPC adalah permintaan tunggal: hal ini mengirimkan identifikasi klien dan kredensial pengguna ke IdP, lalu menerima token sebagai hasilnya. Klien harus meminta alamat email (UPN) dan kata sandi pengguna sebelum melakukannya. Segera setelah permintaan berhasil, klien seharusnya membuang dengan aman kredensial pengguna dari memori. Informasi masuk tidak pernah boleh disimpan.

// Line breaks and spaces are for legibility only.  This is a public client, so no secret is required.

POST {tenant}/oauth2/v2.0/token
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile%20offline_access
&username=MyUsername@myTenant.com
&password=SuperS3cret
&grant_type=password

Parameter	Kondisi	Deskripsi
`tenant`	Wajib diisi	Penyewa direktori yang ingin Anda log ke dalamnya. Penyewa dapat berada dalam format GUID atau nama yang sesuai. Namun, parameter ini tidak dapat diatur ke `common` atau `consumers`, tetapi mungkin dapat diatur ke `organizations`.
`client_id`	Diperlukan	ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra - halaman Pendaftaran aplikasi ke aplikasi Anda.
`grant_type`	Diperlukan	Harus diatur ke `password`.
`username`	Diperlukan	Masukkan alamat email pengguna.
`password`	Diperlukan	Kata sandi pengguna.
`scope`	Disarankan	Daftar cakupan, atau izin yang dipisah spasi, yang diperlukan aplikasi. Dalam alur interaktif, admin atau pengguna harus menyetujui cakupan ini sebelumnya.
`client_secret`	Terkadang diperlukan	Jika aplikasi Anda adalah klien publik, `client_secret` atau `client_assertion` tidak dapat disertakan. Jika aplikasi adalah klien rahasia, maka aplikasi harus disertakan.
`client_assertion`	Terkadang diperlukan	Bentuk yang berbeda dari `client_secret`, yang dihasilkan menggunakan sertifikat. Untuk informasi selengkapnya, lihat kredensial sertifikat.

Respons autentikasi berhasil

Contoh berikut menunjukkan pembaruan repositori yang berhasil:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Parameter	Format	Deskripsi
`token_type`	String	Selalu atur ke `Bearer`.
`scope`	Untai yang dipisahkan spasi	Jika token akses diberikan, parameter ini mencantumkan cakupan yang berlaku untuk token akses.
`expires_in`	int	Jumlah detik yang berlaku untuk token akses yang disertakan.
`access_token`	Untai buram	Diterbitkan untuk cakupan yang diminta.
`id_token`	JWT	Diterbitkan jika parameter `scope` asli menyertakan cakupan `openid`.
`refresh_token`	Untai buram	Diterbitkan jika parameter `scope` yang asli menyertakan `offline_access`.

Anda dapat menggunakan token refresh untuk memperoleh token akses dan refresh token baru yang menggunakan alur yang sama yang dijelaskan dalam dokumentasi alur Kode OAuth.

Peringatan

Jangan mencoba memvalidasi atau membaca token untuk API apa pun yang tidak Anda miliki, termasuk token dalam contoh ini, dalam kode Anda. Token untuk layanan Microsoft dapat menggunakan format khusus yang tidak akan divalidasi sebagai JWT, dan juga dapat dienkripsi untuk pengguna konsumen (akun Microsoft). Meskipun membaca token adalah alat penelusuran kesalahan dan pembelajaran yang berguna, jangan mengambil dependensi terhadapnya dalam kode Anda atau asumsikan hal-hal yang spesifik tentang token yang bukan untuk API yang Anda kontrol.

Respons kesalahan

Jika pengguna belum memberi nama pengguna atau kata sandi yang benar, atau klien belum menerima persetujuan yang diminta, autentikasi akan gagal.

Kesalahan	Deskripsi	Tindakan klien
`invalid_grant`	Autentikasi gagal	Informasi masuk salah atau klien tidak memiliki persetujuan untuk cakupan yang diminta. Jika cakupan tidak diberikan, kesalahan `consent_required` akan diberikan. Untuk menyelesaikannya, klien harus mengirim pengguna ke permintaan interaktif menggunakan webview atau browser.
`invalid_request`	Permintaan itu dibentuk secara tidak benar	Jenis pemberian ini tidak didukung pada konteks autentikasi `/common` atau `/consumers`. Gunakan `/organizations` atau ID penyewa sebagai gantinya.

Pelajari lebih lanjut

Untuk contoh implementasi alur ROPC, lihat sampel kode aplikasi konsol .NET di GitHub.