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

Try running this request in Postman
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.

Device code flow

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.