Mengotorisasi akses ke aplikasi web Azure Active Directory menggunakan alur peruntukan kode OAuth 2.0
Peringatan
Konten ini untuk titik akhir Azure AD v1.0 yang lebih lama. Gunakan platform identitas Microsoft untuk proyek baru.
Catatan
Jika Anda tidak memberi tahu server sumber daya apa yang Anda rencanakan untuk dipanggil, server tidak akan memicu kebijakan Akses Bersyarat untuk sumber daya tersebut. Jadi, untuk memiliki pemicu MFA, Anda harus menyertakan sumber daya dalam URL Anda.
Microsoft Azure Active Directory (Azure AD) menggunakan OAuth 2.0 untuk memungkinkan Anda mengotorisasi akses ke aplikasi web dan API web di penyewa Microsoft Azure Active Directory Anda. Panduan ini tidak tergantung pada bahasa, dan menjelaskan cara mengirim dan menerima pesan HTTP tanpa menggunakan salah satu perpustakaan sumber terbuka kami.
Alur kode otorisasi OAuth 2.0 dijelaskan dalam bagian 4.1 dari spesifikasi OAuth 2.0. Ini digunakan untuk melakukan autentikasi dan otorisasi di sebagian besar jenis aplikasi, termasuk aplikasi web dan aplikasi yang diinstal secara asli.
Mendaftarkan aplikasi Anda dengan penyewa AD Anda
Pertama, daftarkan aplikasi Anda dengan penyewa Microsoft Azure Active Directory (Azure AD). Ini akan memberi Anda ID Aplikasi untuk aplikasi Anda, serta mengaktifkannya untuk menerima token.
Masuk ke portal Microsoft Azure.
Pilih penyewa Microsoft Azure Active Directory Anda dengan memilih akun Anda di sudut kanan atas halaman, diikuti dengan memilih navigasi Alihkan Direktori, lalu pilih penyewa yang sesuai.
- Lewati langkah ini jika Anda hanya memiliki satu penyewa Microsoft Azure Active Directory di bawah akun Anda, atau jika Anda sudah memilih penyewa Microsoft Azure Active Directory yang sesuai.
Di portal Microsoft Azure, cari dan pilih Azure Active Directory.
Di menu sebelah kiri Microsoft Azure Active Directory, pilih Pendaftaran Aplikasi, lalu pilih Pendaftaran baru.
Ikuti perintah dan buat aplikasi baru. Tidak masalah apakah itu aplikasi web atau aplikasi klien publik (desktop & seluler) untuk tutorial ini, tetapi jika Anda ingin contoh khusus untuk aplikasi web atau aplikasi klien publik, lihat mulai cepat kami.
- Nama adalah nama aplikasi dan menjelaskan aplikasi Anda ke pengguna akhir.
- Di bawah Jenis akun yang didukung, pilih Akun di direktori organisasi dan akun Microsoft pribadi apa pun.
- Berikan URI Pengalihan. Untuk aplikasi web, ini adalah URL dasar aplikasi Anda tempat pengguna dapat masuk. Contohnya:
http://localhost:12345Untuk klien publik (seluler & desktop), Microsoft Azure Active Directory menggunakannya untuk mengembalikan respons token. Masukkan nilai yang spesifik untuk aplikasi Anda. Contohnya:http://MyFirstAADApp
Setelah Anda menyelesaikan pendaftaran, Microsoft Azure Active Directory akan menetapkan pengidentifikasi klien unik (ID Aplikasi) ke aplikasi Anda. Anda memerlukan nilai ini di bagian berikutnya, jadi, salin dari halaman aplikasi.
Untuk menemukan aplikasi Anda di portal Microsoft Azure, pilih Pendaftaran aplikasi, lalu pilih Tampilkan semua aplikasi.
Alur otorisasi OAuth 2.0
Pada tingkat tinggi, seluruh alur autentikasi untuk aplikasi terlihat sedikit seperti ini:
Meminta kode otorisasi
Alur kode otorisasi dimulai dengan klien mengarahkan pengguna ke titik akhir /authorize. Dalam permintaan ini, klien menunjukkan izin yang harus didapatkan dari pengguna. Anda bisa mendapatkan titik akhir otorisasi OAuth 2.0 untuk penyewa Anda dengan memilih Pendaftaran aplikasi > Titik akhir di portal Azure.
// Line breaks for legibility only
https://login.microsoftonline.com/{tenant}/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%3A12345
&response_mode=query
&resource=https%3A%2F%2Fservice.contoso.com%2F
&state=12345
| Parameter | Jenis | Deskripsi |
|---|---|---|
| tenant | diperlukan | Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah pengidentifikasi penyewa, misalnya, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 atau contoso.onmicrosoft.com atau common untuk token penyewa independen |
| client_id | diperlukan | ID Aplikasi yang ditetapkan ke aplikasi Anda saat Anda mendaftarkannya dengan Microsoft Azure Active Directory. Anda dapat menemukan ini di portal Microsoft Azure. Klik Microsoft Azure Active Directory di bilah sisi layanan, klik Pendaftaran aplikasi, dan pilih aplikasi. |
| response_type | diperlukan | Harus menyertakan code untuk aliran kode otorisasi. |
| redirect_uri | disarankan | redirect_uri aplikasi Anda, di mana respons autentikasi dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu redirect_uris yang Anda daftarkan di portal, kecuali hal itu memang harus dikodekan URL. Untuk aplikasi asli & seluler, Anda harus menggunakan nilai default dari https://login.microsoftonline.com/common/oauth2/nativeclient. |
| response_mode | opsional | Menentukan metode yang harus digunakan untuk menghasilkan hasil token ke aplikasi Anda. Bisa query, fragment, atau form_post. query menyediakan kode sebagai parameter string kueri pada URI pengalihan Anda. Jika Anda meminta token ID menggunakan alur implisit, Anda tidak dapat menggunakan query seperti yang ditentukan dalam spesifikasi OpenID. Jika Anda hanya meminta kode, Anda dapat menggunakan query, fragment, atau form_post. form_post mengeksekusi POST yang berisi kode ke URI pengalihan Anda. Defaultnya adalah query untuk alur kode. |
| status | disarankan | Nilai yang disertakan dalam permintaan yang juga dikembalikan dalam respons token. Nilai unik yang dihasilkan secara acak biasanya digunakan untuk mencegah serangan pemalsuan permintaan lintas situs. Status ini juga digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada. |
| sumber daya | disarankan | URI ID Aplikasi dari API web target (sumber daya aman). Untuk menemukan URI ID Aplikasi, di portal Microsoft Azure, klik Microsoft Azure Active Directory, klik Pendaftaran aplikasi, buka halaman Pengaturan aplikasi, lalu klik Properti. Ini mungkin juga sumber daya eksternal seperti https://graph.microsoft.com. Ini diperlukan dalam salah satu permintaan otorisasi atau token. Untuk memastikan lebih sedikit permintaan autentikasi, tempatkan dalam permintaan otorisasi untuk memastikan persetujuan diterima dari pengguna. |
| scope | diabaikan | Untuk aplikasi Microsoft Azure Active Directory v1, cakupan harus dikonfigurasi secara statis di portal Microsoft Azure di bawah Pengaturan aplikasi, Izin yang Diperlukan. |
| permintaan | opsional | Menunjukkan jenis interaksi pengguna yang diperlukan. Nilai yang valid adalah: login: Pengguna harus diminta untuk mengautentikasi ulang. select_account: Pengguna diminta untuk memilih akun, mengganggu akses menyeluruh. Pengguna dapat memilih akun masuk yang sudah ada, memasukkan info masuk mereka untuk akun yang diingat, atau memilih untuk menggunakan akun lain. consent: Persetujuan pengguna telah diberikan, tetapi perlu diperbarui. Pengguna harus diminta untuk menyetujui. admin_consent: Administrator harus diminta untuk menyetujui atas nama semua pengguna di organisasi mereka |
| login_hint | opsional | Anda dapat menggunakan parameter ini untuk mengisi terlebih dulu bidang nama pengguna dan alamat email halaman masuk untuk pengguna, jika Anda mengetahui nama pengguna sebelumnya. Sering kali aplikasi menggunakan parameter ini saat autentikasi ulang, setelah mengekstrak nama pengguna dari aktivitas masuk sebelumnya menggunakan klaim preferred_username. |
| domain_hint | opsional | Menyediakan petunjuk tentang penyewa atau domain yang harus digunakan pengguna untuk masuk. Nilai domain_hint domain adalah domain terdaftar untuk penyewa. Jika penyewa disalurkan ke direktori lokal, Microsoft Azure Active Directory akan dialihkan ke server federasi penyewa tertentu. |
| code_challenge_method | disarankan | Metode yang digunakan untuk mengodekan code_verifier untuk parameter code_challenge. Bisa menjadi salah satu dari plain atau S256. Jika dikecualikan, code_challenge diasumsikan sebagai teks biasa jika code_challenge disertakan. Azure AAD v1.0 mendukung plain dan S256. Untuk informasi selengkapnya, lihat PKCE RFC. |
| code_challenge | disarankan | Digunakan untuk mengamankan pemberian kode otorisasi melalui Proof Key for Code Exchange (PKCE) dari klien asli atau publik. Diperlukan jika code_challenge_method disertakan. Untuk informasi selengkapnya, lihat PKCE RFC. |
Catatan
Jika pengguna adalah bagian dari organisasi, administrator organisasi dapat menyetujui atau menolak atas nama pengguna, atau mengizinkan pengguna untuk menyetujuinya. Pengguna diberi opsi untuk menyetujui hanya ketika administrator mengizinkannya.
Pada titik ini, pengguna diminta untuk memasukkan info masuk mereka dan menyetujui izin yang diminta oleh aplikasi di portal Microsoft Azure. Setelah pengguna mengautentikasi dan memberikan persetujuan, Microsoft Azure Active Directory mengirimkan respons ke aplikasi Anda di alamat redirect_uri dalam permintaan Anda dengan kode.
Respons berhasil
Respons yang berhasil bisa terlihat seperti ini:
GET HTTP/1.1 302 Found
Location: http://localhost:12345/?code= AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA&session_state=7B29111D-C220-4263-99AB-6F6E135D75EF&state=D79E5777-702E-4260-9A62-37F75FF22CCE
| Parameter | Deskripsi |
|---|---|
| admin_consent | Nilai True jika administrator menyetujui prompt permintaan persetujuan. |
| kode | Kode otorisasi yang diminta aplikasi. Aplikasi dapat menggunakan kode otorisasi untuk meminta token akses untuk sumber daya target. |
| session_state | Nilai unik yang mengidentifikasi sesi pengguna saat ini. Nilai ini adalah GUID, tetapi harus diperlakukan sebagai nilai buram yang dilewati tanpa pemeriksaan. |
| status | Jika parameter status disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Ini adalah praktik yang baik bagi aplikasi untuk memverifikasi bahwa nilai status dalam permintaan dan respons identik sebelum menggunakan respons. Ini membantu mendeteksi serangan Pemalsuan Permintaan Antar Situs (CSRF) terhadap klien. |
Respons kesalahan
Respons kesalahan juga bisa dikirim ke redirect_uri agar aplikasi dapat menanganinya dengan tepat.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
| Parameter | Deskripsi |
|---|---|
| error | Nilai kode kesalahan yang ditentukan dalam Bagian 5.2 dari Kerangka Kerja Otorisasi OAuth 2.0. Tabel berikutnya menjelaskan kode kesalahan yang dikembalikan Microsoft Azure Active Directory. |
| error_description | Deskripsi kesalahan yang lebih terperinci. Pesan ini tidak dimaksudkan untuk ramah pengguna akhir. |
| status | Nilai status adalah nilai yang tidak digunakan kembali yang dibuat secara acak yang dikirim dalam permintaan dan dikembalikan sebagai respons untuk mencegah serangan pemalsuan permintaan antar situs (CSRF). |
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, dan biasanya tertangkap selama pengujian awal. |
| unauthorized_client | Aplikasi klien tidak diizinkan untuk meminta kode otorisasi. | 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 ini tidak dapat dilanjutkan kecuali pengguna menyetujui. |
| unsupported_response_type | Server otorisasi tidak mendukung jenis respons dalam permintaan. | Perbaiki dan kirim ulang permintaan. Ini adalah kesalahan pengembangan, dan biasanya tertangkap selama pengujian awal. |
| 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 akibat 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 akibat kondisi sementara. |
| invalid_resource | Sumber daya target tidak valid karena tidak ada, Microsoft Azure Active Directory tidak dapat menemukannya, atau tidak dikonfigurasi dengan benar. | Ini menunjukkan bahwa sumber daya, jika ada, belum dikonfigurasi di penyewa. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure Active Directory. |
Menggunakan kode otorisasi untuk meminta token akses
Sekarang setelah Anda memperoleh kode otorisasi dan telah diberi izin oleh pengguna, Anda dapat menukarkan kode untuk token akses ke sumber daya yang diinginkan, dengan mengirim permintaan POST ke titik akhir /token:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code
&client_id=2d4d11a2-f814-46a7-890a-274a72a7309e
&code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrqqf_ZT_p5uEAEJJ_nZ3UmphWygRNy2C3jJ239gV_DBnZ2syeg95Ki-374WHUP-i3yIhv5i-7KU2CEoPXwURQp6IVYMw-DjAOzn7C3JCu5wpngXmbZKtJdWmiBzHpcO2aICJPu1KvJrDLDP20chJBXzVYJtkfjviLNNW7l7Y3ydcHDsBRKZc3GuMQanmcghXPyoDg41g8XbwPudVh7uCmUponBQpIhbuffFP_tbV8SNzsPoFz9CLpBCZagJVXeqWoYMPe2dSsPiLO9Alf_YIe5zpi-zY4C3aLw5g9at35eZTfNd0gBRpR5ojkMIcZZ6IgAA
&redirect_uri=https%3A%2F%2Flocalhost%3A12345
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=p@ssw0rd
//NOTE: client_secret only required for web apps
| Parameter | Jenis | Deskripsi |
|---|---|---|
| tenant | diperlukan | Nilai {tenant} di jalur permintaan dapat digunakan untuk mengontrol siapa yang dapat masuk ke aplikasi. Nilai yang diizinkan adalah pengidentifikasi penyewa, misalnya, 8eaef023-2b34-4da1-9baa-8bc8c9d6a490 atau contoso.onmicrosoft.com atau common untuk token penyewa independen |
| client_id | diperlukan | Id Aplikasi yang ditetapkan ke aplikasi Anda saat Anda mendaftarkannya dengan Microsoft Azure Active Directory. Anda dapat menemukan ini di portal Microsoft Azure. Id Aplikasi ditampilkan di pengaturan pendaftaran aplikasi. |
| grant_type | diperlukan | Harus authorization_code untuk aliran kode otorisasi. |
| kode | diperlukan | authorization_code yang Anda peroleh di bagian sebelumnya |
| redirect_uri | diperlukan | redirect_uri yang terdaftar di aplikasi klien. |
| client_secret | diperlukan untuk aplikasi web, tidak diizinkan untuk klien publik | Rahasia aplikasi yang Anda buat di portal Microsoft Azure untuk aplikasi Anda di bawah Kunci. Ini tidak bisa digunakan dalam aplikasi asli (klien publik), karena client_secrets tidak dapat disimpan dengan andal di perangkat. Ini diperlukan untuk aplikasi web dan API web (semua klien rahasia), yang memiliki kemampuan untuk menyimpan client_secret secara aman di sini server. client_secret harus berupa enkode URL sebelum dikirim. |
| sumber daya | disarankan | URI ID Aplikasi dari API web target (sumber daya aman). Untuk menemukan URI ID Aplikasi, di portal Microsoft Azure, klik Microsoft Azure Active Directory, klik Pendaftaran aplikasi, buka halaman Pengaturan aplikasi, lalu klik Properti. Ini mungkin juga sumber daya eksternal seperti https://graph.microsoft.com. Ini diperlukan dalam salah satu permintaan otorisasi atau token. Untuk memastikan lebih sedikit permintaan autentikasi, tempatkan dalam permintaan otorisasi untuk memastikan persetujuan diterima dari pengguna. Jika dalam permintaan otorisasi dan permintaan token, parameter sumber daya harus cocok. |
| code_verifier | opsional | 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 |
Untuk menemukan URI ID Aplikasi, di portal Microsoft Azure, klik Microsoft Azure Active Directory, klik Pendaftaran aplikasi, buka halaman Pengaturan aplikasi, lalu klik Properti.
Respons berhasil
Microsoft Azure Active Directory mengembalikan token akses setelah respons berhasil. Untuk meminimalkan panggilan jaringan dari aplikasi klien dan latensi terkait, aplikasi klien harus men-cache token akses untuk masa pakai token yang ditentukan dalam respons OAuth 2.0. Untuk menentukan masa pakai token, gunakan nilai parameter expires_in atau expires_on.
Jika sumber daya API web mengembalikan kode kesalahan invalid_token, ini mungkin menunjukkan sumber daya telah menentukan bahwa token kedaluwarsa. Jika waktu jam klien dan sumber daya berbeda (dikenal sebagai "kemiringan waktu"), sumber daya mungkin menganggap token akan kedaluwarsa sebelum token dihapus dari cache klien. Jika ini terjadi, hapus token dari cache, bahkan jika masih dalam masa pakai yang dihitung.
Respons yang berhasil bisa terlihat seperti ini:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1388444763",
"resource": "https://service.contoso.com/",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA",
"scope": "https%3A%2F%2Fgraph.microsoft.com%2Fmail.read",
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJpc3MiOiJodHRwczovL3N0cy53aW5kb3dzLm5ldC83ZmU4MTQ0Ny1kYTU3LTQzODUtYmVjYi02ZGU1N2YyMTQ3N2UvIiwiaWF0IjoxMzg4NDQwODYzLCJuYmYiOjEzODg0NDA4NjMsImV4cCI6MTM4ODQ0NDc2MywidmVyIjoiMS4wIiwidGlkIjoiN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlIiwib2lkIjoiNjgzODlhZTItNjJmYS00YjE4LTkxZmUtNTNkZDEwOWQ3NGY1IiwidXBuIjoiZnJhbmttQGNvbnRvc28uY29tIiwidW5pcXVlX25hbWUiOiJmcmFua21AY29udG9zby5jb20iLCJzdWIiOiJKV3ZZZENXUGhobHBTMVpzZjd5WVV4U2hVd3RVbTV5elBtd18talgzZkhZIiwiZmFtaWx5X25hbWUiOiJNaWxsZXIiLCJnaXZlbl9uYW1lIjoiRnJhbmsifQ."
}
| Parameter | Deskripsi |
|---|---|
| access_token | Token akses yang diminta. Ini adalah string buram - ini tergantung pada apa yang diharapkan sumber daya untuk diterima, dan tidak dimaksudkan untuk dilihat oleh klien. 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. Untuk informasi selengkapnya tentang token Pembawa, lihat Kerangka Kerja Otorisasi OAuth2.0: Penggunaan Token Pembawa (RFC 6750) |
| expires_in | Berapa lama token akses berlaku/valid (dalam detik). |
| expires_on | Rentang waktu kapan token akses kedaluwarsa. Tanggal tersebut dinyatakan sebagai jumlah detik dari 1970-01-01T0:0:0Z UTC hingga waktu kedaluwarsa. Nilai ini digunakan untuk menentukan masa pakai token cache. |
| sumber daya | URI ID Aplikasi dari API web (sumber daya aman). |
| scope | Izin peniruan yang diberikan ke aplikasi klien. Izin default adalah user_impersonation. Pemilik sumber daya aman dapat mendaftarkan nilai tambahan di Microsoft Azure Active Directory. |
| refresh_token | Token refresh OAuth 2.0. Aplikasi dapat menggunakan token ini untuk memperoleh token tambahan setelah token saat ini kedaluwarsa. Token refresh berumur panjang, dan dapat digunakan untuk mempertahankan akses ke sumber daya untuk waktu yang lama. |
| id_token | JSON Web Token (JWT) yang tidak ditandatangani mewakili token ID. Aplikasi dapat base64Url 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 token web JSON, lihat spesifikasi draf IETF JWT. Untuk mempelajari selengkapnya tentang id_tokens, lihat alur OpenID Connect v1.0.
Respons kesalahan
Kesalahan titik akhir penerbitan token adalah kode kesalahan HTTP, karena klien memanggil titik akhir penerbitan token secara langsung. Selain kode status HTTP, titik akhir penerbitan token Microsoft Azure Active Directory juga mengembalikan dokumen JSON dengan objek yang menjelaskan kesalahan.
Sampel respons kesalahan bisa terlihat seperti ini:
{
"error": "invalid_grant",
"error_description": "AADSTS70002: Error validating credentials. AADSTS70008: The provided authorization code or refresh token is expired. Send a new interactive authorization request for this user and resource.\r\nTrace ID: 3939d04c-d7ba-42bf-9cb7-1e5854cdce9e\r\nCorrelation ID: a8125194-2dc8-4078-90ba-7b6592a7f231\r\nTimestamp: 2016-04-11 18:00:12Z",
"error_codes": [
70002,
70008
],
"timestamp": "2016-04-11 18:00:12Z",
"trace_id": "3939d04c-d7ba-42bf-9cb7-1e5854cdce9e",
"correlation_id": "a8125194-2dc8-4078-90ba-7b6592a7f231"
}
| Parameter | Deskripsi |
|---|---|
| error | String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap 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. |
Kode status HTTP
Tabel berikut mencantumkan kode status HTTP yang dikembalikan oleh titik akhir penerbitan token. Dalam beberapa kasus, kode kesalahan cukup untuk menjelaskan respons, tetapi jika ada kesalahan, Anda perlu mengurai dokumen JSON yang menyertainya dan memeriksa kode kesalahannya.
| Kode HTTP | Deskripsi |
|---|---|
| 400 | Kode HTTP default. Digunakan dalam kebanyakan kasus dan biasanya karena permintaan yang salah bentuk. Perbaiki dan kirim ulang permintaan. |
| 401 | Autentikasi gagal. Misalnya, permintaan tidak memiliki parameter client_secret. |
| 403 | Otorisasi gagal. Misalnya, pengguna tidak memiliki izin untuk mengakses sumber daya. |
| 500 | Terjadi kesalahan internal pada layanan. Coba lagi permintaannya. |
Kode kesalahan untuk kesalahan titik akhir token
| Kode Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|
| invalid_request | Kesalahan protokol, seperti kehilangan parameter yang diperlukan. | Memperbaiki dan mengirim ulang permintaan |
| invalid_grant | Kode otorisasi tak-sahih atau telah kedaluwarsa. | Mencoba permintaan baru ke titik akhir /authorize |
| unauthorized_client | Klien yang diautentikasi tidak berwenang untuk menggunakan jenis pemberian otorisasi ini. | 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. | Info masuk klien tidak valid. Untuk memperbaikinya, administrator aplikasi memperbarui kredensial. |
| unsupported_grant_type | Server otorisasi tak mendukung tipe 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, Microsoft Azure Active Directory tidak dapat menemukannya, atau tidak dikonfigurasi dengan benar. | Ini menunjukkan bahwa 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 | Permintaan ini memerlukan interaksi pengguna. Misalnya, langkah autentikasi tambahan diperlukan. | Sebagai ganti permintaan non-interaktif, coba lagi dengan permintaan otorisasi interaktif untuk sumber daya yang sama. |
| temporarily_unavailable | Server terlalu sibuk untuk menangani permintaan tersebut untuk sementara waktu. | Coba lagi permintaannya. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda akibat kondisi sementara. |
Gunakan token akses untuk mengakses sumber daya
Setelah berhasil memperoleh access_token, Anda dapat menggunakan token dalam permintaan ke API Web, dengan menyertakannya di header Authorization. Spesifikasi RFC 6750 menjelaskan cara menggunakan token pembawa dalam permintaan HTTP untuk mengakses sumber daya yang dilindungi.
Permintaan sampel
GET /data HTTP/1.1
Host: service.contoso.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ
Respons Kesalahan
Sumber daya aman yang menerapkan RFC 6750 mengeluarkan kode status HTTP. Jika permintaan tidak menyertakan info masuk autentikasi atau tidak memiliki token, respons menyertakan header WWW-Authenticate. Ketika permintaan gagal, server sumber daya merespons dengan kode status HTTP dan kode kesalahan.
Berikut adalah contoh respons yang tidak berhasil ketika permintaan klien tidak menyertakan token pembawa:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer authorization_uri="https://login.microsoftonline.com/contoso.com/oauth2/authorize", error="invalid_token", error_description="The access token is missing.",
Parameter kesalahan
| Parameter | Deskripsi |
|---|---|
| authorization_uri | URI (titik akhir fisik) server otorisasi. Nilai ini juga digunakan sebagai kunci pencarian untuk mendapatkan informasi selengkapnya tentang server dari titik akhir penemuan. Klien harus memvalidasi bahwa server otorisasi dipercaya. Saat sumber daya dilindungi oleh Microsoft Azure Active Directory, cukup untuk memverifikasi bahwa URL dimulai dengan |
| error | Nilai kode kesalahan yang ditentukan dalam Bagian 5.2 dari Kerangka Kerja Otorisasi OAuth 2.0. |
| error_description | Deskripsi kesalahan yang lebih terperinci. Pesan ini tidak dimaksudkan untuk ramah pengguna akhir. |
| resource_id | Mengembalikan pengidentifikasi unik sumber daya. Aplikasi klien dapat menggunakan pengidentifikasi ini sebagai nilai dari parameter resource ketika meminta token untuk sumber daya. Penting bagi aplikasi klien untuk memverifikasi nilai ini, jika tidak, layanan berbahaya mungkin dapat menginduksi serangan elevation-of-privileges Strategi yang disarankan untuk mencegah serangan adalah memverifikasi bahwa |
Kode kesalahan skema pembawa
Spesifikasi RFC 6750 menentukan kesalahan berikut untuk sumber daya yang menggunakan header WWW-Authenticate dan skema Pembawa dalam respons.
| Kode Status HTTP | Kode Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|---|
| 400 | invalid_request | Permintaan tidak dibentuk dengan baik. Misalnya, ini mungkin kehilangan parameter atau menggunakan parameter yang sama dua kali. | Perbaiki kesalahan, lalu coba lagi permintaannya. Jenis kesalahan ini hanya terjadi selama pengembangan dan terdeteksi selama pengujian awal. |
| 401 | invalid_token | Token akses hilang, tidak valid, atau dicabut. Nilai parameter error_description memberikan detail tambahan. | Minta token baru dari server otorisasi. Jika token baru gagal, terjadi kesalahan tidak terduga. Kirim pesan kesalahan kepada pengguna dan coba lagi setelah penundaan acak. |
| 403 | insufficient_scope | Token akses tidak berisi izin peniruan yang diperlukan untuk mengakses sumber daya. | Kirim permintaan otorisasi baru ke titik akhir otorisasi. Jika respons berisi parameter cakupan, gunakan nilai cakupan dalam permintaan ke sumber daya. |
| 403 | insufficient_access | Subjek token tidak memiliki izin yang diperlukan untuk mengakses sumber daya. | Minta pengguna untuk menggunakan akun lain atau meminta izin ke sumber daya yang ditentukan. |
Me-refresh token akses
Token Akses bersifat sementara, dan harus di-refresh setelah kedaluwarsa untuk terus mengakses sumber daya. Anda dapat me-refresh access_token dengan mengirimkan permintaan POST lain ke titik akhir /token, tetapi kali ini menyediakan refresh_token bukan code. Token refresh berlaku untuk semua sumber daya yang izin untuk mengaksesnya diberikan ke klien Anda - dengan demikian, token refresh yang diterbitkan di permintaan untuk resource=https://graph.microsoft.com dapat digunakan untuk meminta token akses baru untuk resource=https://contoso.com/api.
Token refresh tidak memiliki masa berlaku spesifik. 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 mengharapkan dan menangani kesalahan yang dikembalikan oleh titik akhir penerbitan token dengan benar.
Saat Anda menerima respons dengan kesalahan token refresh, hapus token refresh saat ini dan minta kode otorisasi baru atau token akses. Secara khusus, saat menggunakan token refresh dalam alur Pemberian Kode Otorisasi, jika Anda menerima respons dengan kode kesalahan interaction_required atau invalid_grant, hapus token refresh dan minta kode otorisasi baru.
Sampel permintaan ke titik akhir khusus penyewa (Anda juga dapat menggunakan titik akhir umum) untuk mendapatkan token akses baru menggunakan token refresh terlihat seperti ini:
// Line breaks for legibility only
POST /{tenant}/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&resource=https%3A%2F%2Fservice.contoso.com%2F
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for web apps
Respons berhasil
Respons token yang berhasil akan terlihat seperti:
{
"token_type": "Bearer",
"expires_in": "3600",
"expires_on": "1460404526",
"resource": "https://service.contoso.com/",
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1THdqcHdBSk9NOW4tQSJ9.eyJhdWQiOiJodHRwczovL3NlcnZpY2UuY29udG9zby5jb20vIiwiaXNzIjoiaHR0cHM6Ly9zdHMud2luZG93cy5uZXQvN2ZlODE0NDctZGE1Ny00Mzg1LWJlY2ItNmRlNTdmMjE0NzdlLyIsImlhdCI6MTM4ODQ0MDg2MywibmJmIjoxMzg4NDQwODYzLCJleHAiOjEzODg0NDQ3NjMsInZlciI6IjEuMCIsInRpZCI6IjdmZTgxNDQ3LWRhNTctNDM4NS1iZWNiLTZkZTU3ZjIxNDc3ZSIsIm9pZCI6IjY4Mzg5YWUyLTYyZmEtNGIxOC05MWZlLTUzZGQxMDlkNzRmNSIsInVwbiI6ImZyYW5rbUBjb250b3NvLmNvbSIsInVuaXF1ZV9uYW1lIjoiZnJhbmttQGNvbnRvc28uY29tIiwic3ViIjoiZGVOcUlqOUlPRTlQV0pXYkhzZnRYdDJFYWJQVmwwQ2o4UUFtZWZSTFY5OCIsImZhbWlseV9uYW1lIjoiTWlsbGVyIiwiZ2l2ZW5fbmFtZSI6IkZyYW5rIiwiYXBwaWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctODkwYS0yNzRhNzJhNzMwOWUiLCJhcHBpZGFjciI6IjAiLCJzY3AiOiJ1c2VyX2ltcGVyc29uYXRpb24iLCJhY3IiOiIxIn0.JZw8jC0gptZxVC-7l5sFkdnJgP3_tRjeQEPgUn28XctVe3QqmheLZw7QVZDPCyGycDWBaqy7FLpSekET_BftDkewRhyHk9FW_KeEz0ch2c3i08NGNDbr6XYGVayNuSesYk5Aw_p3ICRlUV1bqEwk-Jkzs9EEkQg4hbefqJS6yS1HoV_2EsEhpd_wCQpxK89WPs3hLYZETRJtG5kvCCEOvSHXmDE6eTHGTnEgsIk--UlPe275Dvou4gEAwLofhLDQbMSjnlV5VLsjimNBVcSRFShoxmQwBJR_b2011Y5IuD6St5zPnzruBbZYkGNurQK63TJPWmRd3mbJsGM0mf3CUQ",
"refresh_token": "AwABAAAAv YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfcUl4VBbiSHZyd1NVZG5QTIOcbObu3qnLutbpadZGAxqjIbMkQ2bQS09fTrjMBtDE3D6kSMIodpCecoANon9b0LATkpitimVCrl PM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4rTfgV29ghDOHRc2B-C_hHeJaJICqjZ3mY2b_YNqmf9SoAylD1PycGCB90xzZeEDg6oBzOIPfYsbDWNf621pKo2Q3GGTHYlmNfwoc-OlrxK69hkha2CF12azM_NYhgO668yfmVCrl-NyfN3oyG4ZCWu18M9-vEou4Sq-1oMDzExgAf61noxzkNiaTecM-Ve5cq6wHqYQjfV9DOz4lbceuYCAA"
}
| Parameter | Deskripsi |
|---|---|
| token_type | Jenis token. Satu-satunya nilai yang didukung adalah pembawa. |
| expires_in | Sisa masa pakai token dalam hitungan detik. Nilai khasnya adalah 3600 (satu jam). |
| expires_on | Tanggal dan waktu ketika token kedaluwarsa. Tanggal tersebut dinyatakan sebagai jumlah detik dari 1970-01-01T0:0:0Z UTC hingga waktu kedaluwarsa. |
| sumber daya | Mengidentifikasi sumber daya aman yang dapat digunakan token akses untuk mengakses. |
| scope | Izin peniruan yang diberikan ke aplikasi klien asli. Izin default adalah user_impersonation. Pemilik sumber daya target dapat mendaftarkan nilai alternatif di Microsoft Azure Active Directory. |
| access_token | Token akses baru yang diminta. |
| refresh_token | refresh_token OAuth 2.0 baru yang dapat digunakan untuk meminta token akses baru saat token dalam respons ini kedaluwarsa. |
Respons kesalahan
Sampel respons kesalahan bisa terlihat seperti ini:
{
"error": "invalid_resource",
"error_description": "AADSTS50001: The application named https://foo.microsoft.com/mail.read was not found in the tenant named 295e01fc-0c56-4ac3-ac57-5d0ed568f872. This can happen if the application has not been installed by the administrator of the tenant or consented to by any user in the tenant. You might have sent your authentication request to the wrong tenant.\r\nTrace ID: ef1f89f6-a14f-49de-9868-61bd4072f0a9\r\nCorrelation ID: b6908274-2c58-4e91-aea9-1f6b9c99347c\r\nTimestamp: 2016-04-11 18:59:01Z",
"error_codes": [
50001
],
"timestamp": "2016-04-11 18:59:01Z",
"trace_id": "ef1f89f6-a14f-49de-9868-61bd4072f0a9",
"correlation_id": "b6908274-2c58-4e91-aea9-1f6b9c99347c"
}
| Parameter | Deskripsi |
|---|---|
| error | String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap 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
Untuk mempelajari selengkapnya tentang titik akhir Azure AD v1.0 dan cara menambahkan autentikasi serta otorisasi ke aplikasi web dan API web Anda, lihat sampel aplikasi.