クレーム ルール言語の役割

  • [アーティクル]

Active Directory フェデレーション サービス (AD FS) 2.0 のクレーム ルール言語は、受信クレームおよび送信クレームの動作の管理構成要素として機能します。一方、クレーム エンジンは、カスタム ルールを定義するクレーム ルール言語のロジックの処理エンジンとして機能します。すべてのルールがクレーム エンジンによって処理される方法の詳細については、「クレーム エンジンの役割」を参照してください。

Stuart Kwan 氏 (フェデレーション ID グループ主任プログラム マネージャー) がクレーム ルール言語の基本概念を解説する 5 分間のビデオを視聴するには、「クレーム ルール言語の紹介https://go.microsoft.com/fwlink/?LinkId=163262」(英語) (https://go.microsoft.com/fwlink/?LinkId=163262) をクリックして新しいウィンドウでビデオを開いてください。

クレーム ルール言語によるカスタム クレーム ルールの作成

AD FS 2.0 には、ID クレームの動作を決定するために使用できるカスタム ルールをクレーム ルール言語によって定義できる、管理者のためのオプションが用意されています。このトピックで紹介するクレーム ルール言語の構文例を参考にして、組織のニーズに応じてクレームを列挙、追加、削除、変更するカスタム ルールを作成できます。カスタム ルールを構築するには、[Send Claims Using a Custom Claim] ルール テンプレートにクレーム ルール言語構文を入力します。

ルールどうしはセミコロンで区切ります。

カスタム ルール使用の詳細については、「カスタム クレーム ルールを使用する場合」を参照してください。

クレーム ルール テンプレートでクレーム ルール言語構文を学ぶ

AD FS 2.0 では、定義済みのクレーム発行およびクレーム受け入れルール テンプレートのセットも用意されており、一般的なクレーム ルールの実装に使用できます。特定の信頼の [Edit Claim Rules] ダイアログ ボックスで、定義済みのルールを作成し、そのルールの [View Rule Language] タブをクリックすると、ルールを構成するクレーム ルール言語構文を表示できます。このセクションの説明と [View Rule Language] タブで得られる情報を参考にして、独自のカスタム ルールの構築方法についての理解を深めてください。

クレーム ルールおよびクレーム ルール テンプレートの詳細については、「クレーム ルールの役割」を参照してください。

クレーム ルール言語の構成要素を理解する
クレーム ルール言語は、"=>" 演算子で区切られた次のコンポーネントで構成されます。

  • 条件

  • 発行ステートメント

条件
ルール内で条件を使用することにより、入力クレームをチェックして、ルールの発行ステートメントを実行するかどうかを決定できます。条件は論理式であり、ルールの本体部分が実行されるためには、この式が true (真) として評価される必要があります。条件部分が存在しない場合は、論理値 true と見なされます。つまり、ルールの本体部分は常に実行されます。条件部分には、条件を結合論理演算子 ("&&") で結合したリストが含まれます。条件部分全体が true として評価されるには、リスト内のすべての条件が true と評価される必要があります。条件には、クレーム選択演算子または集約関数の呼び出しを使用できます。これら 2 つは相互に排他的です。つまり、1 つのルールの条件部分内でクレーム セレクターと集約関数を組み合わせることはできません。

条件はルール内で省略可能です。たとえば、次のルールには条件が含まれていません。

=> issue(type = "https://test/role", value = "employee");

条件には次の 2 種類があります。

  • 単一条件: 最も単純な形式の条件です。1 つの式 (たとえば、windows account name = domain\user) についてのみチェックが行われます。

  • 複合条件: この条件は、ルール本体内の複数の式 (たとえば、windows account name = domain\user、group = contosopurchasers) を処理するために追加のチェックを必要とします。

条件にはもう 1 種類ありますが、これは単一条件または複合条件のサブセットです。この種類の条件は、正規表現 (Regex) 条件と呼ばれます。この条件を使用すると、入力式を取得して、式を特定のパターンと一致させることができます。この条件の使用例は、以下で紹介しています。

次の例は、条件の種類別に、いくつかの構文の構成を示しています。カスタム ルール作成の参考にしてください。

単一条件の例

次の表では、式が 1 つだけの条件について説明します。以下に示した条件は、指定された種類のクレームがあるかどうか、あるいは、指定された種類と値を持つクレームがあるかどうかをチェックするように構成されています。

条件の説明 条件構文例
このルールの条件は、指定されたクレームの種類 ("https://test/name") を持つ入力クレームが存在するかどうかをチェックします。入力クレーム内に一致クレームが存在する場合は、ルールによって一致クレームが出力クレーム セットにコピーされます。

コードのコピー

c:[type == "https://test/name"]
    => issue(claim = c);
