Alur Koneksi/OAuth OpenID Layanan Federasi Direktori Aktif dan Skenario Aplikasi
Berlaku untuk Layanan Federasi Direktori Aktif 2016 dan yang lebih baru
| Skenario | Panduan skenario menggunakan sampel | Flow/Hibah OAuth 2.0 | Tipe Klien |
|---|---|---|---|
| Aplikasi satu halaman | • Sampel menggunakan ADAL | Implisit | Publik |
| Aplikasi Web yang memasukkan pengguna | • Sampel menggunakan OWIN | Kode Otorisasi | Publik, Rahasia |
| Aplikasi Asli memanggil API Web | • Sampel menggunakan MSAL• Sampel menggunakan ADAL | Kode Otorisasi | Publik |
| Web App memanggil API Web | • Sampel menggunakan MSAL• Sampel menggunakan ADAL | Kode Otorisasi | Rahasia |
| API Web memanggil API web lain atas nama (OBO) pengguna | • Sampel menggunakan MSAL• Sampel menggunakan ADAL | Atas nama | Aplikasi web bertindak sebagai Rahasia |
| Aplikasi Daemon memanggil API Web | Informasi masuk klien | Rahasia | |
| Aplikasi Web memanggil API Web menggunakan kredensial pengguna | Info Masuk Kata Sandi Pemilik Sumber Daya | Publik, Rahasia | |
| Aplikasi Tanpa Browser memanggil API Web | Kode perangkat | Publik, Rahasia |
Aliran hibah implisit
Untuk aplikasi satu halaman (AngularJS, Ember.js, React.js, dan sebagainya), Layanan Federasi Direktori Aktif mendukung alur Pemberian Implisit OAuth 2.0. Alur implisit dijelaskan dalam Spesifikasi OAuth 2.0. Manfaat utamanya adalah memungkinkan aplikasi untuk mendapatkan token dari Layanan Federasi Direktori Aktif tanpa melakukan pertukaran kredensial server backend. Ini memungkinkan aplikasi untuk masuk ke pengguna, mempertahankan sesi, dan mendapatkan token ke API web lain dalam kode JavaScript klien. Ada beberapa pertimbangan keamanan penting yang perlu dipertimbangkan saat menggunakan alur implisit khususnya di sekitar klien.
Jika Anda ingin menggunakan alur implisit dan Layanan Federasi Direktori Aktif untuk menambahkan autentikasi ke aplikasi JavaScript Anda, ikuti langkah-langkah umum di bawah ini.
Diagram protokol
Diagram berikut menunjukkan alur masuk implisit dan bagian setelahnya menjelaskan setiap langkah secara lebih rinci.
Meminta Token ID dan Token Akses
Untuk awalnya memasukkan pengguna ke aplikasi, Anda dapat mengirim permintaan autentikasi OpenID Koneksi dan mendapatkan id_token dan token akses dari titik akhir Ad FS.
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=id_token+token
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&scope=openid
&response_mode=fragment
&state=12345
| Parameter | Wajib/opsional | Deskripsi |
|---|---|---|
| client_id | diperlukan | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
| response_type | diperlukan | Harus menyertakan id_token untuk masuk OpenID Connect. Ini mungkin juga termasuk response_type token. Menggunakan token di sini akan memungkinkan aplikasi Anda untuk menerima token akses segera dari titik akhir otorisasi tanpa harus membuat permintaan kedua ke titik akhir token. |
| redirect_uri | diperlukan | 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 konfigurasi di Layanan Federasi Direktori Aktif. |
| nonce | diperlukan | Nilai yang disertakan dalam permintaan, dibuat oleh aplikasi, yang akan disertakan dalam nilai 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. Hanya diperlukan ketika id_token diminta. |
| cakupan | opsional | Daftar cakupan yang dipisahkan spasi. Untuk Koneksi OpenID, harus menyertakan cakupan openid. |
| sumber daya | opsional | Url API Web Anda. Catatan – Jika menggunakan pustaka klien MSAL, parameter sumber daya tidak dikirim. Sebaliknya url sumber daya dikirim sebagai bagian dari parameter cakupan: scope = [resource url]//[scope values e.g., openid]Jika sumber daya tidak diteruskan di sini atau dalam cakupan AD FS akan menggunakan urn sumber daya default:microsoft:userinfo. kebijakan sumber daya userinfo seperti MFA, Penerbitan, atau kebijakan otorisasi, tidak dapat disesuaikan. |
| response_mode | opsional | Menentukan metode yang harus digunakan untuk menghasilkan hasil token ke aplikasi Anda. Default ke fragment. |
| state | opsional | Nilai yang disertakan dalam permintaan yang juga akan 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. Status ini juga digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada. |
| permintaan | opsional | Menunjukkan jenis interaksi pengguna yang diperlukan. Satu-satunya nilai yang valid saat ini adalah login, dan tidak ada.- prompt=login akan memaksa pengguna untuk memasukkan kredensial mereka pada permintaan itu, meniru akses menyeluruh. - prompt=none adalah sebaliknya - ini akan memastikan bahwa pengguna tidak disajikan dengan perintah interaktif apa pun. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui akses menyeluruh, Layanan Federasi Direktori Aktif akan mengembalikan kesalahan interaction_required. |
| login_hint | opsional | Dapat digunakan untuk mengisi bidang nama pengguna dan alamat email halaman masuk sebelumnya untuk pengguna, jika Anda sudah mengetahui nama pengguna. Seringkali aplikasi akan menggunakan parameter ini selama autentikasi ulang, setelah mengekstrak nama pengguna dari rincian masuk sebelumnya menggunakan upn klaim dari id_token. |
| domain_hint | opsional | Jika disertakan, ini akan melewati proses penemuan berbasis domain yang dilalui pengguna pada halaman masuk, yang mengarah ke pengalaman pengguna yang sedikit lebih efisien. |
Pada titik ini, pengguna diminta untuk memasukkan kredensial mereka dan menyelesaikan autentikasi. Setelah pengguna mengautentikasi, titik akhir otorisasi Ad FS akan mengembalikan respons ke aplikasi Anda di redirect_uri yang ditunjukkan, menggunakan metode yang ditentukan dalam parameter response_mode.
Respons berhasil
Respons yang berhasil menggunakan response_mode=fragment and response_type=id_token+token terlihat seperti berikut ini
// Line breaks for legibility only
GET https://localhost/myapp/#
access_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZEstZnl0aEV...
&token_type=Bearer
&expires_in=3599
&scope=openid
&id_token=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZstZnl0aEV1Q...
&state=12345
| Parameter | Deskripsi |
|---|---|
| access_token | Disertakan jika response_type menyertakan token. |
| token_type | Disertakan jika response_type menyertakan token. Akan selalu menjadi Pembawa. |
| expires_in | Disertakan jika response_type menyertakan token. Menunjukkan jumlah detik token valid, untuk tujuan penembolokan. |
| cakupan | Menunjukkan cakupan tempat access_token akan valid. |
| id_token | Disertakan jika response_type menyertakan id_token. JSON Web Token (JWT) yang 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. |
| status | Jika parameter status disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons sama persis. |
Melakukan refresh token
Hibah yang tersirat tidak menyediakan token refresh. Keduanya id_tokens dan access_tokens akan kedaluwarsa setelah waktu yang singkat, sehingga aplikasi Anda harus siap untuk merefresh token ini secara berkala. Untuk menyegarkan salah satu jenis token, Anda dapat melakukan permintaan iframe tersembunyi yang sama dari yang di atas menggunakan parameter prompt=none untuk mengontrol perilaku platform identitas. Jika Anda ingin menerima new id_token, pastikan untuk menggunakan response_type=id_token.
Alur pemberian kode otorisasi
Pemberian kode otorisasi OAuth 2.0 dapat digunakan di aplikasi web untuk mendapatkan akses ke sumber daya yang dilindungi, seperti API web. 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. Alur ini memungkinkan aplikasi memperoleh access_tokens dengan aman yang dapat digunakan untuk mengakses sumber daya yang mempercayai Layanan Federasi Direktori Aktif.
Diagram Protokol
Pada tingkat tinggi, alur autentikasi untuk aplikasi asli 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:
// Line breaks for legibility only
https://adfs.contoso.com/adfs/oauth2/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&resource=https://webapi.com/
&scope=openid
&state=12345
| Parameter | Wajib/opsional | Deskripsi |
|---|---|---|
| client_id | diperlukan | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
| response_type | diperlukan | Harus menyertakan kode untuk alur kode otorisasi. |
| redirect_uri | diperlukan | Aplikasi redirect_uri Anda, di mana respon autentikasinya dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu redirect_uris yang Anda daftarkan di Layanan Federasi Direktori Aktif untuk klien. |
| sumber daya | opsional | Url API Web Anda. Catatan – Jika menggunakan pustaka klien MSAL, parameter sumber daya tidak dikirim. Sebaliknya url sumber daya dikirim sebagai bagian dari parameter cakupan: scope = [resource url]//[scope values e.g., openid]Jika sumber daya tidak diteruskan di sini atau dalam cakupan AD FS akan menggunakan urn sumber daya default:microsoft:userinfo. kebijakan sumber daya userinfo seperti MFA, Penerbitan, atau kebijakan otorisasi, tidak dapat disesuaikan. |
| cakupan | opsional | Daftar cakupan yang dipisahkan spasi. |
| response_mode | opsional | Menentukan metode yang harus digunakan untuk menghasilkan hasil token ke aplikasi Anda. Dapat berupa salah satu hal berikut: - kueri - fragmen - form_postquery menyediakan kode sebagai parameter string kueri pada URI pengalihan Anda. Jika Anda meminta kode, Anda bisa menggunakan kueri, fragmen, atau form_post. form_post mengeksekusi POST yang berisi kode ke URI pengalihan Anda. |
| state | opsional | Nilai yang disertakan dalam permintaan yang juga akan 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. Status ini juga digunakan untuk mengkodekan informasi tentang status pengguna di aplikasi sebelum permintaan autentikasi muncul, seperti halaman atau tampilan tempat mereka berada. |
| permintaan | opsional | Menunjukkan jenis interaksi pengguna yang diperlukan. Satu-satunya nilai yang valid saat ini adalah login, dan tidak ada.- prompt=login akan memaksa pengguna untuk memasukkan kredensial mereka pada permintaan itu, meniru akses menyeluruh. - prompt=none adalah sebaliknya - ini akan memastikan bahwa pengguna tidak disajikan dengan perintah interaktif apa pun. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui akses menyeluruh, Layanan Federasi Direktori Aktif akan mengembalikan kesalahan interaction_required. |
| 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. Seringkali aplikasi akan menggunakan parameter ini selama autentikasi ulang, setelah mengekstrak nama pengguna dari rincian masuk sebelumnya menggunakan upnklaim dari id_token. |
| domain_hint | opsional | Jika disertakan, ini akan melewati proses penemuan berbasis domain yang dilalui pengguna pada halaman masuk, yang mengarah ke pengalaman pengguna yang sedikit lebih efisien. |
| code_challenge_method | opsional | Metode yang digunakan untuk mengodekan code_verifier untuk parameter code_challenge. Dapat berupa salah satu nilai berikut: - biasa - S256 Jika dikecualikan, code_challenge diasumsikan sebagai teks biasa jika code_challenge disertakan. Layanan Federasi Direktori Aktif mendukung S256 dan biasa. Untuk informasi selengkapnya, lihat PKCE RFC. |
| code_challenge | opsional | Digunakan untuk mengamankan pemberian kode otorisasi melalui Proof Key for Code Exchange (PKCE) dari klien asli. Diperlukan jika code_challenge_method disertakan. Untuk informasi selengkapnya, lihat PKCE RFC |
Pada titik ini, pengguna diminta untuk memasukkan kredensial mereka dan menyelesaikan autentikasi. Setelah pengguna mengautentikasi, Layanan Federasi Direktori Aktif akan mengembalikan respons ke aplikasi Anda pada yang ditunjukkan redirect_uri, menggunakan metode yang ditentukan dalam response_mode parameter .
Respons berhasil
Respons yang berhasil menggunakan response_mode=query terlihat seperti:
GET https://adfs.contoso.com/common/oauth2/nativeclient?
code=AwABAAAAvPM1KaPlrEqdFSBzjqfTGBCmLdgfSTLEMPGYuNHSUYBrq...
&state=12345
| Parameter | Deskripsi |
|---|---|
| kode | authorization_code yang diminta oleh 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. |
| state | Jika parameter state disertakan dalam permintaan, maka nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik. |
Minta Token Akses
Sekarang setelah Anda memperoleh authorization_code dan telah diberikan izin oleh pengguna, Anda dapat menukarkan kode dengan sumber daya yang access_token diinginkan. Lakukan ini dengan mengirim permintaan POST ke titik akhir /token:
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com/
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Parameter | Diperlukan/opsional | Deskripsi |
|---|---|---|
| client_id | diperlukan | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
| grant_type | diperlukan | Harus authorization_code untuk aliran kode otorisasi. |
| kode | diperlukan | authorization_code yang Anda peroleh di bagian pertama alur. |
| redirect_uri | diperlukan | Nilai redirect_uri yang sama yang digunakan untuk memperoleh authorization_code. |
| client_secret | diperlukan untuk aplikasi web | Rahasia aplikasi yang Anda buat selama pendaftaran aplikasi di Layanan Federasi Direktori Aktif. Anda tidak boleh menggunakan rahasia aplikasi di aplikasi asli karena client_secrets tidak dapat disimpan dengan andal di perangkat. Diperlukan untuk aplikasi web dan API web, yang memiliki kemampuan untuk menyimpan client_secret aman di sisi server. Rahasia klien harus dienkodekan dengan URL sebelum dikirim. Aplikasi ini juga dapat menggunakan autentikasi berbasis kunci dengan menandatangani JWT dan menambahkannya sebagai parameter client_assertion. |
| 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. Catatan – Berlaku untuk Layanan Federasi Direktori Aktif 2019 dan yang lebih baru |
Respons berhasil
Respons token yang berhasil akan terlihat seperti:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDRkMTFhMi1mODE0LTQ2YTctOD...",
}
| Parameter | Deskripsi |
|---|---|
| access_token | Token akses yang diminta. Aplikasi ini dapat menggunakan token ini untuk mengautentikasi ke sumber daya aman (WEB API). |
| token_type | Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung AD FS adalah Bearer. |
| expires_in | Berapa lama token akses berlaku/valid (dalam detik). |
| refresh_token | Token refresh OAuth 2.0. 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. |
| refresh_token_expires_in | Berapa lama token refresh valid (dalam detik). |
| id_token | JSON Web Token (JWT). Aplikasi dapat memecahkan kode 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. |
Gunakan token akses
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Flow Pemberian Token Refresh
Access_tokens berumur pendek, dan Anda harus menyegarkan mereka setelah kedaluwarsa untuk terus mengakses sumber daya. Anda dapat melakukannya dengan mengirimkan permintaan POST lain ke /token titik akhir, kali ini memberikan refresh_token alih-alih kode. Token refresh valid untuk semua izin yang token aksesnya telah diterima klien Anda.
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.
Meskipun token refresh tidak dicabut ketika digunakan untuk memperoleh token akses baru, Anda diharapkan untuk membuang token refresh lama. Sesuai 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 ke klien." Layanan Federasi Direktori Aktif mengeluarkan token refresh saat masa pakai token refresh baru lebih lama dari masa pakai token refresh sebelumnya. Untuk melihat informasi tambahan tentang masa pakai token refresh Layanan Federasi Direktori Aktif, kunjungi Pengaturan Akses Menyeluruh Layanan Federasi Direktori Aktif.
// Line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh // NOTE: Only required for confidential clients (web apps)
| Parameter | Wajib/opsional | Deskripsi |
|---|---|---|
| client_id | diperlukan | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
| grant_type | diperlukan | Harus refresh_token untuk kaki ini dari aliran kode otorisasi. |
| sumber daya | opsional | Url API Web Anda. Catatan – Jika menggunakan pustaka klien MSAL, parameter sumber daya tidak dikirim. Sebaliknya url sumber daya dikirim sebagai bagian dari parameter cakupan: scope = [resource url]//[scope values e.g., openid]Jika sumber daya tidak diteruskan di sini atau dalam cakupan AD FS akan menggunakan urn sumber daya default:microsoft:userinfo. kebijakan sumber daya userinfo seperti MFA, Penerbitan, atau kebijakan otorisasi, tidak dapat disesuaikan. |
| cakupan | opsional | Daftar cakupan yang dipisahkan spasi. |
| refresh_token | diperlukan | Token refresh asli 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 native, karena client_secrets tidak dapat disimpan dengan andal di perangkat. Diperlukan untuk aplikasi web dan API web, yang memiliki kemampuan untuk menyimpan client_secret aman di sisi server. Aplikasi ini juga dapat menggunakan autentikasi berbasis kunci dengan menandatangani JWT dan menambahkannya sebagai parameter client_assertion. |
Respons berhasil
Respons token yang berhasil akan terlihat seperti:
{
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
"token_type": "Bearer",
"expires_in": 3599,
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"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 AD FS adalah Bearer |
| expires_in | Berapa lama token akses berlaku/valid (dalam detik). |
| cakupan | Cakupan yang berlaku untuk access_token. |
| refresh_token | Token refresh OAuth 2.0. 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. |
| refresh_token_expires_in | Berapa lama token refresh valid (dalam detik). |
| id_token | JSON Web Token (JWT). Aplikasi dapat memecahkan kode 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. |
Alur Atas Nama
Aliran On-Behalf-Of (OBO) OAuth 2.0 melayani kasus penggunaan di mana aplikasi memanggil API layanan/web, yang pada gilirannya perlu memanggil layanan/API web lain. Idenya adalah untuk menyebarluaskan identitas pengguna dan izin yang didelegasikan melalui rantai permintaan. Agar layanan tingkat menengah membuat permintaan terautentikasi ke layanan hilir, layanan perlu mengamankan token akses dari Layanan Federasi Direktori Aktif, atas nama pengguna.
Diagram protokol
Asumsikan bahwa pengguna telah diautentikasi pada aplikasi menggunakan alur pemberian kode otorisasi OAuth 2.0 yang dijelaskan di atas. Pada titik ini, aplikasi memiliki token akses untuk API A (token A) dengan klaim pengguna dan persetujuan untuk mengakses API web tingkat menengah (API A). Pastikan klien meminta cakupan user_impersonation dalam token. Sekarang, API A perlu membuat permintaan yang diautentikasi ke API web hilir (API B).
Langkah-langkah berikutnya merupakan aliran OBO dan dijelaskan dengan bantuan diagram berikut.
- Aplikasi klien membuat permintaan ke API A dengan token A. Catatan: Saat mengonfigurasi alur OBO di Layanan Federasi Direktori Aktif, pastikan cakupan
user_impersonationdipilih dan klien melakukan cakupan permintaanuser_impersonationdalam permintaan. - API A mengautentikasi ke titik akhir penerbitan token LAYANAN Federasi Direktori Aktif dan meminta token untuk mengakses API B. Catatan: Saat mengonfigurasi alur ini di LAYANAN Federasi Direktori Aktif, pastikan API A juga terdaftar sebagai aplikasi server dengan clientID yang memiliki nilai yang sama dengan ID sumber daya di API A.
- Titik akhir penerbitan token Layanan Federasi Direktori Aktif memvalidasi kredensial API A dengan token A dan mengeluarkan token akses untuk API B (token B).
- Token B diatur di header otorisasi permintaan ke API B.
- Data dari sumber daya aman dikembalikan oleh API B.
Permintaan token akses layanan-ke-layanan
Untuk meminta token akses, buat HTTP POST ke titik akhir token AD FS dengan parameter berikut.
Kasus pertama: Mengakses permintaan token dengan rahasia bersama
Saat menggunakan rahasia bersama, permintaan token akses layanan ke layanan berisi parameter berikut:
| Parameter | Wajib/opsional | Deskripsi |
|---|---|---|
| grant_type | diperlukan | Jenis permintaan token. Untuk permintaan yang menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer. |
| client_id | diperlukan | ID Klien yang Anda konfigurasi saat mendaftarkan API Web pertama Anda sebagai aplikasi server (aplikasi tingkat menengah). Ini harus sama dengan ID sumber daya yang digunakan pada leg ke-1 yaitu url API Web pertama. |
| client_secret | diperlukan | Rahasia aplikasi yang Anda buat selama pendaftaran aplikasi server di Layanan Federasi Direktori Aktif. |
| assertion | diperlukan | Nilai token akses yang digunakan dalam permintaan. |
| requested_token_use | diperlukan | Menentukan bagaimana permintaan harus diproses. Dalam alur OBO, nilai harus diatur ke on_behalf_of |
| sumber daya | diperlukan | ID sumber daya yang disediakan saat mendaftarkan API Web pertama sebagai aplikasi server (Aplikasi tingkat menengah). ID sumber daya harus menjadi url Aplikasi tingkat menengah API Web kedua yang akan memanggil atas nama klien. |
| cakupan | opsional | Daftar ruang lingkup yang dipisahkan untuk permintaan token. |
Contoh
Berikut ini HTTP POST meminta token akses dan token refresh
//line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
&client_id=https://webapi.com/
&client_secret=BYyVnAt56JpLwUcyo47XODd
&assertion=eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIm…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope=openid
Kasus kedua: Permintaan token akses dengan sertifikat
Permintaan token akses layanan ke layanan dengan sertifikat berisi parameter berikut:
| Parameter | wajib/Opsional | Deskripsi |
|---|---|---|
| grant_type | diperlukan | Jenis permintaan token. Untuk permintaan yang menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer. |
| client_id | diperlukan | ID Klien yang Anda konfigurasi saat mendaftarkan API Web pertama Anda sebagai aplikasi server (aplikasi tingkat menengah). Ini harus sama dengan ID sumber daya yang digunakan pada leg ke-1 yaitu url API Web pertama. |
| client_assertion_type | diperlukan | Nilai harus urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| client_assertion | diperlukan | Pernyataan (token web JSON) yang perlu Anda buat dan tanda tangani dengan sertifikat yang Anda daftarkan sebagai kredensial untuk aplikasi Anda. |
| assertion | diperlukan | Nilai token akses yang digunakan dalam permintaan. |
| requested_token_use | diperlukan | Menentukan bagaimana permintaan harus diproses. Dalam alur OBO, nilai harus diatur ke on_behalf_of |
| sumber daya | diperlukan | ID sumber daya yang disediakan saat mendaftarkan API Web pertama sebagai aplikasi server (Aplikasi tingkat menengah). ID sumber daya harus menjadi url Aplikasi tingkat menengah API Web kedua yang akan memanggil atas nama klien. |
| cakupan | opsional | Daftar ruang lingkup yang dipisahkan untuk permintaan token. |
Perhatikan bahwa parameter hampir sama seperti dalam kasus permintaan dengan rahasia bersama kecuali bahwa parameter client_secret digantikan oleh dua parameter: client_assertion_type dan client_assertion.
Contoh
HTTP POST berikut meminta token akses untuk API Web dengan sertifikat.
// line breaks for legibility only
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&client_id= https://webapi.com/
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNS…
&resource=https://secondwebapi.com/
&requested_token_use=on_behalf_of
&scope= openid
Respons token akses layanan ke layanan
Respons sukses adalah respons JSON OAuth 2.0 dengan parameter berikut.
| Parameter | Deskripsi |
|---|---|
| token_type | Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung AD FS adalah Bearer. |
| scope | Ruang lingkup akses yang diberikan dalam token. |
| expires_in | Masa berlaku token akses (dalam detik), bahwa token akses adalah sah. |
| access_token | Token akses yang diminta. Layanan panggilan dapat menggunakan token ini untuk mengautentikasi ke layanan penerimaan. |
| id_token | JSON Web Token (JWT). Aplikasi dapat memecahkan kode 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. |
| refresh_token | Token refresh untuk token akses yang diminta. Layanan panggilan dapat menggunakan token ini untuk meminta token akses lain setelah token akses saat ini kedaluwarsa. |
| Refresh_token_expires_in | Lamanya waktu, dalam detik, bahwa token refresh valid. |
Contoh respons keberhasilan
Contoh berikut menunjukkan respons keberhasilan terhadap permintaan token akses untuk API web.
{
"token_type": "Bearer",
"scope": openid,
"expires_in": 3269,
"access_token": "eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1t"
"id_token": "aWRfdG9rZW49ZXlKMGVYQWlPaUpLVjFRaUxDSmhiR2NpT2lKU1V6STFOa"
"refresh_token": "OAQABAAAAAABnfiG…"
"refresh_token_expires_in": 28800,
}
Gunakan token akses untuk mengakses sumber daya aman Sekarang layanan tingkat menengah dapat menggunakan token yang diperoleh di atas untuk membuat permintaan terautentikasi ke API web hilir, dengan mengatur token di header Otorisasi.
Contoh
GET /v1.0/me HTTP/1.1
Host: https://secondwebapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJub25jZSI6IkFRQUJBQUFBQUFCbmZpRy1tQ…
Alur pemberian info masuk klien
Anda dapat menggunakan pemberian kredensial klien OAuth 2.0 yang ditentukan dalam RFC 6749, untuk mengakses sumber daya yang dihosting web dengan menggunakan identitas aplikasi. Jenis pemberian ini umumnya digunakan untuk interaksi server-ke-server yang harus dijalankan di latar belakang, tanpa interaksi langsung dengan pengguna. Jenis aplikasi ini sering disebut sebagai daemon atau akun layanan.
Alur pemberian kredensial klien OAuth 2.0 mengizinkan layanan web (klien rahasia) untuk menggunakan kredesialnya sendiri, bukan meniru identitas pengguna, untuk mengautentikasi saat memanggil layanan web lain. Dalam skenario ini, klien biasanya adalah layanan web tingkat menengah, layanan daemon, atau situs web. Untuk tingkat jaminan yang lebih tinggi, Layanan Federasi Direktori Aktif juga memungkinkan layanan panggilan untuk menggunakan sertifikat (bukan rahasia bersama) sebagai kredensial.
Diagram protokol
Diagram berikut menunjukkan alur pemberian kredensial klien.
Meminta token
Untuk mendapatkan token dengan menggunakan pemberian kredensial klien, kirim POST permintaan ke titik akhir Layanan Federasi Direktori Aktif /token:
Kasus pertama: Mengakses permintaan token dengan rahasia bersama
POST /adfs/oauth2/token HTTP/1.1
//Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f1264799865
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
| Parameter | Wajib/opsional | Deskripsi |
|---|---|---|
| client_id | diperlukan | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
| cakupan | opsional | Daftar lingkup yang dipisahkan cakupan yang membutuhkan persetujuan. |
| client_secret | diperlukan | Rahasia klien yang Anda buat untuk aplikasi Anda di portal pendaftaran aplikasi. Rahasia klien harus dienkodekan dengan URL sebelum dikirim. |
| grant_type | diperlukan | Harus diatur ke client_credentials. |
Kasus kedua: Meminta token akses dengan sertifikat
POST /adfs/oauth2/token HTTP/1.1
// Line breaks for clarity
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
&client_id=97e0a5b7-d745-40b6-94fe-5f77d35c6e05
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsIng1dCI6Imd4OHRHeXN5amNScUtqRlBuZDdSRnd2d1pJMCJ9.eyJ{a lot of characters here}M8U3bSUKKJDEg
&grant_type=client_credentials
| Parameter | Wajib/opsional | Deskripsi |
|---|---|---|
| client_assertion_type | diperlukan | Nilai harus diatur ke urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
| client_assertion | diperlukan | Pernyataan (token web JSON) yang perlu Anda buat dan tanda tangani dengan sertifikat yang Anda daftarkan sebagai kredensial untuk aplikasi Anda. |
| grant_type | diperlukan | Harus diatur ke client_credentials. |
| client_id | opsional | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. Ini adalah bagian dari client_assertion, sehingga tidak perlu diteruskan di sini. |
| cakupan | opsional | Daftar lingkup yang dipisahkan cakupan yang membutuhkan persetujuan. |
Menggunakan token
Sekarang setelah Anda memperoleh token, gunakan token untuk membuat permintaan ke sumber daya. Ketika token kedaluwarsa, ulangi permintaan ke titik akhir /token untuk memperoleh token akses baru.
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Alur pemberian info masuk kata sandi pemilik sumber daya (Tidak disarankan)
Pemberian kredensial kata sandi pemilik sumber daya (ROPC) memungkinkan aplikasi untuk masuk ke pengguna dengan langsung menangani kata sandi mereka. Alur ROPC memerlukan tingkat kepercayaan dan paparan pengguna yang tinggi dan Anda hanya boleh menggunakan alur ini ketika alur lain yang lebih aman dan tidak dapat digunakan.
Diagram protokol
Diagram berikut menunjukkan alur ROPC.
Permintaan otorisasi
Alur ROPC adalah satu permintaan—ini mengirimkan identifikasi klien dan kredensial pengguna ke IDP, lalu menerima token sebagai imbalannya. Klien harus meminta alamat email (UPN) dan kata sandi pengguna sebelum melakukannya. Segera setelah permintaan berhasil, klien harus dengan aman merilis informasi masuk pengguna dari memori. Informasi masuk tidak pernah boleh disimpan.
// Line breaks and spaces are for legibility only.
POST /adfs/oauth2/token HTTP/1.1
Host: https://adfs.contoso.com
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope= openid
&username=myusername@contoso.com
&password=SuperS3cret
&grant_type=password
| Parameter | Wajib/opsional | Deskripsi |
|---|---|---|
| client_id | diperlukan | ID Klien |
| grant_type | diperlukan | Harus diatur ke kata sandi. |
| Nama pengguna | diperlukan | Masukkan alamat email pengguna. |
| kata sandi | diperlukan | Kata sandi pengguna. |
| cakupan | opsional | Daftar cakupan yang dipisahkan spasi. |
Respons autentikasi berhasil
Contoh berikut menunjukkan pembaruan repositori yang berhasil:
{
"token_type": "Bearer",
"scope": "openid",
"expires_in": 3599,
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIn...",
"refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
"refresh_token_expires_in": 28800,
"id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJub25lIn0.eyJhdWQiOiIyZDR..."
}
| Parameter | Deskripsi |
|---|---|
| token_type | Selalu atur ke Pembawa. |
| cakupan | Jika token akses diberikan, parameter ini mencantumkan cakupan yang berlaku untuk token akses. |
| expires_in | Jumlah detik yang berlaku untuk token akses yang disertakan. |
| access_token | Diterbitkan untuk cakupan yang diminta. |
| id_token | JSON Web Token (JWT). Aplikasi dapat memecahkan kode 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. |
| refresh_token_expires_in | Jumlah detik yang berlaku untuk token refresh yang disertakan. |
| refresh_token | Dikeluarkan jika parameter cakupan asli disertakan offline_access. |
Anda dapat menggunakan token refresh untuk memperoleh token akses baru dan token refresh menggunakan alur yang sama yang dijelaskan di bagian alur pemberian kode autentikasi di atas.
Aliran kode perangkat
Pemberian kode perangkat memungkinkan pengguna untuk masuk ke perangkat yang dibatasi input seperti TV pintar, perangkat IoT, atau printer. Untuk mengaktifkan alur ini, pengguna perangkat akan diarahkan untuk mengunjungi halaman web di browser mereka di perangkat lain untuk masuk. Setelah pengguna masuk, perangkat dapat mendapatkan token akses dan menyegarkan token sesuai kebutuhan.
Diagram protokol
Seluruh alur kode perangkat terlihat mirip dengan diagram berikutnya. Kami menjelaskan masing-masing langkah dalam artikel ini nanti.
Permintaan otorisasi perangkat
Klien harus terlebih dahulu memeriksa dengan server autentikasi untuk perangkat dan kode pengguna yang digunakan untuk memulai autentikasi. Klien mengumpulkan permintaan ini dari titik akhir /devicecode. Dalam permintaan ini, klien juga harus menyertakan izin yang harus didapatkan dari pengguna. Sejak permintaan ini dikirim, pengguna hanya memiliki 15 menit untuk masuk (nilai yang biasa untuk expires_in), jadi hanya buat permintaan ini ketika pengguna telah menunjukkan bahwa mereka siap untuk masuk.
// Line breaks are for legibility only.
POST https://adfs.contoso.com/adfs/oauth2/devicecode
Content-Type: application/x-www-form-urlencoded
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
scope=openid
| Parameter | Kondisi | Deskripsi |
|---|---|---|
| client_id | diperlukan | ID Aplikasi (klien) yang ditetapkan LAYANAN Federasi Direktori Aktif ke aplikasi Anda. |
| cakupan | opsional | Daftar cakupan yang dipisahkan spasi. |
Respons otorisasi perangkat
Respons yang berhasil adalah objek JSON yang berisi informasi yang diperlukan untuk memungkinkan pengguna masuk.
| Parameter | Deskripsi |
|---|---|
| device_code | Untai panjang digunakan untuk memverifikasi sesi antara klien dan server otorisasi. Klien menggunakan parameter ini untuk meminta token akses dari server otorisasi. |
| user_code | Untai pendek ditunjukkan kepada pengguna yang digunakan untuk mengidentifikasi sesi pada perangkat sekunder. |
| verification_uri | URI yang harus digunakan pengguna dengan user_code untuk masuk. |
| verification_uri_complete | URI yang harus digunakan pengguna dengan user_code untuk masuk. Ini telah diisi sebelumnya dengan user_code sehingga pengguna tidak perlu memasukkan user_code |
| expires_in | Jumlah detik sebelum device_code dan user_code kedaluwarsa. |
| interval | Jumlah detik di mana klien harus menunggu di antara permintaan polling. |
| pesan | Untai yang dapat dibaca manusia dengan petunjuk untuk pengguna. Ini dapat dilokalkan dengan menyertakan parameter kueri dalam permintaan formulir ?mkt=xx-XX, mengisi kode budaya bahasa yang sesuai. |
Mengautentikasi pengguna
Setelah menerima user_code dan verification_uri, klien menampilkannya kepada pengguna, menginstruksikan mereka untuk masuk menggunakan ponsel atau browser PC mereka. Selain itu, klien dapat menggunakan kode QR atau mekanisme serupa untuk menampilkan verfication_uri_complete, yang akan mengambil langkah memasukkan user_code untuk pengguna. Saat pengguna mengautentikasi di verification_uri, klien harus melakukan polling titik akhir /token untuk token yang diminta menggunakan device_code.
POST https://adfs.contoso.com /adfs/oauth2/token
Content-Type: application/x-www-form-urlencoded
grant_type: urn:ietf:params:oauth:grant-type:device_code
client_id: 6731de76-14a6-49ae-97bc-6eba6914391e
device_code: GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8
| Parameter | diperlukan | Deskripsi |
|---|---|---|
| grant_type | diperlukan | Harus urn:ietf:params:oauth:grant-type:device_code |
| client_id | diperlukan | Harus cocok dengan client_id yang digunakan dalam permintaan awal. |
| kode | diperlukan | device_code dikembalikan dalam permintaan otorisasi perangkat. |
Respons autentikasi berhasil
Respons token yang berhasil akan terlihat seperti:
| Parameter | Deskripsi |
|---|---|
| token_type | Selalu "Pembawa. |
| cakupan | Jika token akses dikembalikan, ini mencantumkan cakupan yang berlaku untuk token akses. |
| expires_in | Jumlah detik sebelum token akses yang disertakan valid. |
| access_token | Diterbitkan untuk cakupan yang diminta. |
| id_token | Dikeluarkan jika parameter cakupan asli menyertakan cakupan openid. |
| refresh_token | Dikeluarkan jika parameter cakupan asli disertakan offline_access. |
| refresh_token_expires_in | Jumlah detik sebelum token refresh yang disertakan valid. |
Konten terkait
Lihat Pengembangan Layanan Federasi Direktori Aktif untuk daftar lengkap artikel panduan, yang menyediakan instruksi langkah demi langkah tentang menggunakan alur terkait.