AD FS 2019 リスク評価モデルを使用してプラグインをビルドする

独自のプラグインをビルドして、受信要求、事前認証、認証後のさまざまな段階で、認証要求にリスク スコアをブロックまたは割り当てることができます。 これは、AD FS 2019 で導入された新しいリスク評価モデルを使用して実現できます。

リスク評価モデルとは

リスク評価モデルは、開発者が認証要求ヘッダーを読み取り、独自のリスク評価ロジックを実装できるようにする一連のインターフェイスとクラスです。 実装されたコード (プラグイン) は、AD FS 認証プロセスに沿って実行されます。 たとえば、モデルに含まれるインターフェイスとクラスを使用して、要求ヘッダーに含まれるクライアント IP アドレスに基づいて認証要求をブロックまたは許可するコードを実装できます。 AD FS は、各認証要求のコードを実行し、実装されたロジックに従って適切なアクションを実行します。

このモデルでは、次に示すように、AD FS 認証パイプラインの 3 つのステージのいずれかでコードをプラグインできます。

1. Request Received Stage – ユーザーが資格情報を入力する前に、AD FS が認証要求を受け取ったときに要求を許可またはブロックするビルド プラグインを有効にします。 この段階で使用可能な要求コンテキスト (クライアント IP、Http メソッド、プロキシ サーバー DNS など) を使用して、リスク評価を実行できます。 たとえば、要求コンテキストから IP を読み取り、IP が定義済みの危険な IP の一覧にある場合は認証要求をブロックするプラグインを構築できます。

2. Pre-Authentication Stage – Enables building plug-ins to allow or block request at the point where user provides the credentials but before AD FS evaluates them. この段階では、要求コンテキストに加えて、リスク評価ロジックで使用するセキュリティ コンテキスト (ユーザー トークン、ユーザー識別子など) とプロトコル コンテキスト (認証プロトコル、clientID、resourceID など) に関する情報も得られます。 たとえば、ユーザー トークンからユーザー パスワードを読み取り、パスワードが定義済みの危険なパスワードの一覧にある場合に認証要求をブロックすることで、パスワード スプレー攻撃を防ぐプラグインを構築できます。

3. Post-Authentication – Enables building plug-in to assess risk after user has provided credentials and AD FS has performed authentication. この段階では、要求コンテキスト、セキュリティ コンテキスト、プロトコル コンテキストに加えて、認証結果 (成功または失敗) に関する情報も得られます。 プラグインは、利用可能な情報に基づいてリスク スコアを評価し、リスク スコアを要求に渡し、さらに評価するためのポリシー ルールを渡すことができます。

To better understand how to build a risk assessment plug-in and run it in line with AD FS process, let's build a sample plug-in that blocks the requests coming from certain extranet IPs identified as risky, register the plug-in with AD FS and finally test the functionality.

Note

または、Microsoft Entra ID Protection によって決定されたユーザー リスク レベルを活用して認証をブロックしたり、多要素認証 (MFA) を適用したりする、 リスクの高いユーザー プラグインのサンプル プラグインを構築することもできます。 Steps to build Risky User Plug-in are available here.

サンプル プラグインのビルド

Note

このチュートリアルでは、サンプル プラグインを作成する方法のみを説明します。 作成しているソリューションは、エンタープライズ対応のソリューションとは決してありません。

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. Create a .csv file at any location on your AD FS server (in my case, I created the authconfigdb.csv file at C:\extensions) and add the IPs you want to block to this file.

The sample plug-in will block any authentication requests coming from the Extranet IPs listed in this file.

Note

AD FS ファームがある場合は、任意またはすべての AD FS サーバーにファイルを作成できます。 任意のファイルを使用して、危険な IP を AD FS にインポートできます。 インポート プロセスの詳細については、以下の「 AD FS にプラグイン dll を登録する」 セクションを参照してください。

3. Visual Studio を使用してプロジェクト ThreatDetectionModule.sln を開きます。