このルールの条件は、指定されたクレームの種類 ("https://test/name") とクレーム値 ("Terry") を持つ入力クレームが存在するかどうかをチェックします。入力クレーム内に一致クレームが存在する場合は、ルールによって一致クレームが出力クレーム セットにコピーされます。

コードのコピー

c:[type == "https://test/name", value == "Terry"]
    => issue(claim = c);

次のセクションでは、複数のクレームをチェックする条件、クレームの発行者をチェックする条件、正規表現パターンに一致する値をチェックする条件など、より複雑な条件について説明します。

複数条件の例

次の表に、複数の式による条件の例を示します。

条件の説明 条件構文例
このルールの条件は、指定されたクレームの種類 ("https://test/name" と "https://test/email") をそれぞれが持つ 2 つの入力クレームが存在するかどうかをチェックします。入力クレームに 2 つの一致クレームが存在する場合、このルールは name クレームを出力クレーム セットにコピーします。 このルールの条件は、指定されたクレームの種類 ("https://test/name") を持つ入力クレームが存在するかどうかをチェックします。入力クレーム内に一致クレームが存在する場合は、ルールによって一致クレームが出力クレーム セットにコピーされます。

コードのコピー

c1:[type == "https://test/name"] && 
c2:[type == "https://test/email"] => issue(claim = c1)

正規表現条件の例

次の表に、式ベースの正規表現条件の例を示します。

条件の説明 条件構文例
このルールの条件は、正規表現を使用して、"@fabrikam.com" で終わる電子メール クレームが存在するかどうかをチェックします。入力クレーム内に一致クレームが存在する場合は、ルールによって一致クレームが出力クレーム セットにコピーされます。

コードのコピー

c:[type == "https://test/email", value
 =~ "^.+@fabrikam.com$"]
 => issue(claim = c);

発行ステートメント

カスタム ルールは、クレーム ルールにプログラムした発行ステートメント (issue または add) に基づいて処理されます。目的に応じて issue ステートメントまたは add ステートメントをルールに記述することにより、入力クレーム セットまたは出力クレーム セットにクレームを格納できます。add ステートメントを明示的に使用するカスタム クレーム ルールは、クレームの値を入力クレーム セットだけに挿入するのに対して、issue ステートメントを使用するカスタム クレーム ルールは、クレームの値を入力クレーム セットと出力クレーム セットの両方に格納します。これは、クレームの値をクレーム ルール セット内のそれ以降のルールでのみ使用する場合に便利です。

たとえば、次の図では、受信クレームがクレーム発行エンジンによって入力クレーム セットに追加されます。最初のカスタム クレーム ルールが実行され、domain\user の条件が満たされると、クレーム発行エンジンは、add ステートメントを使用してルール内のロジックを処理し、Editor の値が入力クレーム セットに追加されます。Editor の値が入力クレーム セットに存在するため、ルール 2 は、ロジックの issue ステートメントを実行して、新しい値 Hello を生成することができます。この値は、出力クレーム セットと入力クレーム セットの両方に追加され、ルール セット内の次のルールで使用されます。ルール 3 では、入力クレーム セットに存在するすべての値をルール 3 のロジックを処理するための入力として使用できます。

クレーム発行アクション

ルールの本体部分は、クレーム発行アクションを表します。言語が認識できるクレーム発行アクションには、次の 2 つがあります。

  • issue ステートメント: issue ステートメントは、入力クレーム セットと出力クレーム セットの両方に追加されるクレームを作成します。たとえば、次のステートメントは、入力クレーム セットに基づいて新しいクレームを発行します。

    c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);

  • add ステートメント: add ステートメントは、入力クレーム セットのコレクションにのみ追加される新しいクレームを作成します。たとえば、次のステートメントは、入力クレーム セットに新しいクレームを追加します。

    [type == "Name", value == "domain\user"] => add(type = "Role", value = "Editor");

ルールの発行ステートメントは、条件が満たされた場合にルールによって発行されるクレームを定義します。発行ステートメントは、引数とステートメントの動作の点で、次の 2 種類に分けられます。

  • 標準: 標準の発行ステートメントは、ルール内のリテラル値または条件に一致したクレームの値を使用してクレームを発行できます。標準発行ステートメントは、次の 2 つの形式のいずれかまたは両方で構成されます。

    • クレーム コピー: クレーム コピーは、出力クレーム セット内の既存のクレームのコピーを作成します。この発行形式は、"issue" 発行ステートメントと組み合わせる場合にのみ有効です。"add" 発行ステートメントと組み合わせても、何も行われません。

    • 新規クレーム: この形式は、指定されたさまざまなクレーム プロパティの値に基づいて新しいクレームを作成します。Claim.Type の指定は必須ですが、その他のクレーム プロパティはすべて省略可能です。この形式では、引数の順序は無視されます。

  • 属性ストア: この種類の発行ステートメントは、属性ストアから取得した値を使用してクレームを作成します。1 つの発行ステートメントを使用して複数の種類のクレームを作成することが可能です。これは、属性の取得時にネットワークの作成またはディスクの入出力 (I/O) 操作を行う属性ストアにとって重要な動作です。そのため、ポリシー エンジンと属性ストアの間のラウンド トリップ数を制限することが望まれます。また、特定のクレームの種類に対して複数のクレームを作成することができます。特定のクレームの種類に対して属性ストアが複数の値を返す場合、発行ステートメントは、返されたクレームの値ごとに 1 つのクレームを自動的に作成します。属性ストアの実装では、param 引数を使用することにより、query 引数のプレースホルダーを param 引数で提供される値に置き換えます。プレースホルダーは、.NET の String.Format() 関数と同じ構文を使用します (例: {1}、{2} など)。この種類の発行では、引数の順序が重要です。以下に示す文法で規定されている順序にする必要があります。

