Platform identitas Microsoft dan alur pemberian otorisasi perangkat OAuth 2.0

2025-04-02

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 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. 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.

Aliran kode perangkat

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

Pengaturan	Keadaan	Deskripsi
`tenant`	Diperlukan	Bisa `/common`, `/consumers`, atau `/organizations`. Ini juga bisa menjadi penyewa direktori yang ingin Anda minta izinnya dalam format GUID atau nama yang mudah diingat.
`client_id`	Diperlukan	ID Aplikasi (klien) yang ditetapkan oleh pusat admin Microsoft Entra – Pendaftaran Aplikasi kepada aplikasi Anda.
`scope`	Diperlukan	Daftar lingkup yang dipisahkan dengan spasi yang Anda ingin pengguna setujui.

Respons otorisasi perangkat

Respons yang berhasil adalah objek JSON yang berisi informasi yang diperlukan untuk memungkinkan pengguna masuk.

Pengaturan	Rancangan	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 (Uniform Resource Identifier)	URI yang harus digunakan pengguna untuk `user_code` masuk.
`expires_in`	Integer	Jumlah detik sebelum dan `device_code` kedaluwarsa`user_code`.
`interval`	Integer	Jumlah detik di mana klien harus menunggu di antara permintaan polling.
`message`	string	teks yang dapat dibaca oleh manusia berisi instruksi untuk pengguna. Ini dapat dilokalkan dengan menyertakan parameter kueri dalam permintaan formulir `?mkt=xx-XX`, mengisi kode budaya bahasa yang sesuai.

Nota

Bidang verification_uri_complete respons tidak disertakan atau didukung saat ini. Kami menyebutkan ini karena jika Anda membaca standar yang Anda lihat yang verification_uri_complete tercantum 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.

Saat pengguna mengautentikasi di verification_uri, klien harus melakukan polling /token titik akhir 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=00001111-aaaa-2222-bbbb-3333cccc4444&device_code=GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8...

Pengaturan	Diperlukan	Deskripsi
`tenant`	Diperlukan	Alias penyewa atau penyewa yang sama yang digunakan dalam permintaan awal.
`grant_type`	Diperlukan	Harus berupa `urn:ietf:params:oauth:grant-type:device_code`
`client_id`	Diperlukan	Harus cocok dengan yang `client_id` digunakan dalam permintaan awal.
`device_code`	Diperlukan	yang `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 status yang tidak diatentikasi.
`bad_verification_code`	Yang `device_code` dikirim ke `/token` titik akhir tidak dikenali.	Verifikasi bahwa klien mengirim yang benar `device_code` dalam permintaan.
`expired_token`	`expires_in` Nilai telah terlampaui dan autentikasi tidak lagi dimungkinkan dengan `device_code`.	Hentikan polling dan kembali ke status yang tidak diatentikasi.

Respons autentikasi berhasil

Respon token yang berhasil tampak seperti:

{
    "token_type": "Bearer",
    "scope": "User.Read profile openid email",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}

Pengaturan	Rancangan	Deskripsi
`token_type`	string	Selalu `Bearer`.
`scope`	String yang dipisahkan oleh spasi	Jika token akses dikembalikan, ini mencantumkan cakupan tempat token akses valid.
`expires_in`	Integer	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 jelas	Dikeluarkan jika parameter asli `scope` menyertakan `offline_access`.

Anda dapat menggunakan token refresh untuk memperoleh token akses baru dan menyegarkan token menggunakan alur yang sama yang didokumenkan 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 ambil ketergantungan terhadapnya dalam kode Anda atau berasumsi tentang spesifikasi token yang bukan untuk API yang Anda kendalikan.

Bagikan melalui