使用AD FS 2019風險評估模型建置外掛程式

您現在可以建置自己的外掛程式，以封鎖或指派風險分數給不同階段的驗證要求 – 已收到要求、預先驗證和驗證后驗證。 這可以使用AD FS 2019引進的新風險評估模型來完成。

什麼是風險評估模型？

風險評估模型是一組介面和類別，可讓開發人員讀取驗證要求標頭並實作自己的風險評估邏輯。 實作的程式代碼（外掛程式）接著會與AD FS驗證程式一致執行。 例如，使用模型隨附的介面和類別，您可以實作程式代碼，根據要求標頭中包含的用戶端 IP 位址來封鎖或允許驗證要求。 AD FS 會針對每個驗證要求執行程式碼，並根據實作的邏輯採取適當的動作。

此模型允許在 AD FS 驗證管線的三個階段中的任何一個階段插入程式代碼，如下所示：

1. 要求接收階段 – 可讓建置外掛程式在AD FS收到驗證要求時允許或封鎖要求，也就是在使用者輸入認證之前。 您可以使用此階段可用的要求內容（例如：用戶端 IP、Http 方法、Proxy 伺服器 DNS 等）來執行風險評估。 例如，您可以建置外掛程式，以從要求內容讀取IP，並在IP位於預先定義的具風險IP清單中時封鎖驗證要求。

2. 預先驗證階段 – 啟用建置外掛程式，以在使用者提供認證時允許或封鎖要求，但在 AD FS 評估之前。 在這個階段，除了要求內容之外，您也有安全性內容的相關信息（例如：使用者令牌、使用者標識符等）和通訊協定內容（例如：驗證通訊協定、clientID、resourceID 等），以用於風險評估邏輯中。 例如，您可以建置外掛程式以防止密碼噴灑攻擊，方法是從使用者令牌讀取用戶密碼，並在密碼位於預先定義的具風險密碼清單中時封鎖驗證要求。

3. 驗證後 – 啟用建置外掛程式，以在使用者提供認證且 AD FS 執行驗證之後評估風險。 在這個階段，除了要求內容、安全性內容和通訊協議內容之外，您也有驗證結果的相關信息（成功或失敗）。 外掛程式可以根據可用資訊評估風險分數，並將風險分數傳遞至宣告和原則規則以進行進一步評估。

為了進一步瞭解如何建置風險評估外掛程式，並依照 AD FS 程式執行它，讓我們建置範例外掛程式，以封鎖來自識別為有風險的特定 外部網路 IP 的要求、向 AD FS 註冊外掛程式，最後測試功能。

建置範例外掛程式

Pre-requisites

以下是建置此範例外掛程式所需的必要條件清單：

• 已安裝並設定AD FS 2019
• .NET Framework 4.7 和更新版本
• Visual Studio

建置外掛程式 dll

下列程序將逐步引導您建立範例外掛程式 dll。

1. 下載範例外掛程式，使用 Git Bash 並輸入下列內容：

git clone https://github.com/Microsoft/adfs-sample-RiskAssessmentModel-RiskyIPBlock

2. 在 AD FS 伺服器上的任何位置建立 .csv 檔案 （在我的案例中，我在 C：\extensions 建立 authconfigdb.csv 檔案） ，並將您要封鎖的 IP 新增至此檔案。

範例外掛程式會封鎖來自此檔案中所列外部 網路 IP 的任何驗證要求。

3. 使用 Visual Studio 開啟專案 ThreatDetectionModule.sln 。

4. 從【解決方案總管】中移除Microsoft.IdentityServer.dll，如下所示：
   

5. 將參照新增至 AD FS 的 Microsoft.IdentityServer.dll，如下所示：

a. 以滑鼠右鍵按兩下 [方案總管] 中的 [參考]，然後選取 [新增參考...]。

b. 在「參考管理員」視窗中，選取「瀏覽」。 在 [ 選取要參考的檔案... ] 對話框中，從您的 AD FS 安裝資料夾選取 Microsoft.IdentityServer.dll [C ：\Windows\ADFS]，然後按兩下 [ 新增]。

c. 在確定Microsoft.IdentityServer.dll勾選勾選框後，按一下「參考管理員」視窗上的「確定」。

6. 所有類別和參考現在都已就緒以執行組建。 不過，由於此項目的輸出是 dll，因此必須先將它安裝到 AD FS 伺服器的 全域程式集緩存或 GAC 中，而且 dll 必須先簽署。 以下步驟可以達到此目的：

a. 以滑鼠右鍵按一下專案名稱 ThreatDetectionModule。 從功能表中，按一下 屬性。

b. 從 [屬性] 頁面中，按一下左側的 [簽署]，然後核取標示為 [簽署組件] 的核取方塊。 從 選擇強名稱密鑰檔案： 下拉選單中，選取 <新增...>。

c. 在 [ 建立強名稱金鑰] 對話框中，輸入金鑰的名稱（您可以選擇任何名稱），取消核取 [ 使用密碼保護我的金鑰檔案] 複選框。 然後，按一下 確定。

