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 biasanya hanya diperlukan saat 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:

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.

Tip

Coba jalankan permintaan ini di Postman
Coba jalankan permintaan ini dan banyak lagi di Postman - jangan lupa untuk mengganti token dan ID!

Diagram ini menunjukkan tampilan tingkat tinggi dari aliran autentikasi:

Diagram menunjukkan aliran kode otorisasi OAuth. Aplikasi asli dan Web A P Saya berinteraksi dengan menggunakan token seperti yang dijelaskan dalam artikel ini.

URI pengalihan untuk single-page apps (SPAs)

URI pengalihan untuk SPA yang menggunakan alur kode autentikasi memerlukan konfigurasi khusus.

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.

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 permintaan ini, klien meminta izin openid, offline_access, dan 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=6731de76-14a6-49ae-97bc-6eba6914391e
&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

Tip

Klik tautan di bawah ini untuk menjalankan permintaan ini! Setelah masuk, browser Anda harus dialihkan ke http://localhost/myapp/ dengan code di bilah alamat. https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

Parameter Diperlukan/opsional Deskripsi
tenant diperlukan 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 diperlukan ID Aplikasi (klien) yang ditetapkan pengalaman portal Microsoft Azure – Pendaftaran aplikasi ke aplikasi Anda.
response_type diperlukan Harus menyertakan code untuk aliran kode otorisasi. Juga dapat mencakup id_token atautoken jika menggunakan aliran hibrid.
redirect_uri diperlukan Aplikasi redirect_uri Anda, di mana respon autentikasinya dapat dikirim dan diterima oleh aplikasi Anda. Hal ini harus sama persis dengan salah satu URI pengalihan yang Anda daftarkan di portal, kecuali jika 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 diperlukan 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 menggunakan aliran 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 autentikasi ulang, setelah mengekstrak login_hintklaim opsional dari proses 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 DIHARUSKANS256, 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, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons sama persis.

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 Microsoft Azure Active Directory atau tidak ditambahkan ke penyewa Microsoft Azure Active Directory pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure Active Directory.
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, Microsoft Azure Active Directory 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 Microsoft Azure Active Directory.
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 Azure AD 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 menggabungkan pemberian implisit dengan aliran kode otorisasi.

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=6731de76-14a6-49ae-97bc-6eba6914391e
&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 diperlukan Penambahan id_token menunjukkan kepada server bahwa aplikasi ingin token ID dalam respons dari titik akhir /authorize.
scope diperlukan Untuk token ID, parameter ini harus diperbarui untuk menyertakan cakupan token ID: openid dan opsional profile dan email.
nonce diperlukan Nilai yang tercantum dalam permintaan, dibuat oleh aplikasi, yang disertakan dalam id_token yang dihasilkan sebagai klaim. Aplikasi kemudian dapat memverifikasi nilai ini untuk mengurangi serangan pemutaran ulang token. Secara umum, nilainya adalah untai (karakter) acak dan unik yang dapat digunakan untuk mengidentifikasi asal permintaan.
response_mode disarankan Menentukan metode yang harus digunakan untuk menghasilkan hasil token ke aplikasi Anda. Nilai default query hanya untuk kode otorisasi, tetapi fragment jika permintaan menyertakan id_tokenresponse_type seperti yang ditentukan dalam spesifikasi OpenID. Sebaiknya aplikasi menggunakan form_post, 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, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons sama persis.

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=6731de76-14a6-49ae-97bc-6eba6914391e
&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=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps. This secret needs to be URL-Encoded.
Parameter Diperlukan/opsional Deskripsi
tenant diperlukan 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 diperlukan ID Aplikasi (klien) yang ditetapkan oleh halaman Portal Azure – Pendaftaran aplikasi untuk 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 diperlukan authorization_code yang Anda peroleh di bagian pertama alur.
redirect_uri diperlukan Nilai redirect_uri yang sama yang digunakan untuk memperoleh authorization_code.
grant_type diperlukan 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 biasanya 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

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&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 diperlukan 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 diperlukan ID Aplikasi (klien) yang ditetapkan oleh halaman Portal Azure – Pendaftaran aplikasi untuk 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 diperlukan authorization_code yang Anda peroleh di bagian pertama alur.
redirect_uri diperlukan Nilai redirect_uri yang sama yang digunakan untuk memperoleh authorization_code.
grant_type diperlukan 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. Untuk mempelajari cara mendaftarkan sertifikat Anda dan format pernyataan, lihat kredensial sertifikat.

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 Azure AD 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 cakupan offline_access 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 cakupan openid 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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 Microsoft Azure Active Directory atau tidak ditambahkan ke penyewa Microsoft Azure Active Directory pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure Active Directory.
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, Azure AD 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 Microsoft Azure Active Directory.
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

Setelah berhasil memperoleh token aksesaccess_token, Anda dapat menggunakan token dalam permintaan ke API web ujung-belakang Anda dengan menyertakannya di header Authorization :

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=535fb089-9ff3-47b6-9bfb-4f1264799865
&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 diperlukan 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 diperlukan ID Aplikasi (klien) yang ditetapkan pengalaman portal Microsoft Azure – Pendaftaran aplikasi ke aplikasi Anda.
grant_type diperlukan 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 diperlukan 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 AAD adalah Token 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 cakupan offline_access 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 cakupan openid 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: 255d1aef-8c98-452f-ac51-23d051240864\r\nCorrelation ID: fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7\r\nTimestamp: 2016-01-09 02:02:12Z",
  "error_codes": [
    70011
  ],
  "timestamp": "2016-01-09 02:02:12Z",
  "trace_id": "255d1aef-8c98-452f-ac51-23d051240864",
  "correlation_id": "fb3d2015-bc17-4bb9-bb85-30c5cf1aaaa7"
}
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