Alur Koneksi/OAuth OpenID Layanan Federasi Direktori Aktif dan Skenario Aplikasi
Berlaku untuk Layanan Federasi Direktori Aktif 2019 dan yang lebih baru
Skenario | Panduan skenario menggunakan sampel | Alur/Hibah OAuth 2.0 | Tipe Klien |
---|---|---|---|
Aplikasi satu halaman | Sampel menggunakan MSAL | Implisit | Publik |
Aplikasi Web yang memasukkan pengguna | Sampel menggunakan OWIN | Kode Otorisasi | Publik, Rahasia |
Aplikasi Asli memanggil API Web | Sampel menggunakan MSAL | Kode Otorisasi | Publik |
Web App memanggil WEB API | Sampel menggunakan MSAL | Kode Otorisasi | Rahasia |
API Web memanggil API web lain atas nama (OBO) pengguna | Sampel menggunakan MSAL | Atas nama | Aplikasi web bertindak sebagai Rahasia |
Aplikasi Daemon memanggil API Web | Informasi masuk klien | Rahasia | |
Aplikasi Web memanggil API Web menggunakan kredensial pengguna | Kredensial kata sandi pemilik sumber daya | Publik, Rahasia | |
Aplikasi Tanpa Browser memanggil API Web | Kode perangkat | Publik, Rahasia |
Aliran hibah implisit
Catatan
Microsoft sangat merekomendasikan migrasi ke MICROSOFT Entra ID alih-alih meningkatkan ke versi LAYANAN Federasi Direktori Aktif yang lebih baru. Untuk informasi selengkapnya tentang alur pemberian implisit di ID Microsoft Entra, lihat Alur pemberian izin implisit di platform identitas Microsoft.
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. Alur 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 diperhitungkan 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 bagian berikut.
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 mengakses token dari titik akhir Layanan Federasi Direktori Aktif.
// 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 | Diperlukan/Opsional | Deskripsi |
---|---|---|
client_id | wajib diisi | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
response_type | wajib diisi | Harus menyertakan id_token untuk masuk OpenID Connect. Ini mungkin juga termasuk response_type token . Menggunakan token di sini memungkinkan aplikasi Anda untuk menerima token akses segera dari titik akhir otorisasi tanpa harus membuat permintaan kedua ke titik akhir token. |
redirect_uri | wajib diisi | 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 | wajib diisi | Nilai yang disertakan dalam permintaan, yang dihasilkan oleh aplikasi yang akan disertakan dalam id_token yang dihasilkan sebagai klaim. Aplikasi kemudian dapat memverifikasi nilai ini untuk meminimalkan serangan replay token. Biasanya, nilainya adalah string acak dan unik yang dapat digunakan untuk mengidentifikasi asal permintaan. 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. Sebagai gantinya 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 menggunakan urn sumber daya default:microsoft:userinfo. kebijakan sumber daya userinfo seperti kebijakan MFA, Penerbitan, atau otorisasi, tidak dapat disesuaikan. |
response_mode | opsional | Menentukan metode yang akan digunakan untuk mengirim token yang dihasilkan kembali 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. |
perintah | opsional | Menunjukkan jenis interaksi pengguna yang diperlukan. Satu-satunya nilai yang valid saat ini adalah masuk, dan tidak ada.- prompt=login memaksa pengguna untuk memasukkan kredensial mereka pada permintaan tersebut, menilai akses menyeluruh. - prompt=none sebaliknya - ini memastikan bahwa pengguna tidak disajikan dengan perintah interaktif apa pun. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui akses menyeluruh, Ad FS 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 menggunakan parameter ini selama autentikasi ulang, setelah mengekstrak nama pengguna dari rincian masuk sebelumnya menggunakan upn klaim dari id_token . |
petunjuk domain | opsional | Jika disertakan, ini melewati proses penemuan berbasis domain yang dilalui pengguna di halaman masuk, yang mengarah ke pengalaman pengguna yang sedikit lebih efisien. |
Pada titik ini, pengguna diminta untuk memasukkan info masuk mereka dan menyelesaikan autentikasi. Setelah pengguna mengautentikasi, titik akhir otorisasi Ad FS 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 . selalu "Pembawa". |
Berakhir dalam | Disertakan jika response_type menyertakan token . Menunjukkan jumlah detik token valid, untuk tujuan penembolokan. |
cakupan | Menunjukkan cakupan yang access_token nya 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. |
state | Jika parameter status disertakan dalam permintaan, nilai yang sama akan muncul dalam respons. Aplikasi harus memverifikasi bahwa nilai status dalam permintaan dan respons adalah identik. |
Token refresh
Pemberian implisit 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 me-refresh salah satu jenis token, Anda dapat melakukan permintaan iframe tersembunyi yang sama di bagian sebelumnya menggunakan prompt=none
parameter untuk mengontrol perilaku platform identitas. Jika Anda ingin menerima new id_token
, pastikan untuk menggunakan response_type=id_token
.
Alur pemberian kode otorisasi
Catatan
Microsoft sangat merekomendasikan migrasi ke MICROSOFT Entra ID alih-alih meningkatkan ke versi LAYANAN Federasi Direktori Aktif yang lebih baru. Untuk informasi selengkapnya tentang alur pemberian kode otorisasi di ID Microsoft Entra, lihat Alur pemberian kode otorisasi di platform identitas Microsoft.
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 | Diperlukan/Opsional | Deskripsi |
---|---|---|
client_id | wajib diisi | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
response_type | wajib diisi | Harus menyertakan kode untuk alur kode otorisasi. |
redirect_uri | wajib diisi | Aplikasi redirect_uri Anda, di mana respon autentikasinya dapat dikirim dan diterima oleh aplikasi Anda. Ini harus sama persis dengan salah satu 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. Sebagai gantinya 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 menggunakan urn sumber daya default:microsoft:userinfo. kebijakan sumber daya userinfo seperti kebijakan MFA, Penerbitan, atau otorisasi, tidak dapat disesuaikan. |
cakupan | opsional | Daftar cakupan yang dipisahkan spasi. |
response_mode | opsional | Menentukan metode yang akan digunakan untuk mengirim token yang dihasilkan kembali ke aplikasi Anda. Bisa menjadi salah satu metode 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. |
perintah | opsional | Menunjukkan jenis interaksi pengguna yang diperlukan. Satu-satunya nilai yang valid saat ini adalah masuk, dan tidak ada.- prompt=login memaksa pengguna untuk memasukkan kredensial mereka pada permintaan tersebut, menilai akses menyeluruh. - prompt=none sebaliknya - ini memastikan bahwa pengguna tidak disajikan dengan perintah interaktif apa pun. Jika permintaan tidak dapat diselesaikan secara diam-diam melalui akses menyeluruh, Ad FS 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 menggunakan parameter ini selama autentikasi ulang, setelah mengekstrak nama pengguna dari rincian masuk sebelumnya menggunakan upn klaim dari id_token . |
petunjuk domain | opsional | Jika disertakan, ini melewati proses penemuan berbasis domain yang dilalui pengguna di 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 menjadi 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 info masuk mereka dan menyelesaikan autentikasi. Setelah pengguna mengautentikasi, Layanan Federasi Direktori Aktif mengembalikan respons ke aplikasi Anda di 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 ke sumber daya yang access_token
diinginkan. Tukarkan kode 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 | wajib diisi | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
grant_type | wajib diisi | Harus authorization_code untuk aliran kode otorisasi. |
code | wajib diisi | authorization_code yang Anda peroleh di bagian pertama alur. |
redirect_uri | wajib diisi | Nilai redirect_uri yang sama yang digunakan untuk memperoleh authorization_code . |
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. Opsi ini berlaku untuk Layanan Federasi Direktori Aktif 2019 dan yang lebih baru |
Respons berhasil
Respons token yang sukses 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 (API Web). |
token_type | Menunjukkan nilai jenis token. Satu-satunya jenis yang didukung AD FS adalah Bearer. |
Berakhir dalam | Berapa lama token akses berlaku/valid (dalam detik). |
refresh_token | Token refresh OAuth 2.0. Aplikasi dapat menggunakan token ini untuk memperoleh lebih banyak token akses 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 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. |
Gunakan token akses
GET /v1.0/me/messages
Host: https://webapi.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...
Refresh Alur Pemberian Token
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 menyediakan refresh_token alih-alih kode. Token refresh valid untuk semua izin yang telah diterima token akses klien Anda.
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.
Meskipun token refresh tidak dicabut saat digunakan untuk memperoleh token akses baru, Anda diharapkan untuk membuang token refresh lama. Sesuai spesifikasi OAuth 2.0 mengatakan: "Server otorisasi MUNGKIN 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 layanan federasi direktori aktif Akses Menyeluruh Pengaturan.
// 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 | Diperlukan/Opsional | Deskripsi |
---|---|---|
client_id | wajib diisi | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
grant_type | wajib diisi | 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. Sebagai gantinya 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 menggunakan urn sumber daya default:microsoft:userinfo. kebijakan sumber daya userinfo seperti kebijakan MFA, Penerbitan, atau otorisasi, tidak dapat disesuaikan. |
cakupan | opsional | Daftar cakupan yang dipisahkan spasi. |
refresh_token | wajib diisi | 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. Ini tidak boleh digunakan dalam 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. Aplikasi ini juga dapat menggunakan autentikasi berbasis kunci dengan menandatangani JWT dan menambahkannya sebagai parameter client_assertion. |
Respons berhasil
Respons token yang sukses 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 |
Berakhir dalam | 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 lebih banyak token akses 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 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. |
Alur Atas Nama
Catatan
Microsoft sangat merekomendasikan migrasi ke MICROSOFT Entra ID alih-alih meningkatkan ke versi LAYANAN Federasi Direktori Aktif yang lebih baru. Untuk informasi selengkapnya tentang alur Atas Nama di ID Microsoft Entra, lihat Alur Atas Nama di platform identitas Microsoft.
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 bagian sebelumnya. 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_impersonation
dipilih dan klien melakukan cakupan permintaanuser_impersonation
dalam permintaan. - API A mengautentikasi ke titik akhir penerbitan token AD FS 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 LAYANAN Federasi Direktori Aktif dengan parameter berikut.
Kasus pertama: Mengakses permintaan token dengan rahasia bersama
Untuk rahasia bersama, permintaan token akses layanan-ke-layanan berisi parameter berikut:
Parameter | Diperlukan/Opsional | Deskripsi |
---|---|---|
grant_type | wajib diisi | Jenis permintaan token. Untuk permintaan yang menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id | wajib diisi | 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 pertama yaitu, url API Web pertama. |
client_secret | wajib diisi | Rahasia aplikasi yang Anda buat selama pendaftaran aplikasi server di Layanan Federasi Direktori Aktif. |
assertion | wajib diisi | Nilai token akses yang digunakan dalam permintaan. |
requested_token_use | wajib diisi | Menentukan bagaimana permintaan harus diproses. Dalam alur OBO, nilai harus diatur ke on_behalf_of |
sumber daya | wajib diisi | ID sumber daya yang disediakan saat mendaftarkan API Web pertama sebagai aplikasi server (Aplikasi tingkat menengah). ID sumber daya harus menjadi url panggilan Aplikasi tingkat menengah API Web kedua 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: Meminta token akses dengan sertifikat
Permintaan token akses layanan ke layanan dengan sertifikat berisi parameter berikut:
Parameter | wajib/Opsional | Deskripsi |
---|---|---|
grant_type | wajib diisi | Jenis permintaan token. Untuk permintaan yang menggunakan JWT, nilainya harus urn:ietf:params:oauth:grant-type:jwt-bearer. |
client_id | wajib diisi | 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 pertama yaitu, url API Web pertama. |
client_assertion_type | wajib diisi | Nilainya harus urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion | wajib diisi | Pernyataan (token web JSON) yang perlu Anda buat dan tanda tangani dengan sertifikat yang Anda daftarkan sebagai kredensial untuk aplikasi Anda. |
assertion | wajib diisi | Nilai token akses yang digunakan dalam permintaan. |
requested_token_use | wajib diisi | Menentukan bagaimana permintaan harus diproses. Dalam alur OBO, nilai harus diatur ke on_behalf_of |
sumber daya | wajib diisi | ID sumber daya yang disediakan saat mendaftarkan API Web pertama sebagai aplikasi server (Aplikasi tingkat menengah). ID sumber daya harus menjadi url panggilan Aplikasi tingkat menengah API Web kedua atas nama klien. |
cakupan | opsional | Daftar ruang lingkup yang dipisahkan untuk permintaan token. |
Perhatikan bahwa parameter hampir sama. Contoh ini mirip dengan 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. |
cakupan | Ruang lingkup akses yang diberikan dalam token. |
Berakhir dalam | 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 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. |
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 dalam contoh respons sebelumnya 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
Catatan
Microsoft sangat merekomendasikan migrasi ke MICROSOFT Entra ID alih-alih meningkatkan ke versi LAYANAN Federasi Direktori Aktif yang lebih baru. Untuk informasi selengkapnya tentang alur pemberian kredensial klien di ID Microsoft Entra, lihat Alur pemberian kredensial klien di platform identitas Microsoft.
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 /token AD FS:
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 | Diperlukan/Opsional | Deskripsi |
---|---|---|
client_id | wajib diisi | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. |
cakupan | opsional | Daftar lingkup yang dipisahkan cakupan yang membutuhkan persetujuan. |
client_secret | wajib diisi | Rahasia klien yang Anda buat untuk aplikasi Anda di portal pendaftaran aplikasi. Rahasia klien harus dienkodekan dengan URL sebelum dikirim. |
grant_type | wajib diisi | 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 | Diperlukan/Opsional | Deskripsi |
---|---|---|
client_assertion_type | wajib diisi | Nilai harus diatur ke urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion | wajib diisi | Pernyataan (token web JSON) yang perlu Anda buat dan tanda tangani dengan sertifikat yang Anda daftarkan sebagai kredensial untuk aplikasi Anda. |
grant_type | wajib diisi | Harus diatur ke client_credentials . |
client_id | opsional | ID Aplikasi (klien) yang ditetapkan AD FS ke aplikasi Anda. Ini adalah bagian dari client_assertion, jadi 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)
Catatan
Microsoft sangat merekomendasikan migrasi ke MICROSOFT Entra ID alih-alih meningkatkan ke versi LAYANAN Federasi Direktori Aktif yang lebih baru. Untuk informasi selengkapnya tentang alur pemberian kredensial kata sandi pemilik sumber daya di ID Microsoft Entra, lihat Alur pemberian kredensial kata sandi pemilik sumber daya di platform identitas Microsoft.
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 | Diperlukan/Opsional | Deskripsi |
---|---|---|
client_id | wajib diisi | ID klien |
grant_type | wajib diisi | Harus diatur ke kata sandi. |
Nama pengguna | wajib diisi | Masukkan alamat email pengguna. |
kata sandi | wajib diisi | 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. |
Berakhir dalam | Jumlah detik yang berlaku untuk token akses yang disertakan. |
access_token | Diterbitkan untuk cakupan yang diminta. |
id_token | JSON Web Token (JWT). 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. |
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 artikel ini.
Aliran kode perangkat
Catatan
Microsoft sangat merekomendasikan migrasi ke MICROSOFT Entra ID alih-alih meningkatkan ke versi LAYANAN Federasi Direktori Aktif yang lebih baru. Untuk informasi selengkapnya tentang alur kode perangkat di ID Microsoft Entra, lihat Alur kode perangkat di platform identitas Microsoft.
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 nanti dalam artikel ini.
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 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 | wajib diisi | ID Aplikasi (klien) yang ditetapkan AD FS 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 |
Berakhir dalam | 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 klien menerima user_code dan verification_uri, klien menampilkan detail ini 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 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 | wajib diisi | Deskripsi |
---|---|---|
grant_type | wajib diisi | Harus urn:ietf:params:oauth:grant-type:device_code |
client_id | wajib diisi | Harus cocok dengan client_id yang digunakan dalam permintaan awal. |
code | wajib diisi | device_code dikembalikan dalam permintaan otorisasi perangkat. |
Respons autentikasi berhasil
Respons token yang sukses terlihat seperti:
Parameter | Deskripsi |
---|---|
token_type | Selalu "Pembawa". |
cakupan | Jika token akses dikembalikan, token akses akan mencantumkan cakupan token akses yang valid. |
Berakhir dalam | 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.