次の表に、クレーム ルールの 2 種類の発行ステートメントで一般的な構文の構成を示します。

発行ステートメントの種類 発行ステートメントの説明 発行ステートメント構文例
標準 このルールは、ユーザーのクレームが指定された種類と値である場合、常に同じクレームを発行します。

コードのコピー

c:[type == "https://test/employee", value == "true"]
 => issue(type = "https://test/role", value = "employee");
標準 このルールは、クレームの種類を別の種類に変換します。条件 "c" に一致するクレームの値が発行ステートメントで使用されていることに注目してください。

コードのコピー

c:[type == "https://test/group"]
 => issue(type = "https://test/role", value = c.Value);
属性ストア このルールは、受信クレームの値を使用して、Active Directory の属性ストアに照会を行います。

コードのコピー

c:[Type == "https://test/name"]
 => issue(store = "Enterprise AD Attribute Store",
 types = ("https://test/email"),
 query = ";mail;{0}",
 param = c.Value)
属性ストア このルールは、受信クレームの値を使用して、以前に構成された SQL (構造化照会言語) の属性ストアに照会を行います。

コードのコピー

c:[type == "https://test/name"]
 => issue(store = "Custom SQL store",
 types = ("https://test/email","https://test/displayname"),
 query = "SELECT mail, displayname FROM users WHERE name='{0}'",
 param = c.value);

式

式は、クレーム セレクターの制約と発行ステートメントのパラメーターのどちらの場合も、右側で使用されます。この言語では、さまざまな種類の式がサポートされています。言語で使用される式はすべて文字列ベースです。つまり、入力として文字列を取得し、文字列を生成します。式の中で数値型や他のデータ型 (日付/時刻型など) を使用することはできません。次に、言語でサポートされている式の種類を示します。

  • 文字列リテラル: 両側を引用符 (“) で区切られた文字列の値。

  • 式の文字列連結: 結果は、左右の値の連結によって生成された文字列になります。

  • 関数の呼び出し: 関数は識別子によって特定され、パラメーターはかっこ ("()") で囲まれた式のコンマ区切りのリストとして渡されます。

  • "変数名.プロパティ名" の形式によるクレームのプロパティへのアクセス: 指定された変数を評価して得られたクレームのプロパティ値。この方法で変数を使用するには、最初に変数をクレーム セレクターにバインドしておく必要があります。クレーム セレクターにバインドされた変数を同じクレーム セレクターの制約内で使用することはできません。

次のクレーム プロパティにアクセスできます。

  • Claim.Type

  • Claim.Value

  • Claim.Issuer

  • Claim.OriginalIssuer

  • Claim.ValueType

  • Claim.Properties[property_name] (このプロパティは、クレームのプロパティ コレクションで property_name が見つからない場合、空の文字列を返します。)

式の中から RegexReplace 関数を呼び出すことができます。この関数は、入力式を取得し、式を特定のパターンに一致させます。パターンが一致した場合は、一致の結果が置換値に置き換えられます。

Exists 関数

Exists 関数を条件で使用すると、条件に一致するクレームが入力クレーム セットに存在するかどうかを評価できます。一致クレームが存在する場合、発行ステートメントが 1 回だけ呼び出されます。次の例では、入力クレーム セットのコレクションに、発行者が "MSFT" に設定されているクレームが少なくとも 1 つ存在する場合、そのようなクレームがいくつ存在するかに関係なく、"origin" クレームが 1 回だけ発行されます。この関数を使用すると、クレームが重複して発行されることを防ぐことができます。

exists([issuer == "MSFT"])
=> issue(type = "origin", value = "Microsoft");

ルールの本体部分

ルールの本体部分には、発行ステートメントを 1 つだけ含めることができます。Exists 関数を使用せずに条件を使用すると、ルールの本体部分は、条件が満たされるたびに一度実行されます。

その他の参照先

カスタム ルールを使用してクレームを送信するルールを作成する (英語)