Platform identitas Microsoft dan alur pemberian otorisasi perangkat OAuth 2.0
platform identitas Microsoft mendukung pemberian otorisasi perangkat, yang memungkinkan pengguna untuk masuk ke perangkat yang dibatasi input seperti TV pintar, perangkat IoT, atau printer. Untuk mengaktifkan alur ini, perangkat membuat pengguna mengunjungi halaman web di browser di perangkat lain untuk masuk. Setelah pengguna masuk, perangkat dapat mendapatkan token akses dan menyegarkan token sesuai kebutuhan.
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. Anda dapat merujuk ke aplikasi sampel yang menggunakan MSAL misalnya.
Diagram protokol
Seluruh alur kode perangkat ditampilkan dalam diagram berikut. Setiap langkah dijelaskan di seluruh artikel ini.
Permintaan otorisasi perangkat
Klien harus terlebih dahulu memeriksa dengan server autentikasi untuk perangkat dan kode pengguna yang digunakan untuk memulai autentikasi. Klien mengumpulkan permintaan ini dari titik akhir /devicecode. Dalam permintaan, klien juga harus menyertakan izin yang perlu diperoleh dari pengguna.
Sejak permintaan dikirim, pengguna memiliki waktu 15 menit untuk masuk. Ini adalah nilai default untuk expires_in. Permintaan hanya boleh dibuat ketika pengguna menunjukkan bahwa mereka siap untuk masuk.
// Line breaks are for legibility only.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=user.read%20openid%20profile
| Parameter | Kondisi | Deskripsi |
|---|---|---|
tenant |
Wajib diisi | Bisa /common, /consumers, atau /organizations. Ini juga bisa menjadi penyewa direktori yang ingin Anda mintai izinnya dari GUID atau format nama yang ramah. |
client_id |
Diperlukan | ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – pengalaman Pendaftaran aplikasi ke aplikasi Anda. |
scope |
Diperlukan | Daftar lingkup yang dipisahkan cakupan yang membutuhkan persetujuan. |
Respons otorisasi perangkat
Respons yang berhasil adalah objek JSON yang berisi informasi yang diperlukan untuk memungkinkan pengguna masuk.
| Parameter | Format | Deskripsi |
|---|---|---|
device_code |
String | Untai panjang digunakan untuk memverifikasi sesi antara klien dan server otorisasi. Klien menggunakan parameter ini untuk meminta token akses dari server otorisasi. |
user_code |
String | String pendek yang ditunjukkan kepada pengguna yang digunakan untuk mengidentifikasi sesi pada perangkat sekunder. |
verification_uri |
URI | URI yang harus di kunjungi pengguna dengan user_code untuk dapat masuk. |
expires_in |
int | Jumlah detik sebelum device_code dan user_code kedaluwarsa. |
interval |
int | Jumlah detik di mana klien harus menunggu di antara permintaan polling. |
message |
String | Untai yang dapat dibaca manusia dengan petunjuk untuk pengguna. Ini dapat dilokalkan dengan menyertakan parameter kueri dalam permintaan formulir ?mkt=xx-XX, mengisi kode budaya bahasa yang sesuai. |
Catatan
Bidang respons verification_uri_complete tidak disertakan atau didukung pada saat ini. Kami menyebutkan ini karena jika Anda membaca standar, Anda melihat bahwa verification_uri_complete terdaftar sebagai bagian opsional dari standar alur kode perangkat.
Mengautentikasi pengguna
Setelah klien menerima user_code dan verification_uri, nilai ditampilkan dan pengguna diarahkan untuk masuk melalui browser seluler atau PC mereka.
Jika pengguna mengautentikasi dengan akun pribadi, menggunakan /common atau /consumers, mereka diminta untuk masuk lagi untuk mentransfer status autentikasi ke perangkat. Ini karena perangkat tidak dapat mengakses cookie pengguna. Mereka diminta untuk menyetujui izin yang diminta oleh klien. Namun, ini tidak berlaku untuk akun kerja atau sekolah yang digunakan untuk mengautentikasi.
Sementara pengguna mengautentikasi di verification_uri, klien seharusnya mem-polling titik akhir /token untuk token yang diminta menggunakan device_code.
POST https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=535fb089-9ff3-47b6-9bfb-4f1264799865&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
| Parameter | Diperlukan | Deskripsi |
|---|---|---|
tenant |
Wajib diisi | Penyewa atau alias penyewa yang sama digunakan dalam permintaan awal. |
grant_type |
Diperlukan | Harus berupa urn:ietf:params:oauth:grant-type:device_code |
client_id |
Diperlukan | Harus cocok dengan client_id yang digunakan dalam permintaan awal. |
device_code |
Diperlukan | device_code dikembalikan dalam permintaan otorisasi perangkat. |
Kesalahan yang diharapkan
Alur kode perangkat adalah protokol polling sehingga kesalahan yang dilayani kepada klien harus diharapkan sebelum penyelesaian autentikasi pengguna.
| Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|
authorization_pending |
Pengguna belum selesai mengautentikasi, tetapi belum membatalkan alur. | Ulangi permintaan setelah setidaknya interval detik. |
authorization_declined |
Pengguna akhir menolak permintaan otorisasi. | Hentikan polling dan kembali ke keadaan tidak terautentikasi. |
bad_verification_code |
device_code yang dikirim ke titik akhir /token tidak dikenali. |
Verifikasi bahwa klien mengirimkan device_code yang benar dalam permintaan. |
expired_token |
expires_in Nilai telah terlampaui dan autentikasi tidak lagi dimungkinkan dengan device_code. |
Hentikan polling dan kembali ke keadaan tidak terautentikasi. |
Respons autentikasi berhasil
Respons token yang sukses terlihat seperti:
{
"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 Bearer. |
scope |
Untai yang dipisahkan spasi | Jika token akses dikembalikan, ini mencantumkan cakupan tempat token akses valid. |
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 didokumentasikan 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.