Bagikan melalui

Platform Identitas Microsoft dan Kredensial Kata Sandi Pemilik Sumber Daya OAuth 2.0

  • Artikel

Platform identitas Microsoft mendukung pemberian OAuth 2.0 Resource Owner Password Credentials (ROPC), yang memungkinkan aplikasi untuk masuk ke dalam akun pengguna dengan langsung menangani kata sandi mereka. Artikel ini menjelaskan cara memprogram secara langsung terhadap protokol dalam aplikasi Anda. Jika memungkinkan, kami sarankan Anda menggunakan Microsoft Authentication Libraries (MSAL) yang didukung sebagai gantinya untuk memperoleh token dan memanggil API web aman. Lihat juga aplikasi sampel yang menggunakan MSAL.

Peringatan

Microsoft menyarankan Anda tidak menggunakan alur ROPC; alur ini tidak dapat digunakan dengan autentikasi multifaktor (MFA). Dalam kebanyakan 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 lain. Anda sebaiknya hanya menggunakan alur ini ketika alur yang lebih aman tidak memungkinkan.

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 tenant Microsoft Entra tidak dapat menggunakan alur ROPC.
  • Akun yang tidak memiliki kata sandi tidak dapat masuk dengan ROPC, yang berarti fitur seperti masuk SMS, FIDO, dan aplikasi Authenticator tidak akan berfungsi dengan alur tersebut. Jika aplikasi atau pengguna Anda memerlukan fitur ini, gunakan jenis hibah selain ROPC.
  • Jika pengguna perlu menggunakan autentikasi multifaktor (MFA) untuk masuk ke aplikasi, mereka akan diblokir sebagai gantinya.
  • ROPC tidak didukung dalam skenario federasi identitas hibrida (misalnya, Microsoft Entra ID dan AD FS yang digunakan untuk mengautentikasi akun lokal). Jika pengguna dialihkan secara penuh ke penyedia identitas on-premises, ID Microsoft Entra tidak dapat menguji nama pengguna dan kata sandi dengan penyedia identitas tersebut. Autentikasi pass-through didukung dengan ROPC.
  • Pengecualian untuk skenario federasi identitas hibrid adalah sebagai berikut: Kebijakan Home Realm Discovery dengan AllowCloudPasswordValidation diatur ke TRUE akan memungkinkan alur ROPC berfungsi untuk pengguna federasi saat kata sandi lokal disinkronkan ke cloud. Untuk informasi selengkapnya, lihat Mengaktifkan autentikasi ROPC langsung pengguna yang terfederasi untuk aplikasi lama.
  • Kata sandi dengan spasi kosong di depan atau di belakang tidak didukung oleh alur ROPC.

Cara bermigrasi jauh dari ROPC

Karena MFA menjadi lebih umum, beberapa API web Microsoft hanya akan menerima token akses jika mereka telah melewati persyaratan MFA. Aplikasi dan rig pengujian yang mengandalkan ROPC akan dikunci. Microsoft Entra tidak akan mengeluarkan token, atau sumber daya akan menolak permintaan.

Jika Anda menggunakan ROPC untuk memperoleh token untuk memanggil API hilir yang dilindungi, migrasikan ke strategi akuisisi token yang aman.

Saat konteks pengguna tersedia

Jika pengguna akhir perlu mengakses sumber daya, aplikasi klien yang bertindak atas nama mereka harus menggunakan bentuk autentikasi interaktif. Pengguna akhir hanya dapat ditantang untuk MFA ketika diminta di browser.

  • Untuk aplikasi web:
    • Jika otentikasi dilakukan pada bagian front-end, lihat Aplikasi Halaman Tunggal.
    • Jika autentikasi dilakukan di back-end, lihat aplikasi web .
  • API Web tidak dapat menampilkan browser. Sebaliknya, mereka harus mengembalikan tantangan kembali ke aplikasi klien. Untuk detailnya, lihat API Web dan tantangan pengguna dalam API Web.
  • Aplikasi desktop harus menggunakan autentikasi berbasis broker. Broker menggunakan autentikasi berbasis browser, sehingga mereka dapat memberlakukan MFA dan memastikan tingkat keamanan tertinggi.
  • Aplikasi seluler juga harus dikonfigurasi untuk menggunakan autentikasi berbasis broker (Authenticator, Company Portal).

Ketika konteks pengguna tidak tersedia

Contoh skenario di mana tidak ada konteks pengguna yang terlibat, tetapi tidak terbatas pada, berikut ini:

  • Skrip yang berjalan sebagai bagian dari alur CI.
  • Layanan yang perlu memanggil sumber daya atas nama dirinya sendiri, tanpa detail pengguna.

