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, pengguna perangkat akan diarahkan untuk mengunjungi halaman web di browser mereka 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. Lihat juga contoh aplikasi yang menggunakan MSAL.
Tip
Coba jalankan permintaan ini dan banyak lagi di Postman - jangan lupa untuk mengganti token dan ID!
Diagram protokol
Seluruh alur kode perangkat terlihat mirip dengan diagram berikutnya. Kami menjelaskan masing-masing langkah dalam artikel ini nanti.
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 ini, klien juga harus menyertakan izin yang harus didapatkan dari pengguna. Dari saat permintaan ini dikirim, pengguna hanya memiliki 15 menit untuk masuk (nilai umum untuk expires_in), jadi hanya buat permintaan ini 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 menjadi /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 masuk menggunakan ponsel atau browser PC mereka.
Jika pengguna mengautentikasi dengan akun pribadi (pada /common atau /consumers), pengguna akan diminta masuk kembali untuk mentransfer status autentikasi ke perangkat. Pengguna juga akan dimintai persetujuan, untuk memastikan pengguna mengetahui izin yang diberikan. 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 klien Anda harus mengharapkan untuk menerima kesalahan sebelum pengguna selesai mengautentikasi.
| 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, lalu kembali ke status 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 |
Setidaknya expires_in beberapa detik sudah berlaku, dan autentikasi tidak lagi dimungkinkan menggunakan device_code ini. |
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 |
String | Selalu Bearer. |
scope |
Untai yang dipisahkan spasi | Jika token akses dikembalikan, ini mencantumkan cakupan yang berlaku untuk token akses. |
expires_in |
int | Jumlah detik sebelum token akses yang disertakan valid. |
access_token |
Untai 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.