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. 事前認証ステージ – ユーザーが資格情報を提供した時点で、AD FS が評価する前に要求を許可またはブロックするビルド プラグインを有効にします。 この段階では、要求コンテキストに加えて、リスク評価ロジックで使用するセキュリティ コンテキスト (ユーザー トークン、ユーザー識別子など) とプロトコル コンテキスト (認証プロトコル、clientID、resourceID など) に関する情報も得られます。 たとえば、ユーザー トークンからユーザー パスワードを読み取り、パスワードが定義済みの危険なパスワードの一覧にある場合に認証要求をブロックすることで、パスワード スプレー攻撃を防ぐプラグインを構築できます。

3. 認証後 – ユーザーが資格情報を指定し、AD FS が認証を実行した後に、プラグインをビルドしてリスクを評価できるようにします。 この段階では、要求コンテキスト、セキュリティ コンテキスト、プロトコル コンテキストに加えて、認証結果 (成功または失敗) に関する情報も得られます。 プラグインは、利用可能な情報に基づいてリスク スコアを評価し、リスク スコアを要求に渡し、さらに評価するためのポリシー ルールを渡すことができます。

リスク評価プラグインを構築し、AD FS プロセスに沿って実行する方法を理解するために、リスクが高いと識別された特定の エクストラネット IP からの要求をブロックするサンプル プラグインを構築し、AD FS にプラグインを登録して、最後に機能をテストします。

注

または、Microsoft Entra ID Protection によって決定されたユーザー リスク レベルを活用して認証をブロックしたり、多要素認証 (MFA) を適用したりする、 リスクの高いユーザー プラグインのサンプル プラグインを構築することもできます。 危険なユーザー プラグインをビルドする手順 については、こちらをご覧ください。

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

注

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

前提条件

このサンプル プラグインをビルドするために必要な前提条件の一覧を次に示します。

• 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 からの認証要求をすべてブロックします。

注

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 への参照を追加します。

ある。 ソリューション エクスプローラーで [参照] を右クリックし、[参照の追加...] を選択します。

b。 [ 参照マネージャー ] ウィンドウで、[ 参照] を選択します。 [ 参照するファイルの選択... ] ダイアログで、AD FS インストール フォルダーから Microsoft.IdentityServer.dll を選択し (私の場合 は C:\Windows\ADFS)、[ 追加] をクリックします。

注

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

c. [] チェック ボックスがオンになっていることを確認した後、[参照マネージャー] ウィンドウで Microsoft.IdentityServer.dllクリックします。

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

ある。 プロジェクトの名前 ThreatDetectionModule を右クリックします。 メニューの [ プロパティ] をクリックします。

b。 [ プロパティ ] ページで、左側の [署名] をクリックし、[ アセンブリに署名する] チェック ボックスをオンにします。 [厳密な名前のキー ファイルを選択してください:] というプルダウン メニューから、<[新規...]> を選択します。

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

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

7. 次に示すように、[ビルド] をクリックしてプロジェクトを ビルド し、[ ソリューションのリビルド ] をクリックします。
   

画面の下部にある [出力] ウィンドウ で、エラーが発生したかどうかを確認します。

プラグイン (dll) は使用できる状態になり、プロジェクト フォルダーの \bin\Debug フォルダーにあります (私の場合は C:\extensions\ThreatDetectionModule\bin\Debug\ThreatDetectionModule.dll)。

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

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

AD FS サーバーで Register-AdfsThreatDetectionModule 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 -T "C:\extensions\ThreatDetectionModule.dll" コマンドを実行します。

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

4. AD FS サーバーの グローバル アセンブリ キャッシュ に dll を追加します。ベスト プラクティスは、プロジェクト用の適切なインストーラーを作成し、インストーラーを使用して GAC にファイルを追加することです。 もう 1 つの解決策は、開発用コンピューターで Gacutil.exe ( Gacutil.exe 詳細 については、こちら) を使用することです。 私はAD FSと同じサーバー上に私のビジュアルスタジオを持っているので、私は次のように Gacutil.exe を使用します:

ある。 Visual Studio の開発者コマンド プロンプトで、 Gacutil.exe を含むディレクトリに移動します (私の場合、ディレクトリは C:\Program Files (x86)\Microsoft SDK\Windows\v10.0A\bin\NETFX 4.7.2 ツールです)。

b。 Gacutil コマンドを実行します (私の場合はGacutil /IF C:\extensions\ThreatDetectionModule.dll)。

注

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

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"

注

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

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

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

注

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

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

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

UnRegister-AdfsThreatDetectionModule -Name "IPBlockPlugin"

プラグインのテスト

1. 先ほど作成した authconfig.csv ファイル (私の場合は C:\extensions) を開き、ブロックする エクストラネット 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を開きます

