Bangun Plug-in dengan Model Penilaian Risiko Ad FS 2019
Anda sekarang dapat membangun plug-in Anda sendiri untuk memblokir atau menetapkan skor risiko ke permintaan autentikasi selama berbagai tahap - permintaan diterima, pra-autentikasi, dan pasca-autentikasi. Ini dapat dicapai menggunakan Model Penilaian Risiko baru yang diperkenalkan dengan Layanan Federasi Direktori Aktif 2019.
Apa itu Model Penilaian Risiko?
Model Penilaian Risiko adalah sekumpulan antarmuka dan kelas yang memungkinkan pengembang membaca header permintaan autentikasi dan menerapkan logika penilaian risiko mereka sendiri. Kode yang diimplementasikan (plug-in) kemudian berjalan sejalan dengan proses autentikasi AD FS. Misalnya, menggunakan antarmuka dan kelas yang disertakan dengan model, Anda dapat menerapkan kode untuk memblokir atau mengizinkan permintaan autentikasi berdasarkan alamat IP klien yang disertakan dalam header permintaan. Layanan Federasi Direktori Aktif akan menjalankan kode untuk setiap permintaan autentikasi dan mengambil tindakan yang sesuai dengan logika yang diterapkan.
Model ini memungkinkan kode plug-in pada salah satu dari tiga tahap alur autentikasi Ad FS seperti yang ditunjukkan di bawah ini:
Tahap Permintaan Diterima – Memungkinkan pembuatan plug-in untuk mengizinkan atau memblokir permintaan saat AD FS menerima permintaan autentikasi yaitu sebelum pengguna memasukkan kredensial. Anda dapat menggunakan konteks permintaan (misalnya: IP klien, metode Http, DNS server proksi, dll.) yang tersedia pada tahap ini untuk melakukan penilaian risiko. Misalnya, Anda dapat membuat plug-in untuk membaca IP dari konteks permintaan dan memblokir permintaan autentikasi jika IP berada dalam daftar IP berisiko yang telah ditentukan sebelumnya.
Tahap Pra-Autentikasi – Memungkinkan pembuatan plug-in untuk mengizinkan atau memblokir permintaan pada titik di mana pengguna memberikan kredensial tetapi sebelum LAYANAN Federasi Direktori Aktif mengevaluasinya. Pada tahap ini, selain konteks permintaan Anda juga memiliki informasi tentang konteks keamanan (misalnya: token pengguna, pengidentifikasi pengguna, dll) dan konteks protokol (misalnya: protokol autentikasi, clientID, resourceID, dll) untuk digunakan dalam logika penilaian risiko Anda. Misalnya, Anda dapat membangun plug-in untuk mencegah serangan semprotan kata sandi dengan membaca kata sandi pengguna dari token pengguna dan memblokir permintaan autentikasi jika kata sandi berada dalam daftar kata sandi berisiko yang telah ditentukan sebelumnya.
Pasca-Autentikasi – Memungkinkan pembuatan plug-in untuk menilai risiko setelah pengguna memberikan kredensial dan AD FS telah melakukan autentikasi. Pada tahap ini, selain konteks permintaan, konteks keamanan, dan konteks protokol, Anda juga memiliki informasi tentang hasil autentikasi (Berhasil atau Gagal). Plug-in dapat mengevaluasi skor risiko berdasarkan informasi yang tersedia dan meneruskan skor risiko ke aturan klaim dan kebijakan untuk evaluasi lebih lanjut.
Untuk lebih memahami cara membuat plug-in penilaian risiko dan menjalankannya sejalan dengan proses Ad FS, mari kita buat plug-in sampel yang memblokir permintaan yang berasal dari IP ekstranet tertentu yang diidentifikasi berisiko, mendaftarkan plug-in dengan Ad FS dan akhirnya menguji fungsionalitas.
Catatan
Atau, Anda dapat membangun Risky User Plug-in, plug-in sampel yang memanfaatkan tingkat risiko pengguna yang ditentukan oleh Microsoft Entra ID Protection untuk memblokir autentikasi atau menerapkan autentikasi multifaktor (MFA). Langkah-langkah untuk membangun Plug-in Pengguna Riskan tersedia di sini.
Membuat sampel plug-in
Catatan
Panduan ini hanya untuk menunjukkan kepada Anda bagaimana Anda dapat membuat sampel plug-in. Solusi yang kami buat sama sekali bukan solusi yang siap untuk Perusahaan.
Prasyarat
Berikut ini adalah daftar prasyarat yang diperlukan untuk membangun plug-in sampel ini:
- Layanan Federasi Direktori Aktif 2019 diinstal dan dikonfigurasi
- .NET Framework 4.7 ke atas
- Visual Studio
Bangun dll plug-in
Prosedur berikut akan memancang Anda melalui pembuatan sampel dll plug-in:
Unduh plug-in sampel, gunakan Git Bash dan ketik yang berikut:
git clone https://github.com/Microsoft/adfs-sample-RiskAssessmentModel-RiskyIPBlock
Buat file .csv di lokasi mana pun di server AD FS Anda (dalam kasus saya, saya membuat file authconfigdb.csv di C:\extensions) dan menambahkan IP yang ingin Anda blokir ke file ini.
Plug-in sampel akan memblokir permintaan autentikasi apa pun yang berasal dari IP Ekstranet yang tercantum dalam file ini.
Catatan
Jika Anda memiliki Layanan Federasi Direktori Aktif, Anda dapat membuat file di salah satu atau semua server Layanan Federasi Direktori Aktif. Salah satu file dapat digunakan untuk mengimpor IP berisiko ke Layanan Federasi Direktori Aktif. Kami akan membahas proses impor secara rinci di bagian Daftarkan dll plug-in dengan Layanan Federasi Direktori Aktif di bawah ini.
Buka proyek
ThreatDetectionModule.sln
menggunakan Visual Studio.Hapus dari Penjelajah Solusi seperti yang
Microsoft.IdentityServer.dll
ditunjukkan di bawah ini:Tambahkan referensi ke Layanan Federasi Direktori Aktif Anda seperti yang
Microsoft.IdentityServer.dll
ditunjukkan di bawah ini:a. Klik kanan Referensi di Penjelajah Solusi dan pilih Tambahkan Referensi....
b. Pada jendela Manajer Referensi, pilih Telusuri. Dalam dialog Pilih file yang akan direferensikan... , pilih
Microsoft.IdentityServer.dll
dari folder penginstalan LAYANAN Federasi Direktori Aktif Anda (dalam kasus saya C:\Windows\ADFS) dan klik Tambahkan.Catatan
Dalam kasus saya, saya membangun plug-in di server LAYANAN Federasi Direktori Aktif itu sendiri. Jika lingkungan pengembangan Anda berada di server yang berbeda, salin
Microsoft.IdentityServer.dll
dari folder penginstalan Layanan Federasi Direktori Aktif Anda di server Layanan Federasi Direktori Aktif ke kotak pengembangan Anda.c. Klik OK pada jendela Manajer Referensi setelah memastikan kotak
Microsoft.IdentityServer.dll
centang dipilih.Semua kelas dan referensi sekarang tersedia untuk melakukan build. Namun, karena output proyek ini adalah dll, itu harus diinstal ke dalam Global Assembly Cache, atau GAC, dari server AD FS dan dll perlu ditandatangani terlebih dahulu. Ini dapat dilakukan sebagai berikut:
a. Klik kanan pada nama proyek, ThreatDetectionModule. Dari menu, klik Properti.
b. Dari halaman Properti , klik Penandatanganan, di sebelah kiri, lalu centang kotak centang bertanda Tangani rakitan. Dari menu Pilih kunci nama yang kuat: tarik ke bawah, pilih <Baru...>.
c. Dalam dialog Buat Kunci Nama Kuat, ketik nama (Anda dapat memilih nama apa pun) untuk kunci, hapus centang pada kotak centang Lindungi file kunci saya dengan kata sandi. Kemudian, klik OK.
d. Simpan proyek seperti yang ditunjukkan di bawah ini:
Bangun proyek dengan mengklik Bangun lalu Bangun Kembali Solusi seperti yang ditunjukkan di bawah ini:
Periksa jendela Output di bagian bawah layar, untuk melihat apakah terjadi kesalahan.
Plug-in (dll) sekarang siap digunakan dan berada di folder \bin\Debug folder proyek (dalam kasus saya, yaitu C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).
Langkah selanjutnya adalah mendaftarkan dll ini dengan Layanan Federasi Direktori Aktif, sehingga berjalan sesuai dengan proses autentikasi Layanan Federasi Direktori Aktif.
Mendaftarkan dll plug-in dengan LAYANAN Federasi Direktori Aktif
Kita perlu mendaftarkan dll di Layanan Federasi Direktori Aktif dengan menggunakan Register-AdfsThreatDetectionModule
perintah PowerShell di server LAYANAN Federasi Direktori Aktif. Namun, sebelum mendaftar, kita perlu mendapatkan Token Kunci Umum. Token kunci publik ini dibuat saat kami membuat kunci dan menandatangani dll menggunakan kunci tersebut. Untuk mempelajari apa itu Token Kunci Publik untuk dll, Anda dapat menggunakan SN.exe sebagai berikut:
Salin file dll dari folder \bin\Debug ke lokasi lain (dalam kasus saya, menyalinnya ke C:\extensions).
Mulai Perintah Pengembang untuk Visual Studio dan buka direktori yang berisi sn.exe (dalam kasus saya, direktorinya adalah C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).
Jalankan perintah SN dengan parameter -T dan lokasi file (dalam kasus
SN -T "C:\extensions\ThreatDetectionModule.dll"
saya ).Perintah akan memberi Anda token kunci publik (Bagi saya, Token Kunci Umum adalah 714697626ef96b35)
Tambahkan dll ke Cache Perakitan Global dari server Layanan Federasi Direktori Aktif Praktik terbaik kami adalah Anda membuat alat penginstal yang tepat untuk proyek Anda dan menggunakan alat penginstal untuk menambahkan file ke GAC. Solusi lain adalah menggunakan Gacutil.exe (informasi lebih lanjut tentang Gacutil.exe tersedia di sini) pada mesin pengembangan Anda. Karena saya memiliki studio visual saya di server yang sama dengan Layanan Federasi Direktori Aktif, saya akan menggunakan Gacutil.exe sebagai berikut:
a. Pada Perintah Pengembang untuk Visual Studio dan buka direktori yang berisi Gacutil.exe (dalam kasus saya, direktorinya adalah C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).
b. Jalankan perintah Gacutil (dalam kasus
Gacutil /IF C:\extensions\ThreatDetectionModule.dll
saya ):Catatan
Jika Anda memiliki farm Layanan Federasi Direktori Aktif, hal di atas perlu dijalankan di setiap server Layanan Federasi Direktori Aktif di farm.
Buka Windows PowerShell dan jalankan perintah berikut untuk mendaftarkan dll:
Register-AdfsThreatDetectionModule -Name "<Add a name>" -TypeName "<class name that implements interface>, <dll name>, Version=10.0.0.0, Culture=neutral, PublicKeyToken=< Add the Public Key Token from Step 2. above>" -ConfigurationFilePath "<path of the .csv file>"
Dalam kasus saya, perintahnya adalah:
Register-AdfsThreatDetectionModule -Name "IPBlockPlugin" -TypeName "ThreatDetectionModule.UserRiskAnalyzer, ThreatDetectionModule, Version=10.0.0.0, Culture=neutral, PublicKeyToken=714697626ef96b35" -ConfigurationFilePath "C:\extensions\authconfigdb.csv"
Catatan
Anda perlu mendaftarkan dll hanya sekali, bahkan jika Anda memiliki farm Layanan Federasi Direktori Aktif.
Mulai ulang layanan Layanan Federasi Direktori Aktif setelah mendaftarkan dll.
Itu saja, dll sekarang terdaftar di Layanan Federasi Direktori Aktif dan siap digunakan!
Catatan
Jika ada perubahan yang dilakukan pada plugin dan proyek dibangun kembali, maka dll yang diperbarui perlu didaftarkan lagi. Sebelum mendaftar, Anda harus membatalkan pendaftaran dll saat ini menggunakan perintah berikut:
UnRegister-AdfsThreatDetectionModule -Name "<name used while registering the dll in 5. above>"
Dalam kasus saya, perintahnya adalah:
UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"
Menguji plug-in
Buka file authconfig.csv yang kami buat sebelumnya (dalam kasus saya di lokasi C:\extensions) dan tambahkan IP Extranet yang ingin Anda blokir. Setiap IP harus berada di baris terpisah dan seharusnya tidak ada spasi di akhir.
Simpan dan tutup file.
Impor file yang diperbarui di Layanan Federasi Direktori Aktif dengan menjalankan perintah PowerShell berikut ini:
Import-AdfsThreatDetectionModuleConfiguration -name "<name given while registering the dll>" -ConfigurationFilePath "<path of the .csv file>"
Dalam kasus saya, perintahnya adalah:
Import-AdfsThreatDetectionModuleConfiguration -name "IPBlockPlugin" -ConfigurationFilePath "C:\extensions\authconfigdb.csv")
Mulai permintaan autentikasi dari server dengan IP yang sama dengan yang Anda tambahkan di authconfig.csv.
Untuk demonstrasi ini, saya akan menggunakan alat X-Ray Klaim Bantuan Layanan Federasi Direktori Aktif untuk memulai permintaan. Jika Anda ingin menggunakan alat X-Ray, silakan ikuti instruksinya
Masukkan instans server federasi dan tekan tombol Uji Autentikasi .
Autentikasi diblokir seperti yang ditunjukkan di bawah ini.
Sekarang setelah kita tahu cara membuat dan mendaftarkan plug-in, mari kita lihat kode plug-in untuk memahami implementasi menggunakan antarmuka dan kelas baru yang diperkenalkan dengan model.
Panduan kode plug-in
Buka proyek ThreatDetectionModule.sln
menggunakan Visual Studio lalu buka file utama UserRiskAnalyzer.cs dari Solutions Explorer di sebelah kanan layar
File berisi kelas utama UserRiskAnalyzer yang mengimplementasikan kelas abstrak ThreatDetectionModule dan antarmuka IRequestReceivedThreatDetectionModule untuk membaca IP dari konteks permintaan, membandingkan IP yang diperoleh dengan IP yang dimuat dari AD FS DB, dan blokir permintaan jika ada kecocokan IP. Mari kita membahas jenis-jenis ini secara lebih rinci
Kelas abstrak ThreatDetectionModule
Kelas abstrak ini memuat plug-in ke dalam alur Layanan Federasi Direktori Aktif sehingga memungkinkan untuk menjalankan kode plug-in sejalan dengan proses LAYANAN Federasi Direktori Aktif.
public abstract class ThreatDetectionModule
{
protected ThreatDetectionModule();
public abstract string VendorName { get; }
public abstract string ModuleIdentifier { get; }
public abstract void OnAuthenticationPipelineLoad(ThreatDetectionLogger logger, ThreatDetectionModuleConfiguration configData);
public abstract void OnAuthenticationPipelineUnload(ThreatDetectionLogger logger);
public abstract void OnConfigurationUpdate(ThreatDetectionLogger logger, ThreatDetectionModuleConfiguration configData);
}
Kelas ini mencakup metode dan properti berikut:
Metode | Jenis | Definisi |
---|---|---|
OnAuthenticationPipelineLoad | Kekosongan | Dipanggil oleh Layanan Federasi Direktori Aktif ketika plugin dimuat ke dalam alurnya |
OnAuthenticationPipelineUnload | Kekosongan | Dipanggil oleh Layanan Federasi Direktori Aktif ketika plugin dibongkar dari alurnya |
OnConfigurationUpdate | Kekosongan | Dipanggil oleh Layanan Federasi Direktori Aktif pada pembaruan konfigurasi |
Properti | Jenis | Definisi |
VendorName | String | Mendapatkan nama vendor yang memiliki plugin |
ModuleIdentifier | String | Mendapatkan pengidentifikasi plugin |
Dalam plugin sampel kami, kami menggunakan metode OnAuthenticationPipelineLoad dan OnConfigurationUpdate untuk membaca IP yang telah ditentukan sebelumnya dari AD FS DB. OnAuthenticationPipelineLoad dipanggil ketika plug-in terdaftar di Layanan Federasi Direktori Aktif sementara OnConfigurationUpdate dipanggil ketika .csv diimpor menggunakan Import-AdfsThreatDetectionModuleConfiguration
cmdlet.
Antarmuka IRequestReceivedThreatDetectionModule
Antarmuka ini memungkinkan Anda menerapkan penilaian risiko pada titik di mana Layanan Federasi Direktori Aktif menerima permintaan autentikasi, tetapi sebelum pengguna memasukkan kredensial yaitu pada tahap Permintaan Yang Diterima dari proses autentikasi.
public interface IRequestReceivedThreatDetectionModule
{
Task<ThrottleStatus> EvaluateRequest (
ThreatDetectionLogger logger,
RequestContext requestContext );
}
Antarmuka mencakup metode EvaluateRequest yang memungkinkan Anda menggunakan konteks permintaan autentikasi yang diteruskan dalam parameter input requestContext untuk menulis logika penilaian risiko Anda. Parameter requestContext berjenis RequestContext.
Parameter input lain yang diteruskan adalah pencatat yang merupakan jenis ThreatDetectionLogger. Parameter dapat digunakan untuk menulis pesan kesalahan, audit, dan/atau debug ke log Ad FS.
Metode mengembalikan ThrottleStatus (0 jika NotEvaluated, 1 hingga Block, dan 2 to Allow) ke LAYANAN Federasi Direktori Aktif yang kemudian memblokir atau mengizinkan permintaan.
Dalam plug-in sampel kami, implementasi metode EvaluateRequest mengurai clientIpAddress dari parameter requestContext dan membandingkannya dengan semua IP yang dimuat dari AD FS DB. Jika kecocokan ditemukan, metode mengembalikan 2 untuk Blokir, jika tidak, metode mengembalikan 1 untuk Izinkan. Berdasarkan nilai yang dikembalikan, LAYANAN Federasi Direktori Aktif memblokir atau mengizinkan permintaan.
Catatan
Plug-in sampel yang dibahas di atas hanya mengimplementasikan antarmuka IRequestReceivedThreatDetectionModule. Namun, model penilaian risiko menyediakan dua antarmuka tambahan –IPreAuthenticationThreatDetectionModule (untuk menerapkan tahap pra-autentikasi duing logika penilaian risiko) dan IPostAuthenticationThreatDetectionModule (untuk menerapkan logika penilaian risiko selama tahap pasca-autentikasi). Detail tentang dua antarmuka disediakan di bawah ini.
Antarmuka IPreAuthenticationThreatDetectionModule
Antarmuka ini memungkinkan Anda menerapkan logika penilaian risiko pada titik di mana pengguna memberikan kredensial tetapi sebelum AD FS mengevaluasinya yaitu tahap pra-autentikasi.
public interface IPreAuthenticationThreatDetectionModule
{
Task<ThrottleStatus> EvaluatePreAuthentication (
ThreatDetectionLogger logger,
RequestContext requestContext,
SecurityContext securityContext,
ProtocolContext protocolContext,
IList<Claim> additionalClams
);
}
Antarmuka mencakup metode EvaluatePreAuthentication yang memungkinkan Anda menggunakan informasi yang diteruskan dalam parameter input RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext, dan IList<Claim> additionalClams untuk menulis logika penilaian risiko pra-autentikasi Anda.
Catatan
Untuk daftar properti yang diteruskan dengan setiap jenis konteks, kunjungi definisi kelas RequestContext, SecurityContext, dan ProtocolContext .
Parameter input lain yang diteruskan adalah pencatat yang merupakan jenis ThreatDetectionLogger. Parameter dapat digunakan untuk menulis pesan kesalahan, audit, dan/atau debug ke log Ad FS.
Metode mengembalikan ThrottleStatus (0 jika NotEvaluated, 1 hingga Block, dan 2 to Allow) ke LAYANAN Federasi Direktori Aktif yang kemudian memblokir atau mengizinkan permintaan.
Antarmuka IPostAuthenticationThreatDetectionModule
Antarmuka ini memungkinkan Anda menerapkan logika penilaian risiko setelah pengguna memberikan kredensial dan Ad FS telah melakukan autentikasi yaitu tahap pasca-autentikasi.
public interface IPostAuthenticationThreatDetectionModule
{
Task<RiskScore> EvaluatePostAuthentication (
ThreatDetectionLogger logger,
RequestContext requestContext,
SecurityContext securityContext,
ProtocolContext protocolContext,
AuthenticationResult authenticationResult,
IList<Claim> additionalClams
);
}
Antarmuka ini mencakup metode EvaluatePostAuthentication yang memungkinkan Anda menggunakan informasi yang diteruskan dalam parameter input RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext, dan IList<Claim> additionalClams untuk menulis logika penilaian risiko pasca-autentikasi Anda.
Catatan
Untuk daftar lengkap properti yang diteruskan dengan setiap jenis konteks, lihat definisi kelas RequestContext, SecurityContext, dan ProtocolContext .
Parameter input lain yang diteruskan adalah pencatat yang merupakan jenis ThreatDetectionLogger. Parameter dapat digunakan untuk menulis pesan kesalahan, audit, dan/atau debug ke log Ad FS.
Metode ini mengembalikan Skor Risiko yang dapat digunakan dalam kebijakan layanan federasi direktori aktif dan aturan klaim.
Catatan
Agar plug-in berfungsi, kelas utama (dalam hal ini UserRiskAnalyzer) perlu memperoleh kelas abstrak ThreatDetectionModule dan harus menerapkan setidaknya satu dari tiga antarmuka yang dijelaskan di atas. Setelah dll terdaftar, LAYANAN Federasi Direktori Aktif memeriksa antarmuka mana yang diimplementasikan dan memanggilnya pada tahap yang sesuai dalam alur.
Tanya Jawab Umum
Mengapa saya harus membuat plug-in ini?
A: Plug-in ini tidak hanya memberi Anda kemampuan tambahan untuk mengamankan lingkungan Anda dari serangan seperti serangan semprotan kata sandi, tetapi juga memberi Anda fleksibilitas untuk membangun logika penilaian risiko Anda sendiri berdasarkan kebutuhan Anda.
Di mana log diambil?
J: Anda dapat menulis log kesalahan ke log peristiwa "AD FS/Admin" menggunakan metode WriteAdminLogErrorMessage, log audit ke log keamanan "Ad FS Auditing" menggunakan metode WriteAuditMessage dan log debug ke log debug "Pelacakan Layanan Federasi Direktori Aktif" menggunakan metode WriteDebugMessage.
Dapatkah menambahkan plug-in ini meningkatkan latensi proses autentikasi AD FS?
A: Dampak latensi akan ditentukan oleh waktu yang diperlukan untuk menjalankan logika penilaian risiko yang Anda terapkan. Sebaiknya evaluasi dampak latensi sebelum menyebarkan plug-in di lingkungan produksi.
Mengapa AD FS tidak dapat menyarankan daftar IP berisiko, pengguna, dll.?
A: Meskipun saat ini tidak tersedia, kami sedang berupaya membangun kecerdasan untuk menyarankan IP berisiko, pengguna, dll. dalam Model Penilaian Risiko yang Dapat Dicolokkan. Kami akan segera membagikan tanggal peluncuran.
Plug-in sampel lain apa yang tersedia?
J: Sampel plug-in berikut tersedia:
Nama | Deskripsi |
---|---|
Plug-in Pengguna Berisiko | Sampel plug-in yang memblokir autentikasi atau memberlakukan MFA berdasarkan tingkat risiko pengguna yang ditentukan oleh Microsoft Entra ID Protection. |