Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Peringatan
Konten ini untuk versi endpoint Azure AD v1.0 yang lama. Gunakan platform identitas Microsoft untuk proyek baru.
Nota
Jika Anda tidak memberi tahu server sumber daya apa yang ingin Anda panggil, server tidak akan memicu kebijakan Akses Bersyarat untuk sumber daya tersebut. Jadi untuk memiliki pemicu MFA, Anda harus menyertakan sumber daya di URL Anda.
Azure Active Directory (Azure AD) menggunakan OAuth 2.0 untuk memungkinkan Anda mengotorisasi akses ke aplikasi web dan API web di penyewa Azure AD Anda. Panduan ini independen dalam bahasa, dan menjelaskan cara mengirim dan menerima pesan HTTP tanpa menggunakan pustaka 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.
Daftarkan aplikasi Anda di penyewa AD Anda
Pertama, daftarkan aplikasi Anda dengan penyewa Azure Active Directory (Azure AD) Anda. Ini akan memberi Anda ID Aplikasi untuk aplikasi Anda, serta memungkinkannya untuk menerima token.
Masuk ke portal Azure.
Pilih penyewa Azure AD Anda dengan memilih akun Anda di sudut kanan atas halaman, diikuti dengan memilih navigasi Beralih Direktori lalu memilih penyewa yang sesuai.
- Lewati langkah ini jika Anda hanya memiliki satu penyewa Azure ACTIVE Directory di bawah akun Anda, atau jika Anda telah memilih penyewa Azure AD yang sesuai.
Di portal Microsoft Azure, cari dan pilih Azure Active Directory.
Di menu kiri Azure Active Directory, pilih Pendaftaran Aplikasi, lalu pilih Pendaftaran baru.
Ikuti perintah dan buat aplikasi baru. Tidak masalah apakah itu adalah aplikasi web atau aplikasi klien publik (mobile & desktop) untuk tutorial ini, namun jika Anda menginginkan contoh spesifik untuk aplikasi web atau aplikasi klien publik, lihat panduan cepat kami.
- Name adalah nama aplikasi dan menjelaskan aplikasi Anda kepada 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:12345. Untuk klien publik (desktop & seluler), Azure AD menggunakannya untuk mengembalikan respons token. Masukkan nilai khusus untuk aplikasi Anda. Contohnya,http://MyFirstAADApp.
Setelah Anda menyelesaikan pendaftaran, Azure ACTIVE Directory akan menetapkan pengidentifikasi klien unik (ID Aplikasi ). 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 Lihat semua aplikasi.
Alur otorisasi OAuth 2.0
Pada tingkat tinggi, seluruh alur otorisasi 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 perlu diperoleh dari pengguna. Anda bisa mendapatkan titik akhir otorisasi OAuth 2.0 untuk penyewa Anda dengan memilih Pendaftaran Aplikasi > Titik Akhir di portal Microsoft 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
| Pengaturan | Tipe | Deskripsi |
|---|---|---|
| penyewa | wajib | 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 independen penyewa |
| ID klien | wajib | ID Aplikasi yang ditetapkan ke aplikasi Anda saat Anda mendaftarkannya dengan Azure AD. Anda dapat menemukan ini di portal Microsoft Azure. Klik Azure Active Directory di bilah sisi layanan, klik Pendaftaran aplikasi, dan pilih aplikasi. |
| jenis_respons | wajib | Harus menyertakan code untuk aliran kode otorisasi. |
| URI pengalihan | Disarankan | Redirect_uri aplikasi Anda, tempat respons autentikasi dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu redirect_uris yang Anda daftarkan di portal, kecuali harus di-encode sebagai URL. Untuk aplikasi mobile & bawaan, Anda harus menggunakan nilai bawaan https://login.microsoftonline.com/common/oauth2/nativeclient. |
| response_mode | fakultatif | Menentukan metode yang akan digunakan untuk mengirim token yang dihasilkan kembali 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 mengirimkan POST yang berisi kode ke URI pengalihan Anda. Defaultnya adalah query untuk alur kode. |
| negara | Disarankan | Nilai yang termasuk dalam permintaan dan 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 mengodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi terjadi, 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 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 menempatkannya dalam permintaan otorisasi untuk memastikan persetujuan diterima dari pengguna. |
| ruang lingkup | diabaikan | Untuk aplikasi Azure AD v1, cakupan harus dikonfigurasi secara statis di portal Microsoft Azure di bawah aplikasi Pengaturan, Izin yang Diperlukan. |
| petunjuk | fakultatif | Tunjukkan jenis interaksi pengguna yang diperlukan. Nilai yang valid adalah: login: Pengguna harus diminta untuk mengautentikasi ulang. select_account: Pengguna diminta untuk memilih akun, mengganggu proses single sign-on. Pengguna dapat memilih akun masuk yang ada, memasukkan kredensial mereka untuk akun yang diingat, atau memilih untuk menggunakan akun lain sama sekali. persetujuan: 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 |
| petunjuk_masuk | fakultatif | Dapat digunakan untuk mengisi otomatis bidang nama pengguna/alamat email pada halaman masuk log untuk pengguna tersebut, jika Anda sudah mengetahui nama pengguna mereka sebelumnya. Seringkali aplikasi menggunakan parameter ini selama autentikasi ulang, setelah mengekstrak nama pengguna dari rincian masuk sebelumnya menggunakan klaim preferred_username. |
| domain_hint | fakultatif | Memberikan petunjuk tentang penyewa atau domain yang harus digunakan pengguna untuk masuk. Nilai dari domain_hint adalah domain yang terdaftar untuk penyewa. Jika penyewa digabungkan ke direktori lokal, AAD mengalihkan ke server federasi penyewa yang ditentukan. |
| metode_tantangan_kode | Disarankan | Metode yang digunakan untuk mengodekan code_verifier untuk parameter code_challenge. Bisa menjadi salah satu 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. |
| tantangan_kode | 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. |
Nota
Jika pengguna adalah bagian dari organisasi, administrator organisasi dapat menyetujui atau menolak atas nama pengguna, atau mengizinkan pengguna untuk menyetujui. Pengguna diberi opsi untuk menyetujui hanya ketika administrator mengizinkannya.
Pada titik ini, pengguna diminta untuk memasukkan kredensial mereka dan menyetujui izin yang diminta oleh aplikasi di portal Microsoft Azure. Setelah pengguna mengautentikasi dan memberikan persetujuan, Azure AD mengirimkan respons ke aplikasi Anda di alamat redirect_uri dalam permintaan Anda dengan kode.
Respons berhasil
Respons yang berhasil dapat 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
| Pengaturan | Deskripsi |
|---|---|
| persetujuan_admin | Nilainya adalah True jika administrator menyetujui permintaan persetujuan yang diminta. |
| kode | Kode otorisasi yang diminta aplikasi. Aplikasi dapat menggunakan kode otorisasi untuk meminta token akses untuk sumber daya target. |
| status_sesi | Nilai unik yang mengidentifikasi sesi pengguna saat ini. Nilai ini adalah GUID, tetapi harus diperlakukan sebagai nilai buram yang dilewati tanpa pemeriksaan. |
| negara | 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 Lintas Situs (CSRF) terhadap klien. |
Tanggapan kesalahan
Respons kesalahan juga dapat dikirim ke redirect_uri sehingga aplikasi dapat menanganinya dengan tepat.
GET http://localhost:12345/?
error=access_denied
&error_description=the+user+canceled+the+authentication
Kode kesalahan untuk titik akhir otorisasi
Tabel berikut menjelaskan berbagai kode kesalahan yang dapat dikembalikan dalam parameter error pada respons kesalahan.
| Kode Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|
| permintaan_tidak_valid | Kesalahan protokol, seperti kehilangan parameter yang diperlukan. | Perbaiki dan kirim ulang permintaan. Ini adalah kesalahan pengembangan, dan biasanya tertangkap selama pengujian awal. |
| klien_tidak_berwenang | Aplikasi klien tidak diizinkan untuk meminta kode otorisasi. | Ini biasanya terjadi ketika aplikasi klien tidak terdaftar di Azure Active Directory atau tidak ditambahkan ke penyewa Azure Active Directory milik pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure AD. |
| akses_ditolak | Pemilik sumber daya menolak persetujuan | Aplikasi klien dapat memberi tahu pengguna bahwa aplikasi tidak dapat dilanjutkan kecuali pengguna menyetujui. |
| jenis_respon_tidak_didukung | Server otorisasi tidak mendukung jenis respons dalam permintaan. | Perbaiki dan kirim ulang permintaan. Ini adalah kesalahan pengembangan, dan biasanya tertangkap selama pengujian awal. |
| kesalahan server | Server mengalami kesalahan tidak terduga. | Ulangi permintaan. Kesalahan ini dapat diakibatkan oleh kondisi sementara. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kesalahan sementara. |
| sementara_tidak_tersedia | Server terlalu sibuk untuk menangani permintaan tersebut untuk sementara waktu. | Ulangi permintaan. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kondisi sementara. |
| sumber daya tidak valid | Sumber daya target tidak valid karena tidak ada, Azure AD tidak dapat menemukannya, atau tidak dikonfigurasi dengan benar. | Ini menunjukkan bahwa sumber daya, jika ada, belum dikonfigurasi di tenant. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure AD. |
Menggunakan kode otorisasi untuk meminta token akses
Sekarang setelah Anda memperoleh kode otorisasi dan telah diberikan 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
| Pengaturan | Tipe | Deskripsi |
|---|---|---|
| penyewa | wajib | 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 independen penyewa |
| ID klien | wajib | Id Aplikasi yang ditetapkan ke aplikasi Anda saat Anda mendaftarkannya dengan Azure AD. Anda dapat menemukan ini di portal Microsoft Azure. Id Aplikasi ditampilkan dalam pengaturan pendaftaran aplikasi. |
| jenis_izin | wajib | Harus authorization_code untuk aliran kode otorisasi. |
| kode | wajib |
authorization_code yang Anda peroleh di bagian sebelumnya |
| URI pengalihan | wajib | Sebuah redirect_uritelah 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 Keys. Ini tidak dapat digunakan dalam aplikasi asli (klien publik), karena client_secrets tidak dapat disimpan dengan andal pada perangkat. Ini diperlukan untuk aplikasi web dan API web (semua klien rahasia), yang memiliki kemampuan untuk menyimpan client_secret dengan aman di sisi server. client_secret harus dikodekan URL sebelum dikirim. |
| Sumber daya | Disarankan | URI ID Aplikasi dari API web yang ditargetkan (sumber daya yang aman). Untuk menemukan URI ID Aplikasi, di portal Microsoft Azure, klik 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 menempatkannya dalam permintaan otorisasi untuk memastikan persetujuan diterima dari pengguna. Jika dalam permintaan otorisasi dan permintaan token, parameter sumber daya harus cocok. |
| pemverifikasi_kode | fakultatif | Kode_verifier yang sama yang digunakan untuk memperoleh 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 Azure Active Directory, klik Pendaftaran aplikasi, buka halaman Pengaturan aplikasi, lalu klik Properti .
Respons berhasil
Azure AD mengembalikan token akses setelah respons berhasil. Untuk meminimalkan panggilan jaringan dari aplikasi klien dan latensi terkait, aplikasi klien harus menyimpan 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 bahwa sumber daya telah menentukan bahwa token kedaluwarsa. Jika waktu jam klien dan sumber daya berbeda (dikenal sebagai "penyimpangan waktu"), sumber daya mungkin mempertimbangkan token untuk kedaluwarsa sebelum token dibersihkan dari cache klien. Jika ini terjadi, hapus token dari cache, bahkan jika masih dalam masa pakai yang dihitung.
Respons yang berhasil dapat 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."
}
| Pengaturan | Deskripsi |
|---|---|
| access_token (token akses) | Token akses yang diminta. Ini adalah string buram - tergantung pada apa yang diharapkan sumber daya untuk menerima, dan tidak dimaksudkan untuk dilihat klien. Aplikasi dapat menggunakan token ini untuk mengautentikasi ke sumber daya yang aman, seperti API web. |
| tipe_token | Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung Microsoft Azure AD adalah Bearer. Untuk informasi selengkapnya tentang token Pembawa, lihat Kerangka Kerja Otorisasi OAuth2.0: Penggunaan Token Pembawa (RFC 6750) |
| Kadaluarsa dalam | Berapa lama token akses berlaku/valid (dalam detik). |
| kedaluwarsa pada | Waktu ketika token akses kedaluwarsa. Tanggal dinyatakan sebagai jumlah detik dari 1970-01-01T0:0:0Z UTC hingga waktu kedaluwarsa. Nilai ini digunakan untuk menentukan masa pakai token yang di-cache. |
| Sumber daya | URI ID Aplikasi dari API web (sumber daya aman). |
| ruang lingkup | Izin penyamaran identitas diberikan kepada aplikasi klien. Izin default adalah user_impersonation. Pemilik sumber daya aman dapat mendaftarkan nilai tambahan di Azure AD. |
| token penyegaran | Token OAuth 2.0 tipe refresh Aplikasi dapat menggunakan token ini untuk memperoleh token akses tambahan setelah token akses 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 yang mewakili sebuah token ID . Aplikasi ini dapat mendekode base64Url segmen token ini untuk meminta informasi tentang pengguna yang masuk. Aplikasi ini dapat menyimpan nilai dan menampilkannya, tetapi tidak boleh mengandalkannya untuk batas otorisasi atau keamanan apa pun. |
Untuk informasi selengkapnya tentang token web JSON, lihat spesifikasi draf JWT IETF . Untuk mempelajari selengkapnya tentang id_tokens, lihat alur OpenID Connect v1.0.
Tanggapan 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 Azure AD juga mengembalikan dokumen JSON dengan objek yang menjelaskan kesalahan.
Contoh respons kesalahan dapat 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"
}
| Pengaturan | Deskripsi |
|---|---|
| kesalahan | String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap kesalahan. |
| deskripsi_kesalahan | Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi. |
| kode_kesalahan | Daftar kode kesalahan khusus STS yang dapat membantu dalam diagnostik. |
| penanda waktu | Waktu saat peristiwa itu terjadi. |
| trace_id | Pengidentifikasi unik untuk permintaan yang dapat membantu dalam proses 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 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 default HTTP. Digunakan dalam kebanyakan kasus dan biasanya karena permintaan yang salah format. 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. Ulangi permintaan. |
Kode kesalahan untuk kesalahan titik akhir token
| Kode Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|
| permintaan_tidak_valid | Kesalahan protokol, seperti kehilangan parameter yang diperlukan. | Memperbaiki dan mengirim ulang permintaan |
| ijin_tidak_valid | Kode otorisasi tidak valid atau telah kedaluwarsa. | Cobalah membuat permintaan baru ke titik akhir /authorize |
| klien_tidak_berwenang | Klien yang diautentikasi tidak berwenang untuk menggunakan jenis pemberian otorisasi ini. | Ini biasanya terjadi ketika aplikasi klien tidak terdaftar di Azure Active Directory atau tidak ditambahkan ke penyewa Azure Active Directory milik pengguna. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure AD. |
| klien_tidak_valid | Autentikasi klien gagal. | Kredensial klien tidak valid. Untuk memperbaikinya, administrator aplikasi memperbarui kredensial. |
| jenis_grant_tidak_didukung | 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. |
| sumber daya tidak valid | Sumber daya target tidak valid karena tidak ada, Azure AD tidak dapat menemukannya, atau tidak dikonfigurasi dengan benar. | Ini menunjukkan bahwa sumber daya, jika ada, belum dikonfigurasi di tenant. Aplikasi dapat meminta pengguna dengan instruksi untuk menginstal aplikasi dan menambahkannya ke Microsoft Azure AD. |
| interaksi_diperlukan | Permintaan ini memerlukan interaksi pengguna. Misalnya, langkah autentikasi tambahan diperlukan. | Alih-alih permintaan non-interaktif, coba lagi dengan permintaan otorisasi interaktif untuk sumber daya yang sama. |
| sementara_tidak_tersedia | Server terlalu sibuk untuk menangani permintaan tersebut untuk sementara waktu. | Ulangi permintaan. Aplikasi klien mungkin menjelaskan kepada pengguna bahwa responsnya tertunda karena kondisi sementara. |
Menggunakan token akses untuk mengakses sumber daya
Sekarang setelah Anda 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.
Permohonan 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
Tanggapan Kesalahan
Sumber daya aman yang menerapkan RFC 6750 mengeluarkan kode status HTTP. Jika permintaan tidak menyertakan kredensial autentikasi atau kehilangan token, respons menyertakan header WWW-Authenticate. Ketika permintaan gagal, server sumber daya merespons dengan kode status HTTP dan kode kesalahan.
Berikut ini 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
Kode kesalahan skema pembawa
Spesifikasi RFC 6750 mendefinisikan kesalahan berikut untuk sumber daya yang menggunakan header WWW-Authenticate dan skema Bearer dalam respons.
| Kode Status HTTP | Kode Kesalahan | Deskripsi | Tindakan Klien |
|---|---|---|---|
| 400 | permintaan_tidak_valid | Permintaan tidak tersusun dengan baik. Misalnya, parameter mungkin hilang atau menggunakan parameter yang sama dua kali. | Perbaiki kesalahan dan coba lagi permintaan. Jenis kesalahan ini harus terjadi hanya selama pengembangan dan terdeteksi dalam pengujian awal. |
| 401 | token_tidak_valid | 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 tak terduga. Kirim pesan kesalahan ke pengguna dan coba lagi setelah penundaan acak. |
| 403 | cakupan_tidak_cukup | 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 | Akses tidak memadai | 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. |
Menyegarkan token akses
Token Akses berumur pendek 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 alih-alih code. Token refresh valid untuk semua sumber daya yang telah diberikan persetujuan untuk diakses klien Anda - dengan demikian, token refresh yang dikeluarkan berdasarkan permintaan resource=https://graph.microsoft.com dapat digunakan untuk meminta token akses baru untuk resource=https://contoso.com/api.
Token refresh 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 mengharapkan dan menangani kesalahan yang dikembalikan oleh titik akhir penerbitan token dengan benar.
Saat Anda menerima respons dengan kesalahan token refresh, buang 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, buang token refresh dan minta kode otorisasi baru.
Permintaan contoh 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"
}
| Pengaturan | Deskripsi |
|---|---|
| tipe_token | Jenis token. Satu-satunya nilai yang didukung adalah bearer. |
| Kadaluarsa dalam | Sisa masa pakai token dalam hitungan detik. Nilai umumnya adalah 3600 (satu jam). |
| kedaluwarsa pada | Tanggal dan waktu kedaluwarsa token. Tanggal dinyatakan sebagai jumlah detik dari 1970-01-01T0:0:0Z UTC hingga waktu kedaluwarsa. |
| Sumber daya | Mengidentifikasi sumber daya aman yang dapat digunakan untuk mengakses token akses. |
| ruang lingkup | Izin impersonasi yang diberikan kepada aplikasi klien lokal. Izin default adalah user_impersonation. Pemilik sumber daya target dapat mendaftarkan nilai alternatif di Azure ACTIVE Directory. |
| access_token (token akses) | Token akses baru yang diminta. |
| token penyegaran | Refresh_token OAuth 2.0 baru yang dapat digunakan untuk meminta token akses baru saat token dalam respons ini kedaluwarsa. |
Tanggapan kesalahan
Contoh respons kesalahan dapat 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"
}
| Pengaturan | Deskripsi |
|---|---|
| kesalahan | String kode kesalahan yang dapat digunakan untuk mengklasifikasikan jenis kesalahan yang terjadi, dan dapat digunakan untuk bereaksi terhadap kesalahan. |
| deskripsi_kesalahan | Pesan kesalahan tertentu yang dapat membantu Anda mengidentifikasi akar penyebab kesalahan autentikasi. |
| kode_kesalahan | Daftar kode kesalahan khusus STS yang dapat membantu dalam diagnostik. |
| penanda waktu | Waktu saat peristiwa itu terjadi. |
| trace_id | Pengidentifikasi unik untuk permintaan yang dapat membantu dalam proses 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 dan otorisasi ke aplikasi web dan API web Anda, lihat aplikasi sampel.