Konsep AD FS OpenID Connect/OAuth

Berlaku untuk: ✅ Windows Server 2025, ✅ Windows Server 2022, ✅ Windows Server 2019, ✅ Windows Server 2016

Berlaku untuk Layanan Federasi Direktori Aktif (AD FS) 2016 dan yang lebih baru

Aktor autentikasi modern

Actor	Description
Pengguna akhir	Prinsip keamanan (pengguna, aplikasi, layanan, dan grup) yang mengakses sumber daya.
Client	Aplikasi web Anda, diidentifikasi oleh ID kliennya. Klien biasanya adalah pihak yang berinteraksi dengan pengguna akhir, dan klien meminta token dari server otorisasi.
Server otorisasi/Penyedia identitas (IdP)	Server AD FS Anda. Ini bertanggung jawab untuk memverifikasi identitas prinsip keamanan yang ada di direktori organisasi. Ini mengeluarkan token keamanan (token akses pembawa, token ID, dan token refresh) setelah autentikasi yang berhasil dari prinsip keamanan tersebut.
Server sumber daya/Penyedia sumber daya/Pihak yang mengandalkan	Tempat sumber daya atau data berada. Ini mempercayai server otorisasi untuk mengautentikasi dan mengotorisasi klien dengan aman dan menggunakan token akses pembawa untuk memastikan bahwa akses ke sumber daya dapat diberikan.

Diagram berikut menyediakan hubungan paling mendasar antara aktor:

Jenis aplikasi

Jenis Aplikasi	Description	Role
Aplikasi asli	Terkadang disebut klien publik. Ini dimaksudkan untuk menjadi aplikasi klien yang berjalan pada pc atau perangkat dan dengan mana pengguna berinteraksi.	Meminta token dari server otorisasi (AD FS) untuk akses pengguna ke sumber daya. Mengirim permintaan HTTP ke sumber daya yang dilindungi, dengan menggunakan token sebagai header HTTP.
Aplikasi server (aplikasi web)	Aplikasi web yang berjalan di server dan dapat diakses oleh pengguna melalui browser. Karena mampu mempertahankan rahasia atau kredensial kliennya sendiri, terkadang disebut klien rahasia.	Meminta token dari server otorisasi (AD FS) untuk akses pengguna ke sumber daya. Sebelum meminta token, klien (aplikasi web) perlu mengautentikasi dengan menggunakan rahasianya.
web API	Sumber daya akhir yang diakses pengguna. Anggap saja sebagai representasi baru dari pihak yang bergantung.	Mengonsumsi token akses pembawa yang diperoleh oleh klien.

Grup aplikasi

Anda harus menghubungkan grup aplikasi dengan setiap klien OAuth untuk aplikasi asli (native) atau sumber daya API web atau aplikasi web yang dikonfigurasi dengan AD FS. Konfigurasikan klien dalam grup aplikasi untuk mengakses sumber daya dalam grup yang sama. Grup aplikasi dapat memiliki beberapa klien dan sumber daya.

Token keamanan

Autentikasi modern menggunakan jenis token berikut:

id_token: Token JWT yang dikeluarkan oleh server otorisasi (AD FS) dan digunakan oleh klien. Klaim dalam token ID berisi informasi tentang pengguna sehingga klien dapat menggunakannya.
access_token: Token JWT yang dikeluarkan oleh server otorisasi (AD FS) dan dimaksudkan untuk digunakan oleh sumber daya. Klaim 'aud' atau audiens dari token ini harus cocok dengan pengidentifikasi sumber daya atau API web.
refresh_token: Dikeluarkan oleh Active Directory Federation Services untuk digunakan klien saat perlu memperbarui id_token dan access_token. Token tidak terlihat oleh klien dan hanya digunakan oleh AD FS.

Memperbarui masa berlaku token

Masuk sederhana, tidak ada KMSI, perangkat tidak terdaftar: AD FS menerapkan SsoLifetime dan DeviceUsageWindowInDays. Token refresh pertama memiliki lifetime=DeviceUsageWindowInDays atau SsoLifetime, berdasarkan kolom mana yang lebih rendah sehingga tidak ada token refresh lebih lanjut yang dikeluarkan.
KMSI masuk, EnableKmsi=true di AD FS conf dan kmsi=true diteruskan sebagai parameter: AD FS menerapkan KmsiLifetimeMins dengan DeviceUsageWindowInDays. Token refresh pertama memiliki lifetime=DeviceUsageWindowInDays dan setiap permintaan grant_type=refresh_token berikutnya mendapatkan token refresh baru. Proses ini hanya terjadi dengan klien asli atau klien rahasia ditambah autentikasi perangkat.
Perangkat terdaftar, autentikasi perangkat: Layanan Federasi Direktori Aktif menggunakan PersistentSsoLifetimeMins dan DeviceUsageWindowInDays dengan cara yang mirip KMSI. Klien asli dan rahasia harus mendapatkan token refresh baru, berdasarkan autentikasi perangkat.

Untuk mempelajari selengkapnya, lihat dokumentasi sign-on tunggal AD FS.

Scopes