4. 次に示すように、ソリューション エクスプローラーからMicrosoft.IdentityServer.dllを削除します。[スクリーンショット
   。

5. 次に示すように、AD FS の Microsoft.IdentityServer.dll への参照を追加します。

a. Right click on References in Solutions Explorer and select Add Reference….

b. On the Reference Manager window, select Browse. [ 参照するファイルの選択... ] ダイアログで、AD FS インストール フォルダーから Microsoft.IdentityServer.dll を選択し (私の場合 は C:\Windows\ADFS)、[ 追加] をクリックします。

Note

私の場合は、AD FS サーバー自体にプラグインをビルドしています。 開発環境が別のサーバー上にある場合は、AD FS サーバー上の AD FS インストール フォルダーから開発ボックスに Microsoft.IdentityServer.dll をコピーします。

c. Click OK on the Reference Manager window after making sure the Microsoft.IdentityServer.dll check box is selected.

6. ビルドを実行するために、すべてのクラスと参照が配置されました。 ただし、このプロジェクトの出力は dll であるため、AD FS サーバーの グローバル アセンブリ キャッシュ (GAC) にインストールする必要があり、dll に最初に署名する必要があります。 これは、次の方法で行います。

a. Right-click on the name of the project, ThreatDetectionModule. From the menu, click Properties.

b. From the Properties page, click Signing, on the left, and then check the check box marked Sign the assembly. [厳密な名前のキー ファイルを選択してください:] というプルダウン メニューから、<[新規...]> を選択します。

c. [ 厳密な名前キーの作成] ダイアログで、キーの名前 (任意の名前を選択できます) を入力し、[ パスワードでキー ファイルを保護する] チェック ボックスをオフにします。 Then, click OK.

d. 次のようにプロジェクトを保存します。

7. Build the project by clicking Build and then Rebuild Solution as shown below:
   

Check the Output window at the bottom of the screen, to see if any errors occurred.

The plug-in (dll) is now ready for use and is in the \bin\Debug folder of the project folder (in my case, that's C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll).

次の手順では、この dll を AD FS に登録して、AD FS 認証プロセスに沿って実行します。

AD FS にプラグイン dll を登録する

AD FS サーバーで Register-AdfsThreatDetectionModule PowerShell コマンドを使用して、AD FS に dll を登録する必要があります。 ただし、登録する前に、公開キー トークンを取得する必要があります。 この公開キー トークンは、キーを作成し、そのキーを使用して dll に署名したときに作成されました。 To learn what the Public Key Token for the dll is, you can use the SN.exe as follows:

1. Copy the dll file from the \bin\Debug folder to another location (in my case, copying it to C:\extensions).

2. Visual Studio の 開発者コマンド プロンプト を起動し、 sn.exe が含まれているディレクトリに移動します (私の場合、ディレクトリは C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools です)。

3. Run the SN command with the -T parameter and the location of the file (in my case SN -T "C:\extensions\ThreatDetectionModule.dll").

このコマンドによって公開キー トークンが提供されます (公開 キー トークンは 714697626ef96b35 です)

4. AD FS サーバーの グローバル アセンブリ キャッシュ に dll を追加します。ベスト プラクティスは、プロジェクト用の適切なインストーラーを作成し、インストーラーを使用して GAC にファイルを追加することです。 Another solution is to use Gacutil.exe (more information on Gacutil.exe available here) on your development machine. Since I have my visual studio on the same server as AD FS, I'll be using Gacutil.exe as follows:

a. On Developer Command Prompt for Visual Studio and go to the directory containing the Gacutil.exe (in my case, the directory is C:\Program Files (x86)\Microsoft SDKs\Windows\v10.0A\bin\NETFX 4.7.2 Tools).

b. Run the Gacutil command (in my case Gacutil /IF C:\extensions\ThreatDetectionModule.dll):

Note

AD FS ファームがある場合は、ファーム内の各 AD FS サーバーで上記を実行する必要があります。

5. Open Windows PowerShell and run the following command to register the 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"

Note

AD FS ファームがある場合でも、dll を登録する必要があるのは 1 回だけです。

6. dll を登録した後、AD FS サービスを再起動します。

これで、dll が AD FS に登録され、使用する準備が整いました。

Note

プラグインに変更が加えられ、プロジェクトが再構築された場合は、更新された dll をもう一度登録する必要があります。 登録する前に、次のコマンドを使用して現在の dll の登録を解除する必要があります。

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

私の場合、コマンドは次のとおりです。

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

プラグインのテスト

1. Open the authconfig.csv file we created earlier (in my case at location C:\extensions) and add the Extranet IPs you want to block. すべての 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. Initiate authentication request from the server with the same IP you added in authconfig.csv.

Enter federation server instance and hit Test Authentication button.

5. 次に示すように、認証はブロックされます。
   

プラグインをビルドして登録する方法を理解したので、モデルで導入された新しいインターフェイスとクラスを使用して、プラグイン コードをチュートリアルして実装を理解しましょう。

プラグイン コードのチュートリアル

Open the project ThreatDetectionModule.sln using Visual Studio and then open the main file UserRiskAnalyzer.cs from the Solutions Explorer on the right of the screen

The file contains the main class UserRiskAnalyzer which implements the abstract class ThreatDetectionModule and interface IRequestReceivedThreatDetectionModule to read the IP from the request context, compare the obtained IP with the IPs loaded from AD FS DB, and block request if there's an IP match. これらの型について詳しく見てみましょう

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

このクラスには、次のメソッドとプロパティが含まれています。

Method	タイプ	Definition
OnAuthenticationPipelineLoad	Void	プラグインがパイプラインに読み込まれるときに AD FS によって呼び出される
OnAuthenticationPipelineUnload	Void	プラグインがパイプラインからアンロードされたときに AD FS によって呼び出される
OnConfigurationUpdate	Void	構成の更新時に AD FS によって呼び出される
Property	Type	Definition
VendorName	String	プラグインを所有しているベンダーの名前を取得します。
ModuleIdentifier	String	プラグインの識別子を取得します。

In our sample plugin, we're using OnAuthenticationPipelineLoad and OnConfigurationUpdate methods to read the pre-defined IPs from AD FS DB. OnAuthenticationPipelineLoad is called when plug-in is registered with AD FS while OnConfigurationUpdate is called when the .csv is imported using the Import-AdfsThreatDetectionModuleConfiguration cmdlet.

IRequestReceivedThreatDetectionModule Interface

This interface enables you to implement risk assessment at the point where AD FS receives the authentication request, but before user enters credentials i.e. at Received Request stage of the authentication process.

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

The interface includes EvaluateRequest method which allows you to use the context of the authentication request passed in the requestContext input parameter to write your risk assessment logic. The requestContext parameter is of type RequestContext.

The other input parameter passed is logger which is type ThreatDetectionLogger. このパラメーターを使用して、AD FS ログにエラーメッセージ、監査メッセージ、デバッグ メッセージを書き込むことができます。

The method returns ThrottleStatus (0 if NotEvaluated, 1 to Block, and 2 to Allow) to AD FS which then either blocks or allows the request.

In our sample plug-in, EvaluateRequest method implementation parses the clientIpAddress from the requestContext parameter and compares it with all the IPs loaded from the AD FS DB. If a match is found, method returns 2 for Block, else it returns 1 for Allow. 返された値に基づいて、AD FS は要求をブロックまたは許可します。

Note

上記のサンプル プラグインでは、IRequestReceivedThreatDetectionModule インターフェイスのみが実装されています。 ただし、リスク評価モデルには、IPreAuthenticationThreatDetectionModule (事前認証段階でリスク評価ロジックを実装するため) と IPostAuthenticationThreatDetectionModule (認証後の段階でリスク評価ロジックを実装するため) という 2 つの追加インターフェイスが用意されています。 2 つのインターフェイスの詳細を以下に示します。

IPreAuthenticationThreatDetectionModule Interface

This interface enables you to implement risk assessment logic at the point where user provides the credentials but before AD FS evaluates them i.e. pre-authentication stage.

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

The interface includes EvaluatePreAuthentication method which allows you to use the information passed in the RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext, and IList<Claim> additionalClams input parameters to write your pre-authentication risk assessment logic.

Note

For list of properties passed with each context type, visit RequestContext, SecurityContext, and ProtocolContext class definitions.

The other input parameter passed is logger which is type ThreatDetectionLogger. このパラメーターを使用して、AD FS ログにエラーメッセージ、監査メッセージ、デバッグ メッセージを書き込むことができます。

The method returns ThrottleStatus (0 if NotEvaluated, 1 to Block, and 2 to Allow) to AD FS which then either blocks or allows the request.

IPostAuthenticationThreatDetectionModule Interface

This interface enables you to implement risk assessment logic after user has provided credentials and AD FS has performed authentication i.e. post-authentication stage.

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

The interface includes EvaluatePostAuthentication method which allows you to use the information passed in the RequestContext requestContext, SecurityContext securityContext, ProtocolContext protocolContext, and IList<Claim> additionalClams input parameters to write your post-authentication risk assessment logic.

Note

For complete list of properties passed with each context type, refer RequestContext, SecurityContext, and ProtocolContext class definitions.

The other input parameter passed is logger which is type ThreatDetectionLogger. このパラメーターを使用して、AD FS ログにエラーメッセージ、監査メッセージ、デバッグ メッセージを書き込むことができます。

The method returns the Risk Score which can be used in AD FS policy and claim rules.

Note

For plug-in to work, the main class (in this case UserRiskAnalyzer) needs to derive ThreatDetectionModule abstract class and should implement at least one of the three interfaces described above. dll が登録されると、AD FS は実装されているインターフェイスを確認し、パイプライン内の適切な段階でそれらを呼び出します。

FAQs

これらのプラグインをビルドする必要がある理由
ある： これらのプラグインは、パスワード スプレー攻撃などの攻撃から環境を保護する追加の機能を提供するだけでなく、要件に基づいて独自のリスク評価ロジックを柔軟に構築することもできます。

ログはどこにキャプチャされますか?
ある： WriteAdminLogErrorMessage メソッドを使用してエラー ログを "AD FS/Admin" イベント ログに書き込み、WriteAuditMessage メソッドを使用して "AD FS 監査" セキュリティ ログに監査ログを書き込み、WriteDebugMessage メソッドを使用して "AD FS トレース" デバッグ ログにデバッグ ログを書き込むことができます。

これらのプラグインを追加すると、AD FS 認証プロセスの待機時間が長くなりますか?
ある： 待機時間の影響は、実装するリスク評価ロジックの実行にかかった時間によって決まります。 運用環境にプラグインをデプロイする前に、待機時間の影響を評価することをお勧めします。

AD FS が危険な IP、ユーザーなどの一覧を提案できないのはなぜですか?
ある： 現時点では使用できませんが、プラグ可能なリスク評価モデルでリスクの高い IP、ユーザーなどを提案するインテリジェンスの構築に取り組んでいます。 私たちはまもなく発売日をお知らせします。

その他のサンプル プラグインは何ですか?
ある： 次のサンプル プラグインを使用できます。

Name	Description
危険なユーザー プラグイン	Microsoft Entra ID Protection によって決定されるユーザー リスク レベルに基づいて認証をブロックするか、MFA を適用するサンプル プラグイン。