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, kami sarankan Anda menggunakan Microsoft Authentication Libraries (MSAL) yang didukung alih-alih mendapatkan token dan memanggil API web aman. Anda dapat merujuk ke contoh aplikasi yang menggunakan MSAL misalnya.
Tip
Coba jalankan permintaan ini dan banyak lagi di Postman - jangan lupa untuk mengganti token dan ID!
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 telah 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=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20openid%20profile
| Parameter | Kondisi | Deskripsi |
|---|---|---|
tenant |
Diperlukan | 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 pengalaman portal Microsoft Azure – 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 |
Untai | Untai panjang digunakan untuk memverifikasi sesi antara klien dan server otorisasi. Klien menggunakan parameter ini untuk meminta token akses dari server otorisasi. |
user_code |
Untai | Untai pendek 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 |
Untai | 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 menerima user_code dan verification_uri, klien menampilkan ini kepada pengguna, menginstruksikan mereka untuk menggunakan ponsel atau browser PC mereka untuk masuk.
Jika pengguna mengautentikasi dengan akun pribadi, menggunakan /common atau /consumers, mereka akan diminta untuk masuk lagi untuk mentransfer status autentikasi ke perangkat. Ini karena perangkat tidak dapat mengakses cookie pengguna. Mereka juga akan diminta untuk menyetujui izin yang diminta oleh klien. Namun, ini tidak berlaku untuk akun kantor 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=6731de76-14a6-49ae-97bc-6eba6914391e&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...
| Parameter | Diperlukan | Deskripsi |
|---|---|---|
tenant |
Diperlukan | 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 menyelesaikan 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 berhasil akan 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 |
Untai | Selalu Bearer. |
scope |
String yang dipisah spasi | Jika token akses dikembalikan, ini mencantumkan cakupan tempat token akses valid. |
expires_in |
int | Jumlah detik token akses yang disertakan berlaku untuk. |
access_token |
String buram | Diterbitkan untuk cakupan yang diminta. |
id_token |
JWT | Diterbitkan jika parameter scope asli menyertakan cakupan openid. |
refresh_token |
String 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.