Saat mendaftarkan sumber daya di Layanan Federasi Direktori Aktif, Anda dapat mengonfigurasi cakupan untuk memungkinkan Layanan Federasi Direktori Aktif melakukan tindakan tertentu. Bersama dengan mengonfigurasi cakupan, Anda harus mengirim nilai cakupan dalam permintaan AD FS agar dapat melakukan tindakan. Misalnya, administrator mengonfigurasi cakupan sebagai openid selama pendaftaran sumber daya, dan aplikasi (klien) harus mengirim scope = openid dalam permintaan autentikasi agar AD FS menerbitkan Token ID. Berikut adalah detail tentang lingkup yang tersedia di AD FS:

aza - Jika Anda menggunakan ekstensi protokol OAuth 2.0 untuk klien broker dan jika parameter cakupan berisi cakupan aza, server mengeluarkan token refresh utama baru. Ini menetapkan token di bidang refresh_token pada respons dan mengatur refresh_token_expires_in field ke masa pakai token pembaruan utama yang baru jika diberlakukan.
openid - Memungkinkan aplikasi mengajukan permintaan untuk menggunakan protokol autentikasi openid.
logon_cert - Memungkinkan aplikasi meminta sertifikat masuk yang dapat Anda gunakan untuk masuk secara interaktif pada pengguna yang diautentikasi. Server AD FS menghapus parameter access_token dari respons dan sebagai gantinya menyediakan rantai sertifikat CMS yang dikodekan dalam base64 atau respons PKI lengkap CMC. Untuk informasi selengkapnya, lihat MS-OAPX: Ekstensi protokol OAuth 2.0.
user_impersonation - Meminta token akses atas nama dari AD FS (Active Directory Federation Services). Untuk detail tentang cara menggunakan cakupan ini, lihat Membangun aplikasi bertingkat menggunakan On-Behalf-Of (OBO) dengan OAuth menggunakan AD FS 2016.
allatclaims – Memungkinkan aplikasi meminta klaim dalam token akses untuk ditambahkan ke token ID juga.
vpn_cert - Memungkinkan aplikasi meminta sertifikat VPN, yang membuat koneksi VPN dengan menggunakan autentikasi EAP-TLS. Fitur ini tidak didukung lagi.
email - Memungkinkan aplikasi meminta klaim email untuk pengguna yang masuk.
profile - Memungkinkan aplikasi meminta klaim terkait profil untuk pengguna yang masuk.

Claims

Token keamanan (token akses dan identitas) yang dikeluarkan oleh AD FS berisi klaim, yaitu pernyataan informasi tentang subjek yang telah diautentikasi. Aplikasi dapat menggunakan klaim untuk berbagai tugas, termasuk:

Validasi token
Mengidentifikasi penyewa direktori milik subjek
Menampilkan informasi pengguna
Menentukan otorisasi subjek

Klaim yang ada dalam token keamanan tertentu tergantung pada jenis token, jenis kredensial yang digunakan untuk mengautentikasi pengguna, dan konfigurasi aplikasi.

Alur autentikasi AD FS tingkat tinggi

Diagram alur tingkat tinggi akan disajikan berikut.

AD FS menerima permintaan autentikasi dari klien.
Layanan Federasi Direktori Aktif memvalidasi ID klien dalam permintaan autentikasi dengan ID klien yang diperoleh selama pendaftaran klien dan sumber daya di Layanan Federasi Direktori Aktif. Jika menggunakan klien rahasia, AD FS juga memvalidasi rahasia klien yang disediakan dalam permintaan autentikasi. Layanan Federasi Direktori Aktif juga memvalidasi URI pengalihan Klien.
AD FS mengidentifikasi sumber daya yang ingin diakses klien melalui parameter sumber daya yang diteruskan dalam permintaan autentikasi. Jika Anda menggunakan pustaka klien MSAL, parameter sumber daya tidak dikirim. Sebagai gantinya, URL sumber daya dikirim sebagai bagian dari parameter cakupan: cakupan = [url sumber daya]/[nilai cakupan, misalnya, openid].