d. 儲存專案，如下所示：

7. 按一下 [建置] ，然後按一下 [重建解決方案] 來建置專案，如下所示：
   

檢查螢幕底部的 輸出視窗 ，看看是否發生任何錯誤。

外掛程式 （dll） 現在可供使用，位於專案資料夾的 \bin\Debug 資料夾中（在我的例子中，這是 C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll）。

下一個步驟是向AD FS註冊此 dll，使其與AD FS驗證程式一致執行。

使用 AD FS 註冊外掛程式 dll

我們需要使用 Register-AdfsThreatDetectionModule AD FS 伺服器上的PowerShell命令，在AD FS中註冊 dll。 不過，在我們註冊之前，我們需要取得公鑰令牌。 當我們建立金鑰並使用該金鑰簽署 dll 時，會建立此公鑰令牌。 要了解 dll 的公開金鑰權杖是什麼，您可以使用以下 SN.exe ：

1. 將 dll 文件從 \bin\Debug 文件夾複製到另一個位置（在我的例子中，將其複製到 C：\extensions）。

2. 啟動 Visual Studio 的 開發人員命令提示字元 ，並移至包含 sn.exe 的目錄（在本例中，目錄為 C：\Program Files （x86）\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools）。

3. 使用 -T 參數和文件位置運行 SN 命令（在我的例子中SN -T "C:\extensions\ThreatDetectionModule.dll"）。

此命令會提供公鑰令牌（對我來說， 公鑰令牌是 714697626ef96b35）

4. 將 dll 新增至 AD FS 伺服器的 全域程式集 緩存：最佳作法是，您為專案建立適當的安裝程式，並使用安裝程式將檔案新增至 GAC。 另一個解決方案是在開發電腦上使用 Gacutil.exe （如需 Gacutil.exe 的詳細資訊， 請參閱此處）。 由於我的 Visual Studio 與 AD FS 位於同一伺服器上，因此我將使用 Gacutil.exe ，如下所示：

a. 在 Visual Studio 的開發人員命令提示符上，轉到包含 Gacutil.exe 的目錄（在我的例子中，該目錄是 C：\Program Files （x86）\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools）。

b. 執行 Gacutil 命令（在我的例子 Gacutil /IF C:\extensions\ThreatDetectionModule.dll中）：

5. 開啟 Windows PowerShell 並執行下列命令來註冊 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>"

在我的案例中，命令為：

Register-AdfsThreatDetectionModule -Name "IPBlockPlugin" -TypeName "ThreatDetectionModule.UserRiskAnalyzer, ThreatDetectionModule, Version=10.0.0.0, Culture=neutral, PublicKeyToken=714697626ef96b35" -ConfigurationFilePath "C:\extensions\authconfigdb.csv"

6. 註冊 dll 之後，重新啟動 AD FS 服務。

就是這樣，dll 現在已向AD FS註冊並可供使用！

UnRegister-AdfsThreatDetectionModule -Name "<name used while registering the dll in 5. above>"

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

測試外掛程式

1. 開啟我們之前建立的 authconfig.csv 檔案（在我的例子中位於位置 C：\extensions）並新增您要封鎖的 Extranet IP 。 每個IP都應該位於個別行上，結尾應該沒有空格。
   

2. 儲存並關閉檔案。

3. 執行下列 PowerShell 命令，在 AD FS 中匯入更新的檔案：

Import-AdfsThreatDetectionModuleConfiguration -name "<name given while registering the dll>" -ConfigurationFilePath "<path of the .csv file>"

在我的案例中，命令為：

Import-AdfsThreatDetectionModuleConfiguration -name "IPBlockPlugin" -ConfigurationFilePath "C:\extensions\authconfigdb.csv")

4. 使用您在 authconfig.csv中新增的相同 IP 從伺服器起始驗證要求。

輸入聯合伺服器實例並點擊 測試身份驗證 按鈕。

5. 驗證遭到封鎖，如下所示。
   

既然我們已經知道如何建置和註冊外掛程式，讓我們逐步解說外掛程式程式代碼，以瞭解如何使用模型引進的新介面和類別來了解實作。

插件程式代碼逐步解說

使用 Visual Studio 開啟專案ThreatDetectionModule.sln，然後從畫面右側的 [方案總管] 開啟主要檔案UserRiskAnalyzer.cs

此檔案包含主要類別 UserRiskAnalyzer，其實作抽象類別 ThreatDetectionModule 和介面 IRequestReceivedThreatDetectionModule ，以從要求內容讀取 IP、將取得的 IP 與從 AD FS DB 載入的 IP 進行比較，並在有相符的 IP 時封鎖要求。 讓我們更詳細地探討這些類型

ThreatDetectionModule 抽象類別

這個抽象類會將外掛程式載入AD FS管線，讓其能夠與AD FS程式一致執行外掛程式程式代碼。

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);
}

類別包含下列方法和屬性：