Pengembang aplikasi harus menggunakan autentikasi Perwakilan Layanan, yang diilustrasikan dalam sampel daemon . MFA tidak berlaku untuk Perwakilan Layanan.

Ada beberapa cara untuk mengautentikasi sebagai perwakilan layanan:

  • Jika aplikasi Anda berjalan di infrastruktur Azure, gunakan Managed Identity. Identitas Terkelola menghilangkan beban dalam pemeliharaan dan pergantian rahasia dan sertifikat.
  • Jika aplikasi Anda berjalan pada sistem yang dikelola oleh Penyedia Identitas lain yang mematuhi OAuth2, seperti GitHub, gunakan kredensial identitas federasi .
  • Jika Anda tidak dapat menggunakan Identitas Terkelola atau Identitas Federasi, gunakan kredensial sertifikat .

Peringatan

Jangan gunakan autentikasi Prinsipal Layanan ketika konteks pengguna tersedia. Akses khusus aplikasi secara inheren memiliki hak istimewa tinggi, sering kali memberikan akses ke seluruh penyewa dan berpotensi memungkinkan aktor jahat mengakses data pelanggan untuk setiap pengguna.

Diagram protokol

Diagram berikut menunjukkan alur ROPC.

Diagram memperlihatkan alur kredensial kata sandi pemilik sumber daya

Permintaan otorisasi

Alur ROPC adalah satu permintaan; ini mengirimkan identifikasi klien dan kredensial pengguna ke penyedia identitas, dan menerima token sebagai imbalannya. Klien harus meminta alamat email (UPN) dan kata sandi pengguna sebelum melakukannya. Segera setelah permintaan berhasil, klien harus membuang kredensial pengguna dengan aman dari memori. Ini tidak boleh menyelamatkan mereka.

// 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 Keadaan Deskripsi
tenant Diperlukan Penyewa akun direktori tempat Anda ingin pengguna masuk. Penyewa dapat dalam format GUID atau format nama yang ramah. Namun, parameternya tidak dapat diatur ke common atau consumers, tetapi dapat diatur ke organizations.
client_id Diperlukan ID Aplikasi (klien) yang ditetapkan oleh halaman pusat admin Microsoft Entra - Pendaftaran aplikasi ke aplikasi Anda.
grant_type Diperlukan Harus diatur ke password.
username Diperlukan Alamat email pengguna.
password Diperlukan Kata sandi pengguna.
scope Direkomendasikan Daftar cakupan atau izin yang dipisahkan oleh spasi, yang diperlukan oleh aplikasi. Dalam alur interaktif, admin atau pengguna harus menyetujui cakupan ini sebelumnya.
client_secret Terkadang diperlukan Jika aplikasi Anda adalah klien publik, maka client_secret atau client_assertion tidak dapat disertakan. Jika aplikasi adalah klien rahasia, maka aplikasi tersebut harus disertakan.
client_assertion Terkadang diperlukan Bentuk client_secretyang berbeda , dihasilkan menggunakan sertifikat. Untuk informasi selengkapnya, lihat kredensial sertifikat .

Respons autentikasi berhasil

Contoh berikut menunjukkan respons token 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 Tali Selalu setel ke Bearer.
scope String yang dipisahkan oleh spasi Jika token akses dikembalikan, parameter ini mencantumkan cakupan token akses yang valid.
expires_in Int Jumlah detik yang berlaku untuk token akses yang disertakan.
access_token String tidak jelas Dikeluarkan untuk cakupan yang diminta.
id_token JWT Dikeluarkan jika parameter scope asli menyertakan cakupan openid.
refresh_token String tidak transparan Dikeluarkan jika parameter asli scope menyertakan offline_access.

Anda dapat menggunakan token refresh untuk memperoleh token akses baru dan token refresh 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 bergantung pada ini dalam kode Anda atau berasumsi tentang spesifikasi token yang bukan untuk API yang Anda kelola.

Tanggapan kesalahan

Jika pengguna belum memberikan 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 Kredensial salah atau klien tidak memiliki persetujuan untuk cakupan yang diminta. Jika cakupan tidak diberikan izin, kesalahan consent_required akan dikembalikan. Untuk mengatasi kesalahan ini, klien harus mengirim pengguna ke perintah interaktif menggunakan webview atau browser.
invalid_request Permintaan tersebut dibuat secara tidak benar Jenis pemberian tidak didukung pada konteks autentikasi /common atau /consumers. Gunakan /organizations atau ID penyewa sebagai gantinya.

Pelajari lebih lanjut

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