Jika sumber daya tidak diteruskan menggunakan parameter sumber daya atau cakupan, Ad FS menggunakan sumber daya default urn:microsoft:userinfo yang kebijakannya, seperti, MFA, penerbitan, atau kebijakan otorisasi, tidak dapat dikonfigurasi.
AD FS selanjutnya memverifikasi apakah klien punya izin untuk mengakses sumber daya. AD FS juga memvalidasi apakah cakupan yang diteruskan dalam permintaan autentikasi sesuai dengan cakupan yang dikonfigurasi saat mendaftarkan sumber daya. Jika klien tidak memiliki izin, atau cakupan yang tepat tidak dikirim dalam permintaan autentikasi, alur autentikasi akan dihentikan.
Setelah izin dan cakupan memvalidasi, AD FS mengautentikasi pengguna dengan menggunakan metode autentikasi yang dikonfigurasi.
Jika metode autentikasi lain diperlukan sesuai kebijakan sumber daya atau kebijakan autentikasi global, AD FS memicu autentikasi tambahan.
Layanan Federasi Direktori Aktif (AD FS) menggunakan autentikasi multifaktor Microsoft Entra atau autentikasi multifaktor pihak ketiga untuk melakukan autentikasi.
Setelah pengguna diautentikasi, AD FS menerapkan aturan klaim. Aturan klaim menentukan klaim yang dikirim ke sumber daya sebagai bagian dari token keamanan. Layanan Federasi Direktori Aktif (AD FS) juga menerapkan kebijakan kontrol akses yang mengonfirmasi bahwa pengguna memenuhi kondisi yang diperlukan untuk mengakses sumber daya.
Selanjutnya, AD FS menghasilkan akses dan memperbarui token. Layanan Federasi Direktori Aktif juga menghasilkan token ID.
AD FS menerima permintaan autentikasi.
Jika Anda menyertakan scope = allatclaims dalam permintaan autentikasi, ini menyesuaikan token ID untuk menyertakan klaim dalam token akses berdasarkan aturan klaim yang ditentukan.
Setelah token yang diperlukan dihasilkan dan disesuaikan, Layanan Federasi Direktori Aktif merespons klien dan menyertakan token. Respons token ID hanya disertakan dalam respons jika permintaan autentikasi menyertakan scope = openid. Klien selalu bisa mendapatkan token ID setelah autentikasi dengan menggunakan titik akhir token.

Jenis pustaka

Gunakan dua jenis pustaka dengan AD FS.

Pustaka klien: Klien asli dan aplikasi server menggunakan pustaka klien untuk mendapatkan token akses untuk memanggil sumber daya seperti API web. Microsoft Authentication Library (MSAL) adalah pustaka klien terbaru yang direkomendasikan ketika Anda menggunakan Active Directory Federation Services (AD FS) 2019.
Pustaka middleware server: Aplikasi web menggunakan pustaka middleware server untuk otentikasi pengguna. API Web menggunakan pustaka middleware server untuk memvalidasi token yang dikirim oleh klien asli atau oleh server lain. Antarmuka Web Terbuka untuk .NET (OWIN) adalah pustaka middleware yang direkomendasikan.

Menyesuaikan token ID (klaim tambahan dalam token ID)

Dalam skenario tertentu, ada kemungkinan bahwa klien aplikasi web memerlukan klaim tambahan dalam token ID untuk membantu dalam fungsionalitas. Siapkan klaim tambahan dalam token ID dengan menggunakan salah satu opsi berikut:

Opsi 1: Gunakan opsi ini saat Anda memiliki klien publik dan aplikasi web tidak memiliki sumber daya yang coba diaksesnya. Opsi memerlukan:

response_mode diatur sebagai form_post
Pengidentifikasi pihak yang mengandalkan (pengidentifikasi API web) sama dengan pengidentifikasi klien

Diagram AD FS mengatur opsi token satu.

Opsi 2: Gunakan opsi ini saat aplikasi web memiliki sumber daya yang coba diakses dan perlu meneruskan klaim tambahan melalui token ID. Anda dapat menggunakan klien publik dan rahasia. Opsi memerlukan:

response_mode diatur sebagai form_post
KB4019472 diinstal di server Active Directory Federation Services Anda
Cakupan allatclaims ditetapkan kepada pasangan klien-RP. Anda dapat menetapkan cakupan dengan menggunakan Grant-ADFSApplicationPermission. Gunakan Set-AdfsApplicationPermission jika sudah diberikan sekali. Cmdlet PowerShell ditunjukkan dalam contoh berikut:
```
Grant-AdfsApplicationPermission -ClientRoleIdentifier "https://my/privateclient" -ServerRoleIdentifier "https://rp/fedpassive" -ScopeNames "allatclaims","openid"
```

Diagram AD FS menyesuaikan opsi token dua.

Untuk lebih memahami cara mengonfigurasi aplikasi web di Layanan Federasi Direktori Aktif (AD FS) untuk mendapatkan token ID yang disesuaikan, lihat token ID kustom di Layanan Federasi Direktori Aktif 2016 atau yang lebih baru.

Logout tunggal

Keluar tunggal mengakhiri semua sesi klien yang menggunakan ID sesi. Layanan Federasi Direktori Aktif 2016 dan yang lebih baru mendukung akses menyeluruh untuk OpenID Connect/OAuth. Untuk informasi selengkapnya, lihat Akses menyeluruh untuk OpenID Connect dengan Layanan Federasi Direktori Aktif.

Titik akhir Layanan Federasi Direktori Aktif

Titik Akhir AD FS	Description
/authorize	AD FS mengembalikan kode otorisasi yang dapat Anda gunakan untuk mendapatkan token akses.
/token	Layanan Federasi Direktori Aktif mengembalikan token akses yang dapat Anda gunakan untuk mengakses sumber daya, seperti dalam API web.
/userinfo	AD FS mengembalikan klaim subjek.
/devicecode	AD FS mengembalikan kode perangkat dan kode pengguna.
/logout	Layanan AD FS mengeluarkan pengguna.
/keys	Kunci publik AD FS yang digunakan untuk menandatangani respons.
/.well-known/openid-configuration	Layanan Federasi Direktori Aktif (AD FS) mengembalikan metadata OAuth/OpenID Connect.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2025-08-15