Platform identitas Microsoft dan alur kode otorisasi OAuth 2.0
Jenis pemberian kode otorisasi OAuth 2.0, atau alur kode autentikasi, memungkinkan aplikasi klien mendapatkan akses resmi ke sumber daya yang dilindungi seperti API web. Alur kode autentikasi memerlukan agen pengguna yang mendukung pengalihan dari server otorisasi (platform identitas Microsoft) kembali ke aplikasi Anda. Misalnya, browser web, desktop, atau aplikasi seluler yang dioperasikan oleh pengguna untuk masuk ke aplikasi Anda dan mengakses data mereka.
Artikel ini menjelaskan detail protokol tingkat rendah yang diperlukan hanya ketika membuat dan mengeluarkan permintaan HTTP mentah secara manual untuk menjalankan alur, yang tidak kami rekomendasikan. Sebagai gantinya, gunakan pustaka autentikasi yang dibuat dan didukung Microsoft untuk mendapatkan token keamanan dan memanggil API web yang dilindungi di aplikasi Anda.
Aplikasi yang mendukung alur kode auth
Gunakan alur kode autentikasi yang dipasangkan dengan Proof Key for Code Exchange (PKCE) dan OpenID Connect (OIDC) untuk mendapatkan token akses dan token ID dalam jenis aplikasi ini:
- Single-page web application (SPA)
- Aplikasi web standar (berbasis server)
- Aplikasi desktop dan seluler
Detail Protokol
Alur kode otorisasi OAuth 2.0 dijelaskan dalam bagian 4.1 dari spesifikasi OAuth 2.0. Aplikasi yang menggunakan alur kode otorisasi OAuth 2.0 memperoleh access_token untuk disertakan dalam permintaan ke sumber daya yang dilindungi oleh platform identitas Microsoft (biasanya API). Aplikasi juga dapat meminta ID baru dan token akses untuk entitas yang diautentikasi sebelumnya dengan menggunakan mekanisme refresh.
Diagram ini menunjukkan tampilan tingkat tinggi dari aliran autentikasi:
URI Pengalihan untuk aplikasi satu halaman (SPAs)
URI pengalihan untuk SPA yang menggunakan alur kode autentikasi memerlukan konfigurasi khusus.
- Tambahkan URI pengalihan yang mendukung alur kode autentikasi dengan PKCE dan berbagi sumber daya lintas asal (CORS): Ikuti langkah-langkah di URI Pengalihan: MSAL.js 2.0 dengan alur kode autentikasi.
- Memperbarui URI pengalihan: Atur URI
typepengalihan kespadengan menggunakan editor manifes aplikasi di pusat admin Microsoft Entra.
Jenis pengalihan spa kompatibel mundur dengan alur implisit. Aplikasi yang saat ini menggunakan alur implisit untuk mendapatkan token dapat berpindah ke jenis URI pengalihan spa tanpa masalah dan terus menggunakan alur implisit. Terlepas dari kompatibilitas mundur ini, kami sarankan Anda menggunakan alur kode autentikasi dengan PKCE untuk SPAs.
Jika Anda mencoba menggunakan alur kode otorisasi tanpa menyiapkan CORS untuk URI pengalihan, Anda akan melihat kesalahan ini di konsol:
access to XMLHttpRequest at 'https://login.microsoftonline.com/common/v2.0/oauth2/token' from origin 'yourApp.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
Kemudian, kunjungi pendaftaran aplikasi Anda dan perbarui URI pengalihan untuk aplikasi Anda menggunakan spayang sejenis.
Aplikasi tidak dapat menggunakan spa URI pengalihan dengan alur non-SPA, misalnya aplikasi asli atau alur kredensial klien. Untuk memastikan keamanan dan praktik terbaik, platform Identitas Microsoft akan menampilkan kesalahan jika Anda mencoba menggunakan spaURI pengalihan tanpa Origin header. Demikian pula, platform Identitas Microsoft juga mencegah penggunaan info masuk klien di semua alur dalam penyedia Originheader, untuk memastikan bahwa rahasia tidak digunakan dari dalam browser.
Meminta kode otorisasi
Alur kode otorisasi dimulai dengan klien mengarahkan pengguna ke titik akhir /authorize. Dalam contoh permintaan ini, klien meminta openidizin , , offline_accessdan https://graph.microsoft.com/mail.read dari pengguna.
Beberapa izin dibatasi admin, misalnya menulis data ke direktori organisasi dengan menggunakan Directory.ReadWrite.All. Jika aplikasi Anda meminta akses ke salah satu izin ini dari pengguna organisasi, pengguna menerima pesan kesalahan yang mengatakan bahwa mereka tidak berwenang untuk menyetujui izin aplikasi Anda. Untuk meminta akses ke cakupan yang dibatasi admin, Anda harus memintanya langsung dari Administrator Global. Untuk informasi selengkapnya, lihat Izin yang dibatasi admin.
Kecuali ditentukan sebaliknya, tidak ada nilai default untuk parameter opsional. Namun, terdapat perilaku default untuk permintaan yang menghilangkan parameter opsional. Perilaku default tersebut adalah masuk ke satu-satunya pengguna saat ini, menampilkan pemilih akun jika ada beberapa pengguna, atau menampilkan halaman masuk jika tidak ada pengguna yang masuk.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Parameter | Diperlukan/opsional | Deskripsi |
|---|---|---|
tenant |
wajib diisi | Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah common, organizations, consumers, dan pengidentifikasi penyewa. Untuk skenario tamu di mana Anda memasukkan pengguna dari satu penyewa ke penyewa lain, Anda harus memberikan pengidentifikasi penyewa untuk memasukkannya ke sumber daya penyewa. Untuk informasi selengkapnya, lihat Titik akhir. |
client_id |
wajib diisi | ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – pengalaman Pendaftaran aplikasi ke aplikasi Anda. |
response_type |
wajib diisi | Harus menyertakan code untuk aliran kode otorisasi. Juga dapat mencakup id_token atautoken jika menggunakan aliran hibrid. |
redirect_uri |
wajib diisi | Aplikasi redirect_uri Anda, di mana respon autentikasinya dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di pusat admin Microsoft Entra, kecuali harus dikodekan URL. Untuk aplikasi seluler asli, gunakan salah satu nilai yang disarankan: https://login.microsoftonline.com/common/oauth2/nativeclient untuk aplikasi yang menggunakan browser tersemat atau http://localhost untuk aplikasi yang menggunakan browser sistem. |
scope |
wajib diisi | Daftar lingkup yang dipisahkan cakupan yang membutuhkan persetujuan. Untuk /authorize bagian permintaan, parameter ini dapat mencakup beberapa sumber daya. Nilai ini memungkinkan aplikasi Anda mendapatkan persetujuan untuk beberapa API web yang ingin Anda hubungi. |
response_mode |
Disarankan | Menentukan bagaimana platform identitas harus mengembalikan token yang diminta ke aplikasi Anda. Nilai yang didukung: - query: Default saat meminta token akses. Sediakan kode sebagai parameter string kueri pada URI pengalihan Anda. Parameter query tidak didukung saat meminta token ID dengan menggunakan alur implisit. - fragment: Default saat meminta token ID dengan menggunakan aliran implisit. Juga didukung jika hanya meminta kode.- form_post: Jalankan POST yang berisi kode ke URI pengalihan Anda. Didukung saat meminta kode. |
state |
Disarankan | Nilai yang disertakan dalam permintaan yang juga dikembalikan dalam respons token. Ini bisa berupa untai (karakter) dari konten yang Anda inginkan. Nilai unik yang dihasilkan secara acak biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs. Nilai ini juga digunakan untuk mengodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi terjadi. Misalnya, itu bisa mengodekan halaman atau melihat keberadaan mereka. |
prompt |
opsional | Menunjukkan jenis interaksi pengguna yang diperlukan. Nilai yang valid adalah: login, none, consent, dan select_account.- prompt=login memaksa pengguna untuk memasukkan info masuk mereka pada permintaan itu, meniadakan akses menyeluruh.- prompt=none adalah sebaliknya. Klaim ini memastikan pengguna tidak disajikan dengan permintaan interaktif apa pun. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui akses menyeluruh, platform identitas Microsoft mengembalikan interaction_requiredkesalahan.- prompt=consent memicu dialog persetujuan OAuth setelah pengguna masuk, meminta pengguna untuk memberikan izin ke aplikasi.- prompt=select_account mengganggu akses menyeluruh yang memberikan pengalaman pemilihan akun yang mencantumkan semua akun baik dalam sesi atau akun yang diingat atau opsi untuk memilih menggunakan akun yang berbeda sama sekali. |
login_hint |
opsional | Anda dapat menggunakan parameter ini untuk mengisi bidang nama pengguna dan alamat email dari halaman masuk untuk pengguna. Aplikasi dapat menggunakan parameter ini selama aatentikasi ulang, setelah mengekstrak login_hint klaim opsional dari rincian masuk sebelumnya. |
domain_hint |
opsional | Jika disertakan, aplikasi akan melewati proses penemuan berbasis email yang dilalui pengguna di halaman masuk, jarak antar baris untuk pengalaman pengguna yang disederhanakan. Misalnya, mengirim mereka ke penyedia identitas federasi mereka. Aplikasi akan menggunakan parameter ini selama autentikasi ulang, dengan mengekstraksi tid dari proses masuk sebelumnya. |
code_challenge |
disarankan/diperlukan | Digunakan untuk mengamankan pemberian kode otorisasi melalui Proof Key for Code Exchange (PKCE). Diperlukan jika code_challenge_method disertakan. Untuk informasi selengkapnya, lihat PKCE RFC. Parameter saat ini direkomendasikan untuk semua jenis aplikasi - klien publik dan rahasia - dan diperlukan oleh platform identitas Microsoft untuk aplikasi halaman tunggal menggunakan alur kode otorisasi. |
code_challenge_method |
disarankan/diperlukan | Metode yang digunakan untuk mengodekan code_verifier untuk parameter code_challenge. Ini DIHARUSKAN S256, namun specnya memungkinkan penggunaanplain jika klien tidak mendapatkan dukungan SHA256. Jika dikecualikan, code_challenge diasumsikan sebagai teks biasa jika code_challenge disertakan. Platform identitas Microsoft mendukung plain dan S256. Untuk informasi selengkapnya, lihat PKCE RFC. Parameter ini diperlukan untuk aplikasi satu halaman yang menggunakan alur kode otorisasi. |
Pada titik ini, pengguna diminta untuk memasukkan info masuk mereka dan menyelesaikan autentikasi. Platform identitas Microsoft juga akan memastikan bahwa pengguna sudah menyetujui izin yang ditunjukkan dalam scope parameter kueri. Jika pengguna belum menyetujui izin tersebut, pengguna akan diminta untuk menyetujui izin yang diperlukan. Untuk informasi selengkapnya, lihat Izin dan persetujuan di platform identitas Microsoft.
Setelah pengguna mengautentikasi dan memberikan persetujuan, platform identitas Microsoft mengembalikan respons ke aplikasi Anda pada indikasi redirect_uri, menggunakan metode yang ditentukan dalam parameter response_mode.
Respons berhasil
Contoh ini menunjukkan respons keberhasilan menggunakan response_mode=query:
GET http://localhost?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parameter | Deskripsi |
|---|---|
code |
authorization_code yang diminta oleh aplikasi. Aplikasi dapat menggunakan kode otorisasi untuk meminta token akses untuk sumber daya target. Kode otorisasi berlangsung singkat. Biasanya, kode otorisasi kedaluwarsa setelah sekitar 10 menit. |
state |
Jika parameter state disertakan dalam permintaan, maka nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik. |
Anda juga dapat menerima token ID jika Anda memintanya dan mengaktifkan hibah implisit dalam pendaftaran aplikasi Anda. Perilaku ini terkadang merujuk pada bagaimana alur hibrid. Ini digunakan oleh kerangka kerja seperti ASP.NET.
Respons kesalahan
Respons kesalahan juga dapat dikirim ke redirect_uri sehingga aplikasi dapat menanganinya dengan tepat:
GET http://localhost?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. Bagian kesalahan ini disediakan sehingga aplikasi dapat bereaksi dengan tepat terhadap kesalahan, tetapi tidak menjelaskan secara mendalam mengapa terjadi kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi pengembang yang menyebabkan kesalahan autentikasi. Bagian kesalahan ini berisi sebagian besar informasi yang berguna tentang mengapa terjadi kesalahan. |
Kode galat untuk kesalahan titik akhir otorisasi
Tabel berikut menjelaskan kode galat yang dapat dikembalikan dalam parameter error respons kesalahan.
| Kode Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|
invalid_request |
Kesalahan protokol, seperti kehilangan parameter yang diperlukan. | Perbaiki dan kirim ulang permintaan. Ini adalah kesalahan pengembangan yang biasanya tertangkap selama pengujian awal. |
unauthorized_client |
Aplikasi klien tidak diizinkan untuk meminta kode otorisasi. | Kesalahan ini biasanya terjadi ketika aplikasi klien tidak terdaftar di ID Microsoft Entra atau tidak ditambahkan ke penyewa Microsoft Entra pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke ID Microsoft Entra. |
access_denied |
Pemilik sumber daya menolak persetujuan | Aplikasi klien dapat memberi tahu pengguna bahwa hal ini tidak dapat dilanjutkan kecuali pengguna menyetujui. |
unsupported_response_type |
Server perizinan tidak mendukung jenis respons dalam permintaan. | Perbaiki dan kirim ulang permintaan. Ini adalah kesalahan pengembangan yang biasanya tertangkap selama pengujian awal. Dalam aliran hibrid, sinyal kesalahan ini mengharuskan Anda mengaktifkan pengaturan pemberian implisit token ID pada pendaftaran aplikasi klien. |
server_error |
Server mengalami kesalahan tidak terduga. | Coba lagi permintaannya. Kesalahan ini dapat diakibatkan oleh kondisi sementara. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kesalahan sementara. |
temporarily_unavailable |
Server terlalu sibuk untuk menangani permintaan tersebut untuk sementara waktu. | Coba lagi permintaannya. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kondisi sementara. |
invalid_resource |
Sumber daya target tidak valid karena tidak ada, ID Microsoft Entra tidak dapat menemukannya, atau tidak dikonfigurasi dengan benar. | Kesalahan ini menunjukkan bahwa sumber daya, jika ada, belum dikonfigurasi pada penyewa. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke ID Microsoft Entra. |
login_required |
Terlalu banyak atau tidak ada pengguna yang ditemukan. | Klien meminta autentikasi senyap (prompt=none), tetapi pengguna tunggal tidak dapat ditemukan. Kesalahan ini mungkin berarti ada beberapa pengguna yang aktif dalam satu sesi, atau tidak ada pengguna. Kesalahan ini memperhitungkan akun penyewa yang dipilih. Misalnya, jika ada dua akun Microsoft Entra aktif dan satu akun Microsoft, dan consumers dipilih, autentikasi senyap berfungsi. |
interaction_required |
Permintaan ini memerlukan interaksi pengguna. | Langkah autentikasi lainnya atau persetujuan diperlukan. Coba lagi permintaan tanpa prompt=none. |
Meminta token ID atau aliran hibrid
Untuk mempelajari siapa pengguna sebelum menukarkan kode otorisasi, biasanya aplikasi juga meminta token ID saat mereka meminta kode otorisasi. Pendekatan ini disebut aliran hibrid karena mencampur OIDC dengan alur kode otorisasi OAuth2.
Alur hibrid umumnya digunakan dalam aplikasi web untuk merender halaman bagi pengguna tanpa memblokir penukaran kode, terutama ASP.NET. Aplikasi satu halaman dan aplikasi web tradisional mendapat manfaat dari berkurangnya latensi dalam model ini.
Aliran hibrid sama dengan aliran kode otorisasi yang dijelaskan sebelumnya namun dengan tiga tambahan. Semua penambahan ini diperlukan untuk meminta token ID: cakupan baru, response_type baru, dan parameter kueri noncebaru.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&response_type=code%20id_token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=fragment
&scope=openid%20offline_access%20https%3A%2F%2Fgraph.microsoft.com%2Fuser.read
&state=12345
&nonce=abcde
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256
| Parameter yang Diperbarui | Diperlukan/opsional | Deskripsi |
|---|---|---|
response_type |
wajib diisi | Penambahan id_token menunjukkan kepada server bahwa aplikasi ingin token ID dalam respons dari titik akhir /authorize. |
scope |
wajib diisi | Untuk token ID, parameter ini harus diperbarui untuk menyertakan cakupan token ID: openid dan opsional profile dan email. |
nonce |
wajib diisi | Nilai yang tercantum dalam permintaan, dibuat oleh aplikasi, yang disertakan dalam id_token yang dihasilkan sebagai klaim. Aplikasi kemudian dapat memverifikasi nilai ini untuk meminimalkan serangan replay token. Biasanya, nilainya adalah string acak dan unik yang dapat digunakan untuk mengidentifikasi asal permintaan. |
response_mode |
Disarankan | Menentukan metode yang akan digunakan untuk mengirim token yang dihasilkan kembali ke aplikasi Anda. Nilai default hanya query untuk kode otorisasi, tetapi fragment jika permintaan menyertakan seperti yang id_token response_type ditentukan dalam spesifikasi OpenID. Sebaiknya gunakan form_postaplikasi , terutama saat menggunakan http://localhost sebagai URI pengalihan. |
Penggunaan fragment sebagai mode respons menyebabkan masalah untuk aplikasi web yang membaca kode dari pengalihan. Browser tidak meneruskan fragmen ke server web. Dalam situasi ini, aplikasi harus menggunakan mode respons form_post untuk memastikan bahwa semua data dikirim ke server.
Respons berhasil
Contoh ini menunjukkan respons keberhasilan menggunakan response_mode=fragment:
GET https://login.microsoftonline.com/common/oauth2/nativeclient#
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&id_token=eYj...
&state=12345
| Parameter | Deskripsi |
|---|---|
code |
Kode otorisasi yang diminta aplikasi. Aplikasi dapat menggunakan kode otorisasi untuk meminta token akses untuk sumber daya target. Kode otorisasi memiliki masa berlaku pendek yang kedaluwarsa setelah sekitar 10 menit. |
id_token |
Token ID untuk pengguna, diterbitkan dengan menggunakan hibah implisit. Berisi c_hashklaim khusus yang merupakan hash codedari permintaan yang sama. |
state |
Jika parameter state disertakan dalam permintaan, maka nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik. |
Menukarkan kode untuk token akses
Semua klien rahasia memiliki pilihan untuk menggunakan rahasia klien atau kredensial sertifikat. Rahasia bersama simetris dihasilkan oleh platform identitas Microsoft. Kredensial sertifikat adalah kunci asimetris yang diunggah oleh pengembang. Untuk informasi selengkapnya, lihat Kredensial sertifikat autentikasi aplikasi platform identitas Microsoft.
Untuk keamanan terbaik, sebaiknya gunakan kredensial sertifikat. Klien publik, yang mencakup aplikasi asli dan aplikasi halaman tunggal, tidak boleh menggunakan rahasia atau sertifikat saat menukarkan kode otorisasi. Selalu pastikan bahwa URI pengalihan Anda menyertakan jenis aplikasi dan unik.
Meminta token akses dengan client_secret
Sekarang setelah Anda memperoleh authorization_code dan telah diberikan izin oleh pengguna, Anda dapat menukarkan code dengan access_token ke sumber daya. Tukarkan code dengan mengirimkan permintaan POST ke titik akhir /token :
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=11112222-bbbb-3333-cccc-4444dddd5555
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
| Parameter | Diperlukan/opsional | Deskripsi |
|---|---|---|
tenant |
wajib diisi | Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah common, organizations, consumers, dan pengidentifikasi penyewa. Untuk informasi selengkapnya, lihat Titik akhir. |
client_id |
wajib diisi | ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – halaman Pendaftaran aplikasi ke aplikasi Anda. |
scope |
opsional | Daftar cakupan yang dipisahkan spasi. Cakupan semua harus dari satu sumber daya, bersama dengan lingkup OIDC (profile, openid, email). Untuk informasi selengkapnya, lihat Izin dan persetujuan di platform identitas Microsoft. Parameter ini adalah ekstensi Microsoft untuk alur kode otorisasi, yang dimaksudkan untuk memungkinkan aplikasi mendeklarasikan sumber daya yang mereka inginkan untuk token selama penukaran token. |
code |
wajib diisi | authorization_code yang Anda peroleh di bagian pertama alur. |
redirect_uri |
wajib diisi | Nilai redirect_uri yang sama yang digunakan untuk memperoleh authorization_code. |
grant_type |
wajib diisi | Harus authorization_code untuk aliran kode otorisasi. |
code_verifier |
Disarankan | code_verifier yang sama yang digunakan untuk mendapatkan authorization_code. Diperlukan jika PKCE digunakan dalam permintaan pemberian kode otorisasi. Untuk informasi selengkapnya, lihat PKCE RFC. |
client_secret |
diperlukan untuk aplikasi web rahasia | Rahasia aplikasi yang Anda buat di portal pendaftaran aplikasi untuk aplikasi Anda. Jangan gunakan rahasia aplikasi di aplikasi asli atau aplikasi halaman tunggal karena client_secret tidak dapat disimpan dengan andal di perangkat atau halaman web. Hal ini diperlukan untuk aplikasi web dan API web, yang dapat menyimpan client_secret dengan aman di sisi server. Seperti semua parameter di sini, rahasia klien harus dikodekan sebagai URL sebelum dikirim. Langkah ini dilakukan oleh SDK. Untuk informasi selengkapnya tentang pengodean URI, lihat spesifikasi Sintaksos Umum URI. Pola autentikasi Dasar melainkan pemberian info masuk di header Otorisasi, per RFC 6749 juga didukung. |
Meminta token akses dengan kredensial sertifikat
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&code_verifier=ThisIsntRandomButItNeedsToBe43CharactersLong
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
| Parameter | Diperlukan/opsional | Deskripsi |
|---|---|---|
tenant |
wajib diisi | Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah common, organizations, consumers, dan pengidentifikasi penyewa. Untuk detail selengkapnya, lihat Titik akhir. |
client_id |
wajib diisi | ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – halaman Pendaftaran aplikasi ke aplikasi Anda. |
scope |
opsional | Daftar cakupan yang dipisahkan spasi. Cakupan semua harus dari satu sumber daya, bersama dengan lingkup OIDC (profile, openid, email). Untuk informasi selengkapnya, lihat izin, persetujuan, dan cakupan. Parameter ini adalah ekstensi Microsoft ke alur kode otorisasi. Ekstensi ini memungkinkan aplikasi untuk mendeklarasikan sumber daya yang mereka inginkan untuk token selama penukaran token. |
code |
wajib diisi | authorization_code yang Anda peroleh di bagian pertama alur. |
redirect_uri |
wajib diisi | Nilai redirect_uri yang sama yang digunakan untuk memperoleh authorization_code. |
grant_type |
wajib diisi | Harus authorization_code untuk aliran kode otorisasi. |
code_verifier |
Disarankan | code_verifier yang sama yang digunakan untuk mendapatkan authorization_code. Diperlukan jika PKCE digunakan dalam permintaan pemberian kode otorisasi. Untuk informasi selengkapnya, lihat PKCE RFC. |
client_assertion_type |
diperlukan untuk aplikasi web rahasia | Nilai harus disetel ke urn:ietf:params:oauth:client-assertion-type:jwt-bearer untuk menggunakan kredensial sertifikat. |
client_assertion |
diperlukan untuk aplikasi web rahasia | Pernyataan, token web JSON (JWT), bahwa Anda perlu membuat dan menandatangani sertifikat yang Anda daftarkan sebagai kredensial untuk aplikasi Anda. Baca kredensial sertifikat untuk mempelajari cara mendaftarkan sertifikat Anda dan format pernyataan. |
Parameter yang sama dengan permintaan oleh rahasia bersama kecuali bahwa parameter client_secret diganti dengan dua parameter: client_assertion_type dan client_assertion.
Respons berhasil
Contoh ini menunjukkan respons token yang berhasil:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Parameter | Deskripsi |
|---|---|
access_token |
Token akses yang diminta. Aplikasi dapat menggunakan token ini untuk mengautentikasi ke sumber daya yang aman, seperti API web. |
token_type |
Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung microsoft Entra ID adalah Bearer. |
expires_in |
Berapa lama token akses valid, dalam hitungan detik. |
scope |
Cakupan yang berlaku untuk access_token. Opsional. Parameter ini tidak standar dan, jika dihilangkan, token adalah untuk cakupan yang diminta pada bagian awal alur. |
refresh_token |
Token refresh OAuth 2.0. Aplikasi dapat menggunakan token ini untuk memperoleh token akses lain setelah token akses saat ini kedaluwarsa. Token refresh berumur panjang. Mereka dapat mempertahankan akses ke sumber daya untuk waktu yang lama. Untuk detail selengkapnya tentang menyegarkan token akses, lihat Segarkan token akses nanti di artikel ini. Catatan: Hanya disediakan jika offline_access ruang lingkup diminta. |
id_token |
Token web JSON. Aplikasi dapat mendekodekan segmen token ini untuk meminta informasi tentang pengguna yang masuk. Aplikasi dapat menyimpan nilai dan menampilkannya, dan klien rahasia dapat menggunakan token ini untuk otorisasi. Untuk informasi selengkapnya tentang id_tokens, lihat id_token reference. Catatan: Hanya disediakan jika openid ruang lingkup diminta. |
Respons kesalahan
Contoh ini adalah respons Kesalahan:
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi pengembang yang menyebabkan kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus STS yang dapat membantu dalam diagnostik. |
timestamp |
Waktu saat peristiwa itu terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Kode kesalahan untuk kesalahan titik akhir token
| Kode Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|
invalid_request |
Kesalahan protokol, seperti kehilangan parameter yang diperlukan. | Perbaiki permintaan atau pendaftaran aplikasi dan kirim ulang permintaan. |
invalid_grant |
Kode otorisasi atau verifier kode PKCE tidak valid atau telah kedaluwarsa. | Coba permintaan baru ke titik akhir /authorize dan verifikasi bahwa parameter code_verifier sudah benar. |
unauthorized_client |
Klien yang diautentikasi tidak berwenang untuk menggunakan jenis hibah otorisasi ini. | Kesalahan ini biasanya terjadi ketika aplikasi klien tidak terdaftar di ID Microsoft Entra atau tidak ditambahkan ke penyewa Microsoft Entra pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke ID Microsoft Entra. |
invalid_client |
Autentikasi klien gagal. | Informasi masuk klien tidak valid. Untuk memperbaikinya, Administrator Aplikasi memperbarui kredensial. |
unsupported_grant_type |
Server otorisasi tidak mendukung jenis pemberian otorisasi. | Ubah jenis hibah dalam permintaan. Jenis kesalahan ini hanya boleh terjadi selama pengembangan dan terdeteksi selama pengujian awal. |
invalid_resource |
Sumber daya target tidak valid karena tidak ada, ID Microsoft Entra tidak dapat menemukannya, atau tidak dikonfigurasi dengan benar. | Kode ini menunjukkan sumber daya, jika ada, belum dikonfigurasi di penyewa. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke ID Microsoft Entra. |
interaction_required |
Non-standar, karena spesifikasi OIDC meminta kode ini hanya pada titik akhir /authorize. Permintaan ini memerlukan interaksi pengguna. Misalnya, langkah autentikasi lain diperlukan. |
Coba lagi permintaan/authorize dengan cakupan yang sama. |
temporarily_unavailable |
Server terlalu sibuk untuk menangani permintaan tersebut untuk sementara waktu. | Coba lagi permintaan setelah penundaan kecil. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kondisi sementara. |
consent_required |
Permintaan ini memerlukan persetujuan pengguna. Kesalahan ini tidak standar. Biasanya hanya dikembalikan pada titik akhir /authorize per spesifikasi OIDC. Dikembalikan ketika parameter scope digunakan pada alur penukaran kode bahwa aplikasi klien tidak memiliki izin untuk meminta. |
Klien harus mengirim pengguna kembali ke titik akhir /authorize dengan cakupan yang benar untuk memicu persetujuan. |
invalid_scope |
Cakupan yang diminta oleh aplikasi tidak valid. | Perbarui nilai parameter scope dalam permintaan autentikasi ke nilai yang valid. |
Catatan
Aplikasi halaman tunggal mungkin menerima kesalahan invalid_request yang menunjukkan bahwa penukaran token lintas asal hanya diizinkan untuk jenis klien 'Aplikasi Halaman Tunggal'. Ini menunjukkan bahwa URI pengalihan yang digunakan untuk meminta token belum ditandai sebagai spa URI pengalihan. Tinjau langkah-langkah pendaftaran aplikasi tentang cara mengaktifkan alur ini.
Gunakan token akses
Sekarang setelah Anda berhasil memperoleh access_token, Anda dapat menggunakan token dalam permintaan ke API web dengan menyertakannya di Authorization header:
GET /v1.0/me/messages
Host: https://graph.microsoft.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Merefresh token akses
Token akses berumur pendek. Refresh mereka setelah kedaluwarsa untuk terus mengakses sumber daya. Anda dapat melakukannya dengan mengirimkan permintaan POST lain ke titik akhir /token. Berikan refresh_token sebagai ganti dari code. Token refresh berlaku untuk semua izin yang telah disetujui klien Anda. Misalnya, token penyegaran yang dikeluarkan atas permintaan scope=mail.read dapat digunakan untuk meminta token akses baru untuk scope=api://contoso.com/api/UseResource.
Token refresh untuk aplikasi web dan aplikasi asli tidak memiliki masa pakai yang ditentukan. Biasanya, masa pakai token refresh relatif panjang. Namun, dalam beberapa kasus, token refresh kedaluwarsa, dicabut, atau tidak memiliki hak istimewa yang memadai untuk tindakan yang diinginkan. Aplikasi Anda perlu mengantisipasi dan menangani kesalahan yang dikembalikan oleh titik akhir penerbitan token. Aplikasi halaman tunggal mendapatkan token dengan masa pakai 24 jam, membutuhkan autentikasi baru setiap hari. Tindakan ini dapat dilakukan secara diam-diam dalam iframe ketika cookie pihak ketiga diaktifkan. Tindakan ini harus dilakukan dalam bingkai tingkat atas, baik navigasi halaman penuh atau jendela pop-up, pada browser tanpa cookie pihak ketiga, seperti Safari.
Token refresh tidak dicabut saat digunakan untuk mendapatkan token akses baru. Anda diharapkan untuk membuang token refresh lama. Spesifikasi OAuth 2.0 mengatakan: "Server otorisasi DAPAT mengeluarkan token refresh baru, dalam hal ini klien HARUS membuang token refresh lama dan menggantinya dengan token refresh baru. Server otorisasi DAPAT mencabut token refresh lama setelah mengeluarkan token refresh baru kepada klien."
Penting
Untuk token refresh yang dikirim ke URI pengalihan yang terdaftar sebagai spa, token refresh akan kedaluwarsa setelah 24 jam. Token refresh tambahan yang diperoleh menggunakan token refresh awal membawa lebih dari waktu kedaluwarsa itu, sehingga aplikasi harus siap untuk menjalankan kembali alur kode otorisasi menggunakan autentikasi interaktif untuk mendapatkan token refresh baru setiap 24 jam. Pengguna tidak harus memasukkan kredensial mereka, dan biasanya bahkan tidak melihat pengalaman pengguna, hanya memuat ulang aplikasi Anda. Browser harus mengunjungi halaman login dalam bingkai tingkat atas untuk melihat sesi login. Hal ini disebabkan oleh fitur privasi pada browser yang memblokir cookie pihak ketiga.
// Line breaks for legibility only
POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2Fmail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=sampleCredentia1s // NOTE: Only required for web apps. This secret needs to be URL-Encoded
| Parameter | Jenis | Deskripsi |
|---|---|---|
tenant |
wajib diisi | Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah common, organizations, consumers, dan pengidentifikasi penyewa. Untuk informasi selengkapnya, lihat Titik akhir. |
client_id |
wajib diisi | ID Aplikasi (klien) yang ditetapkan pusat admin Microsoft Entra – pengalaman Pendaftaran aplikasi ke aplikasi Anda. |
grant_type |
wajib diisi | Harus refresh_token untuk kaki ini dari aliran kode otorisasi. |
scope |
opsional | Daftar cakupan yang dipisahkan spasi. Cakupan yang diminta di bagian ini harus setara dengan atau sebagian dari cakupan yang diminta di bagian permintaan authorization_code asli. Jika cakupan yang ditentukan dalam permintaan ini mencakup beberapa server sumber daya, maka platform identitas Microsoft akan mengembalikan token untuk sumber daya yang ditentukan dalam cakupan pertama. Untuk informasi selengkapnya, lihat Izin dan persetujuan di platform identitas Microsoft. |
refresh_token |
wajib diisi | refresh_token yang Anda peroleh di bagian kedua alur. |
client_secret |
diperlukan untuk aplikasi web | Rahasia aplikasi yang Anda buat di portal pendaftaran aplikasi untuk aplikasi Anda. Hal ini tidak boleh digunakan di aplikasi asli, karena client_secret tidak dapat disimpan dengan andal di perangkat. Hal ini diperlukan untuk aplikasi web dan API web, yang dapat menyimpan client_secret dengan aman di sisi server. Rahasia ini perlu dikodekan dengan URL. Untuk informasi selengkapnya, lihat spesifikasi URI Generic Syntax. |
Respons berhasil
Contoh ini menunjukkan respons token yang berhasil:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD..."
}
| Parameter | Deskripsi |
|---|---|
access_token |
Token akses yang diminta. Aplikasi dapat menggunakan token ini untuk mengautentikasi ke sumber daya yang aman, seperti API web. |
token_type |
Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung microsoft Entra ID adalah Pembawa. |
expires_in |
Berapa lama token akses valid, dalam hitungan detik. |
scope |
Cakupan yang berlaku untuk access_token. |
refresh_token |
Token refresh OAuth 2.0 baru. Ganti token refresh lama dengan token refresh yang baru diperoleh ini untuk memastikan token refresh Anda tetap berlaku selama mungkin. Catatan: Hanya disediakan jika offline_access ruang lingkup diminta. |
id_token |
JSON Web Token yang tidak ditandatangani. Aplikasi dapat mendekodekan segmen token ini untuk meminta informasi tentang pengguna yang masuk. Aplikasi dapat menyimpan nilai dan menampilkannya, tetapi tidak boleh bergantung padanya untuk batas otorisasi atau keamanan apa pun. Untuk informasi selengkapnya tentang id_token, lihat token ID platform identitas Microsoft. Catatan: Hanya disediakan jika openid ruang lingkup diminta. |
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.
Respons kesalahan
{
"error": "invalid_scope",
"error_description": "AADSTS70011: The provided value for the input parameter 'scope' is not valid. The scope https://foo.microsoft.com/mail.read is not valid.\r\nTrace ID: 0000aaaa-11bb-cccc-dd22-eeeeee333333\r\nCorrelation ID: aaaa0000-bb11-2222-33cc-444444dddddd\r\nTimestamp: 2016-01-09 02:02:12Z",
"error_codes": [
70011
],
"timestamp": "2016-01-09 02:02:12Z",
"trace_id": "0000aaaa-11bb-cccc-dd22-eeeeee333333",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd"
}
| Parameter | Deskripsi |
|---|---|
error |
Untai (karakter) kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan, dan bereaksi pada kesalahan. |
error_description |
Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi. |
error_codes |
Daftar kode kesalahan khusus STS yang dapat membantu dalam diagnostik. |
timestamp |
Waktu saat peristiwa itu terjadi. |
trace_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik. |
correlation_id |
Pengidentifikasi unik untuk permintaan yang dapat membantu dalam diagnostik lintas komponen. |
Untuk deskripsi kode kesalahan dan tindakan klien yang direkomendasikan, lihat Kode kesalahan untuk kesalahan titik akhir token.
Langkah berikutnya
- Buka sampel MSAL JS untuk memulai pengodean.
- Pelajari tentang skenario pertukaran token.