Active Directory フェデレーション サービス (AD FS) 要求規則言語は、受信要求と送信要求の動作の管理構成要素として機能しますが、要求エンジンは、カスタム規則を定義する要求規則言語のロジックの処理エンジンとして機能します。 要求エンジンによるすべての規則の処理方法の詳細については、「 要求エンジンの役割」を参照してください。
要求規則言語を使用したカスタム要求規則の作成
AD FS は、要求規則言語を使用して ID 要求の動作を判断するために使用できるカスタム規則を定義するオプションを管理者に提供します。 このトピックの要求規則言語構文の例を使用して、組織のニーズに合わせて要求を列挙、追加、削除、および変更するカスタム規則を作成できます。 カスタム要求規則テンプレートを 使用して要求を送信 するで要求規則言語構文を入力することで、カスタム規則を構築できます。
規則はセミコロンで区切られます。
カスタム規則を使用する場合の詳細については、「 カスタム要求規則を使用する場合」を参照してください。
要求規則テンプレートを使用して要求規則言語の構文について学習する
AD FS には、一般的な要求規則の実装に使用できる定義済みの要求発行と要求受け入れ規則テンプレートのセットも用意されています。 特定の信頼の [ 要求規則の編集 ] ダイアログ ボックスで、定義済みの規則を作成し、その規則を構成する要求規則言語構文を表示するには、その規則の [ ルール言語の表示 ] タブをクリックします。 このセクションの情報と ルール言語の表示 手法を使用すると、独自のカスタム ルールを構築する方法に関する分析情報を得ることができます。
要求規則と要求規則テンプレートの詳細については、「要求規則 の役割」を参照してください。
要求規則言語のコンポーネントを理解する
要求規則言語は、"=>" 演算子でそれぞれ区切られた次のコンポーネントから構成されます。
A condition
発行ステートメント
Conditions
ルールの条件を使用して、入力要求を確認し、ルールの発行ステートメントを実行する必要があるかどうかを判断できます。 条件は、ルール本文部分を実行するために true に評価する必要がある論理式を表します。 この部分が見つからない場合は、論理 true が想定されます。つまり、ルールの本文は常に実行されます。 条件部分には、結合論理演算子 (">" と組み合わせた条件の一覧) が含まれています。 条件部分全体を true に評価するには、リスト内のすべての条件を true に評価する必要があります。 条件には、要求選択演算子または集計関数呼び出しのいずれかを指定できます。 これら 2 つは相互に排他的です。つまり、要求セレクターと集計関数を 1 つのルール条件部分で組み合わせることはできません。
ルールでは条件は省略可能です。 たとえば、次のルールには条件がありません。
=> issue(type = "http://test/role", value = "employee");
条件には次の 3 種類があります。
単一の条件 - これは条件の最も単純な形式です。 チェックは 1 つの式に対してのみ行われます。たとえば、Windows アカウント名 = ドメイン ユーザーなどです。
複数の条件 - この条件では、ルール本文で複数の式を処理するための追加のチェックが必要です。たとえば、Windows アカウント名 = ドメイン ユーザーとグループ = contosopurchasers です。
Note
別の条件が存在しますが、単一の条件または複数の条件のサブセットです。 正規表現 (Regex) 条件と呼ばれます。 これは、入力式を受け取り、式を特定のパターンと一致させるために使用されます。 その使用方法の例を次に示します。
次の例では、カスタム ルールの作成に使用できる、条件の種類に基づく構文の構造をいくつか示します。
単一の条件の例
次の表では、単一の -expression 条件について説明します。 指定した要求の種類を持つ要求、または指定した要求の種類と要求値を持つ要求を単にチェックするように構築されています。
| Condition description | 条件構文の例 |
|---|---|
この規則には、指定した要求の種類 ("<http://test/name>" ) を持つ入力要求を確認する条件があります。 一致する要求が入力要求内にある場合、規則は一致する要求または要求を出力要求セットにコピーします。 |
c: [type == "http://test/name"] => issue(claim = c ); |
この規則には、指定した要求の種類 ("<http://test/name>" ) と要求値 ("Terry" ) を持つ入力要求を確認する条件があります。 一致する要求が入力要求内にある場合、規則は一致する要求または要求を出力要求セットにコピーします。 |
c: [type == "http://test/name", value == "Terry"] => issue(claim = c); |
次のセクションでは、複数の要求をチェックする条件、要求の発行者を確認する条件、正規表現パターンに一致する値をチェックする条件など、より多くの -complex 条件を示します。
複数の条件の例
次の表に、複数の -expression 条件の例を示します。
| Condition description | 条件構文の例 |
|---|---|
この規則には、指定された要求の種類 ("<http://test/name>" と "<http://test/email>" ) を持つ 2 つの入力要求を確認する条件があります。 一致する 2 つの要求が入力要求内にある場合、規則は名前要求を出力要求セットにコピーします。 |
c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 ); |
通常の -condition の例
次の表に、正規表現 -based 条件の例を示します。
| Condition description | 条件構文の例 |
|---|---|
| この規則には、正規表現を使用して、"@fabrikam.com" で終わる電子 -mail 要求を確認する条件があります。 入力要求に一致する要求が見つかった場合、規則は一致する要求を出力要求セットにコピーします。 | c: [type == "http://test/email", value =~ "^. +@fabrikam.com$" ] => issue (claim = c ); |
Issuance statements
Custom rules are processed based on the issuance statements (issue or add ) that you program into the claim rule. 目的の結果に応じて、問題ステートメントまたは add ステートメントをルールに書き込み、入力要求セットまたは出力要求セットを設定できます。 add ステートメントを使用するカスタム規則は、入力要求セットにのみ要求値を明示的に設定します。一方、問題ステートメントを使用するカスタム要求規則では、入力要求セットと出力要求セットの両方で要求値が設定されます。 これは、要求の値が、一連の要求規則の将来の規則によってのみ使用されることを意図している場合に役立ちます。
たとえば、次の図では、受信要求が要求発行エンジンによって設定された入力要求に追加されます。 When the first custom claim rule executes and the criteria of ___domain user is satisfied, the claims issuance engine processes the logic in the rule using the add statement, and the value of Editor is added to the input claim set. Because the value of Editor is present in the input claim set, Rule 2 can successfully process the issue statement in its logic and generate a new value of Hello, which is added to both the output claim set and to the input claim set for use by the next rule in the rule set. ルール 3 では、入力要求セットに存在するすべての値を、そのロジックを処理するための入力として使用できるようになりました。
請求を発行する措置
規則本文は、要求発行アクションを表します。 言語で認識される要求発行アクションは 2 つあります。
Issue statement: The issue statement creates a claim that goes to both input and output claim sets. たとえば、次のステートメントは、入力要求セットに基づいて新しい要求を発行します。
c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);Add statement: The add statement creates a new claim that is added only to the input claim set collection. たとえば、次のステートメントは、入力要求セットに新しい要求を追加します。
c:[type == "Name", value == "___domain user"] => add(type = "Role", value = "Editor");
ルールの発行ステートメントは、条件が一致したときにルールによって発行される要求を定義します。 引数とステートメントの動作に関する発行ステートメントには、次の 2 つの形式があります。
Normal—Normal issuance statements can issue claims by using literal values in the rule or the values from claims that match the conditions. 通常の発行ステートメントは、次の形式のいずれかまたは両方で構成できます。
Claim copy: The claim copy creates a copy of the existing claim in the output claim set. この発行フォームは、「issue」発行ステートメントと組み合わせるときにのみ意味があります。 "追加" 発行ステートメントと組み合わせると、効果はありません。
New claim: This format creates a new claim, given the values for various claim properties. Claim.Type を指定する必要があります。その他のすべての要求プロパティは省略可能です。 このフォームの引数の順序は無視されます。
Attribute Store—This form creates claims with values that are retrieved from an attribute store. 1 つの発行ステートメントを使用して複数の要求の種類を作成できます。これは、属性の取得中にネットワークまたはディスクの入出力 (I/O) 操作を行う属性ストアにとって重要です。 そのため、ポリシー エンジンと属性ストアの間のラウンド トリップの数を制限することが望ましいです。 また、特定の種類の要求に対して複数の要求を作成することも有効です。 属性ストアが特定の要求の種類に対して複数の値を返すと、発行ステートメントによって、返された要求値ごとに要求が自動的に作成されます。 属性ストアの実装では、パラメーター引数を使用して、クエリ引数のプレースホルダーを param 引数で指定された値に置き換えます。 プレースホルダーでは、.NET String.Format ( ) 関数と同じ構文を使用します (たとえば、 {1}、 {2}など)。 この形式の発行の引数の順序は重要であり、次の文法で規定されている順序である必要があります。
次の表では、要求規則の両方の種類の発行ステートメントの一般的な構文の構造について説明します。
| 発行ステートメントの種類 | 発行ステートメントの説明 | 発行ステートメントの構文の例 |
|---|---|---|
| Normal | 次の規則は、ユーザーが指定した要求の種類と値を持つたびに、常に同じ要求を出力します。 | c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee"); |
| Normal | 次の規則は、1 つの要求の種類を別の要求の種類に変換します。 条件 "c" と一致する要求の値が発行ステートメントで使用されていることに注意してください。 | c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value ); |
| Attribute store | 次の規則では、受信要求の値を使用して Active Directory 属性ストアのクエリを実行します。 | c: [Type == "http://test/name" ] => issue (store = "Enterprise AD Attribute Store", types = ("http://test/email" ), query = ";mail;{0}", param = c.Value ) |
| Attribute store | 次の規則では、受信要求の値を使用して、以前に構成された構造化クエリ言語 (SQL) 属性ストアに対してクエリを実行します。 | c: [type == "http://test/name"] => issue (store = "Custom SQL store", types = ("http://test/email","http://test/displayname" ), query = "SELECT mail, displayname FROM users WHERE name ={0}", param = c.value ); |
Expressions
式は、クレーム セレクター制約と発行ステートメント パラメーターの両方に対して右側で使用されます。 言語でサポートされる式には、さまざまな種類があります。 言語内のすべての式は文字列ベースです。つまり、文字列を入力として受け取り、文字列を生成します。 式内の数値やその他のデータ型 (日付/時刻など) はサポートされていません。 言語でサポートされる式の種類を次に示します。
文字列リテラル: 両側の引用符 (" ) 文字で区切られた文字列値。
式の文字列連結: 結果は、左と右の値の連結によって生成される文字列です。
関数呼び出し: 関数は識別子によって識別され、パラメーターは角かっこ (" ( )" で囲まれた式のコンマ -delimited リストとして渡されます。
変数名 DOT プロパティ名という形式で要求のプロパティにアクセスします: 特定の変数評価に基づいて識別された要求プロパティの値の結果を取得します。 この方法で変数を使用するには、最初に要求セレクターにバインドする必要があります。 同じ要求セレクターの制約内で要求セレクターにバインドされている変数を使用することは無効です。
アクセスには、次の要求プロパティを使用できます。
Claim.Type
Claim.Value
Claim.Issuer
Claim.OriginalIssuer
Claim.ValueType
Claim.Properties[property_name] (プロパティ _nameが要求のプロパティ コレクションに見つからない場合、このプロパティは空の文字列を返します)。
RegexReplace 関数を使用して、式内で呼び出すことができます。 この関数は入力式を受け取り、指定されたパターンと一致します。 パターンが一致する場合、一致の出力は置換値に置き換えられます。
Exists functions
Exists 関数は、条件に一致する要求が入力要求セットに存在するかどうかを評価するために、条件で使用できます。 一致する要求が存在する場合、発行ステートメントは 1 回だけ呼び出されます。 次の例では、入力要求セット コレクション内に発行元 (issuer) が "MSFT" に設定されている要求が 1 つでもあれば、"origin" 要求が 1 回だけ発行されます。発行元 (issuer) が "MSFT" に設定されている要求がいくつあるかは関係ありません。 この関数を使用すると、重複する要求が発行されなくなります。
exists([issuer == "MSFT"])
=> issue(type = "origin", value = "Microsoft");
Rule body
ルール本文に含めることができる発行ステートメントは 1 つだけです。 Exists 関数を使用せずに条件を使用すると、条件部分が一致するたびにルール本文が 1 回実行されます。
Additional references
カスタム ルール を使用して要求を送信する規則を作成する