このファイルには、抽象クラス ThreatDetectionModule とインターフェイス IRequestReceivedThreatDetectionModule を実装するメイン クラス UserRiskAnalyzer が含まれており、要求コンテキストから 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);
}

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

メソッド	タイプ	定義
認証パイプラインロード	無効	プラグインがパイプラインに読み込まれるときに AD FS によって呼び出される
認証パイプラインアンロード	無効	プラグインがパイプラインからアンロードされたときに AD FS によって呼び出される
OnConfigurationUpdateの	無効	構成の更新時に AD FS によって呼び出される
プロパティ	タイプ	定義
ベンダー名	糸	プラグインを所有しているベンダーの名前を取得します。
モジュール識別子	糸	プラグインの識別子を取得します。

このサンプル プラグインでは、 OnAuthenticationPipelineLoad メソッドと OnConfigurationUpdate メソッドを使用して、AD FS DB から定義済みの IP を読み取っています。 OnAuthenticationPipelineLoad は、 コマンドレットを使用して .csv をインポートするときに Import-AdfsThreatDetectionModuleConfiguration が呼び出されるときに、プラグインが AD FS に登録されている場合に呼び出されます。

IRequestReceivedThreatDetectionModule インターフェイス

この インターフェイス を使用すると、AD FS が認証要求を受信した時点で、ユーザーが資格情報を入力する前 、つまり認証プロセスの受信要求ステージでリスク評価を実装できます。

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

インターフェイスには EvaluateRequest メソッドが含まれており、requestContext 入力パラメーターで渡された認証要求のコンテキストを使用して、リスク評価ロジックを記述できます。 requestContext パラメーターの型は RequestContext です。

渡されるもう 1 つの入力パラメーターは、 ThreatDetectionLogger 型のロガーです。 このパラメーターを使用して、AD FS ログにエラーメッセージ、監査メッセージ、デバッグ メッセージを書き込むことができます。

このメソッドは、要求をブロックまたは許可する ThrottleStatus (NotEvaluated の場合は 0、ブロックに 1、許可する場合は 2) を AD FS に返します。

サンプル プラグインの EvaluateRequest メソッドの実装では、requestContext パラメーターから clientIpAddress が解析され、AD FS DB から読み込まれたすべての IP と比較されます。 一致が見つかった場合、メソッドは Block に対して 2 を返し、それ以外の場合は Allow に対して 1 を返します。 返された値に基づいて、AD FS は要求をブロックまたは許可します。

注

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

IPreAuthenticationThreatDetectionModule インターフェイス

この インターフェイス を使用すると、ユーザーが資格情報を提供する時点で、AD FS が資格情報を評価する前、つまり事前認証段階でリスク評価ロジックを実装できます。

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

インターフェイスには EvaluatePreAuthentication メソッドが含まれており、RequestContext requestContext、SecurityContext securityContext、ProtocolContext protocolContext、 入力パラメーターで渡された情報を使用して、事前認証リスク評価ロジックを記述できます。 <

注

各コンテキスト型で渡されるプロパティの一覧については、 RequestContext、 SecurityContext、および ProtocolContext クラスの定義を参照してください。

渡されるもう 1 つの入力パラメーターは、 ThreatDetectionLogger 型のロガーです。 このパラメーターを使用して、AD FS ログにエラーメッセージ、監査メッセージ、デバッグ メッセージを書き込むことができます。

このメソッドは、要求をブロックまたは許可する ThrottleStatus (NotEvaluated の場合は 0、ブロックに 1、許可する場合は 2) を 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、SecurityContext securityContext、ProtocolContext protocolContext、 入力パラメーターで渡された情報を使用して、認証後のリスク評価ロジックを記述できます。 <

注

各コンテキスト型で渡されるプロパティの完全な一覧については、 RequestContext、 SecurityContext、および ProtocolContext クラスの定義を参照してください。

渡されるもう 1 つの入力パラメーターは、 ThreatDetectionLogger 型のロガーです。 このパラメーターを使用して、AD FS ログにエラーメッセージ、監査メッセージ、デバッグ メッセージを書き込むことができます。

このメソッドは、AD FS ポリシーおよび要求規則で使用できる リスク スコア を返します。

注

プラグインを機能させるには、メイン クラス (この場合は UserRiskAnalyzer) が ThreatDetectionModule 抽象クラスを派生させる必要があり、上記の 3 つのインターフェイスのうち少なくとも 1 つを実装する必要があります。 dll が登録されると、AD FS は実装されているインターフェイスを確認し、パイプライン内の適切な段階でそれらを呼び出します。

よく寄せられる質問

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

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

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

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

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

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