在我們的範例外掛程式中，我們使用 OnAuthenticationPipelineLoad 和 OnConfigurationUpdate 方法，從 AD FS DB 讀取預先定義的 IP。 當外掛程式向 AD FS 註冊時，會呼叫 OnAuthenticationPipelineLoad，而使用 Cmdlet 匯Import-AdfsThreatDetectionModuleConfiguration入 .csv 時會呼叫 OnConfigurationUpdate。

IRequestReceivedThreatDetectionModule 介面

此 介面 可讓您在 AD FS 收到驗證要求時，但在使用者輸入認證之前，即在驗證程式的 [收到要求] 階段實作風險評估。

public interface IRequestReceivedThreatDetectionModule
{
  Task<ThrottleStatus> EvaluateRequest (
  ThreatDetectionLogger logger,
  RequestContext requestContext );
}

介面包含 EvaluateRequest 方法，可讓您使用 requestContext 輸入參數中傳遞的驗證要求內容來撰寫風險評估邏輯。 requestContext 參數的類型為 RequestContext。

傳遞的另一個輸入引數是 logger，其類型為 ThreatDetectionLogger。 參數可用來將錯誤、稽核和/或偵錯訊息寫入AD FS記錄。

此方法會傳回 ThrottleStatus （如果 NotEvaluated，則為 0,1 為 Block，2 為 Allow） 給 AD FS，然後會封鎖或允許要求。

在我們的範例外掛程式中，EvaluateRequest 方法實作會剖析 requestContext 參數中的 clientIpAddress，並將它與從 AD FS DB 載入的所有 IP 進行比較。 如果找到相符項，則方法會針對 Block 傳回 2，否則會針對 Allow 傳回 1。 根據傳回的值，AD FS 會封鎖或允許要求。

IPreAuthenticationThreatDetectionModule 介面

此 介面 可讓您在使用者提供認證時，但在 AD FS 評估認證之前，即預先驗證階段，實作風險評估邏輯。

public interface IPreAuthenticationThreatDetectionModule
{
  Task<ThrottleStatus> EvaluatePreAuthentication (
  ThreatDetectionLogger logger,
  RequestContext requestContext,
  SecurityContext securityContext,
  ProtocolContext protocolContext,
  IList<Claim> additionalClams
  );
}

介面包含 EvaluatePreAuthentication 方法，可讓您使用 RequestContext、requestContext、 requestContext、securityContext、 ProtocolContext protocolContext 和 IList<Claim> additionalClams 輸入參數中傳遞的資訊，來撰寫預先驗證風險評估邏輯。

傳遞的另一個輸入引數是 logger，其類型為 ThreatDetectionLogger。 參數可用來將錯誤、稽核和/或偵錯訊息寫入AD FS記錄。

此方法會傳回 ThrottleStatus （如果 NotEvaluated，則為 0,1 為 Block，2 為 Allow） 給 AD FS，然後會封鎖或允許要求。

IPostAuthenticationThreatDetectionModule 介面

此 介面 可讓您在使用者提供認證且 AD FS 執行驗證 （即驗證後階段） 之後實作風險評估邏輯。

public interface IPostAuthenticationThreatDetectionModule
{
  Task<RiskScore> EvaluatePostAuthentication (
  ThreatDetectionLogger logger,
  RequestContext requestContext,
  SecurityContext securityContext,
  ProtocolContext protocolContext,
  AuthenticationResult authenticationResult,
  IList<Claim> additionalClams
  );
}

介面包含 EvaluatePostAuthentication 方法，可讓您使用 RequestContext、requestContext、requestContext、 SecurityContext、securityContext、 protocolContext protocolContext 和 IList<Claim> additionalClams 輸入參數中傳遞的資訊，來撰寫驗證後風險評估邏輯。

傳遞的另一個輸入引數是 logger，其類型為 ThreatDetectionLogger。 參數可用來將錯誤、稽核和/或偵錯訊息寫入AD FS記錄。

此方法會傳回 可用於 AD FS 原則和宣告規則的風險分數。

FAQs

為什麼應該建置這些外掛程式？
一個： 這些外掛程式不僅提供額外的功能，讓您保護環境免於遭受密碼噴洒攻擊等攻擊，還能讓您根據需求彈性建置自己的風險評估邏輯。

擷取記錄的位置？
答： 您可以使用 WriteAdminLogErrorMessage 方法，將錯誤記錄寫入「AD FS/Admin」事件記錄檔；使用 WriteAuditMessage 方法，將稽核記錄寫入「AD FS 稽核」安全性記錄；並使用 WriteDebugMessage 方法，將偵錯記錄寫入「AD FS 追蹤」偵錯記錄檔。

新增這些外掛程式會增加AD FS驗證程序延遲嗎？
一個： 延遲影響取決於執行您所實作風險評估邏輯所花費的時間。 建議您先評估延遲影響，再部署生產環境中的外掛程式。

為什麼 AD FS 無法建議具風險 IP、使用者等的清單？
一個： 雖然目前無法使用，但我們正努力在插入式風險評估模型中建置情報，以建議有風險的IP、使用者等。 我們將很快分享啟動日期。

有哪些其他範例外掛程式可供使用？
答： 下列範例外掛程式可供使用：