要求規則言語の役割
Active Directory フェデレーション サービス (AD FS) の要求規則言語は、入力方向および出力方向の要求の動作の管理用構成要素として機能します。一方、要求エンジンは、カスタムの規則を定義する要求規則言語のロジックの処理エンジンとして機能します。 要求エンジンですべてのルールを処理する方法の詳細についてを参照してください 要求エンジンの役割します。
要求規則言語を使用したカスタム要求規則の作成
AD FS では、管理者を使用して要求規則言語の id 要求の動作を決定するカスタムの規則を定義するオプションを提供します。 このトピックの要求規則言語の構文例を使用して、組織のニーズに合わせて、要求を列挙、追加、削除、および削除するカスタム規則を作成できます。 カスタム規則は、"カスタム規則を使用して要求を送信する" テンプレートに要求規則言語構文を入力することで作成できます。
複数の規則を指定する場合は規則をセミコロンで区切ります。
詳細については、カスタム ルールを使用する場合、次を参照してください。 カスタム要求規則を使用する場合します。
要求規則テンプレートを使用して要求規則言語の構文を理解する
AD FS では、定義済みのクレームの発行とクレームの一般的な実装に使用できるルール テンプレートを承認要求規則のセットも提供します。 特定の信頼の [要求規則の編集] ダイアログ ボックスでは、定義済みの規則を作成できます。また、規則の [規則言語の表示] タブをクリックして、その規則を構成する要求規則言語構文を表示できます。 このセクションの情報と [規則言語の表示] を使用すると、独自のカスタム規則を作成する方法を把握できます。
要求規則および要求規則テンプレートについては詳細を参照してください。 [要求規則の役割します。
要求規則言語のコンポーネントを理解する
要求規則言語は、"=>" 演算子でそれぞれ区切られた次のコンポーネントから構成されます。
条件
発行ステートメント
条件
規則内で条件を使用すると、入力要求をチェックして、規則の発行ステートメントを実行するかどうかを判断することができます。 条件とは論理式のことで、規則の本文部分を実行するにはこの条件が true に評価される必要があります。 この部分が指定されていない場合、論理 true が想定され、規則の本文は常に実行されます。 条件部分には、論理積演算子 (“&&” ) で連結された条件のリストが含まれます。 条件部分全体が true に評価されるためには、リスト内のすべての条件が true に評価される必要があります。 条件には、要求選択演算子または集計関数呼び出しのいずれかを指定できます。 これらの 2 つは相互に排他的です。つまり、1 つの規則の条件部分で要求セレクターと集計関数を組み合わせることはできません。
規則において、条件は省略できます。 たとえば、次の規則には条件がありません。
=> issue(type = "http://test/role", value = "employee");
条件には次の 3 種類があります。
単一の条件 — これは条件の最も単純な形です。 1 つの式のみがチェックされます (例: windows account name = domain user)。
複数の条件 — この条件では、規則の本文内の複数の式を処理するために追加のチェックが必要になります (例: windows account name = domain user と group = contosopurchasers)。
注意
条件にはもう 1 種類ありますが、その条件は単一の条件または複数の条件のサブセットになります。 これは、正規表現 (Regex) 条件と呼ばれます。 この条件は、入力式を受け取り、式を指定されたパターンと照合するために使用されます。 使用例を次に示します。
以降の例に、カスタム規則を作成するために使用できるいくつかの構文構造を条件の種類別に示します。
単一の条件の例
次の表では、単一式条件について説明します。 単一の条件は、指定された要求の種類を持つ要求や指定された要求の種類と要求値を持つ要求があるかどうかを単に確認するために使用します。
| 条件の説明 | 条件の構文の例 |
|---|---|
この規則には、指定された要求の種類 ("<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); |
次のセクションでは、複数の要求の有無をチェックする条件、要求の発行元をチェックする条件、正規表現パターンに一致する値の有無をチェックする条件など、さらに複雑な条件について説明します。
複数の条件の例
次の表に、複数式条件の例を示します。
| 条件の説明 | 条件の構文の例 |
|---|---|
この規則には、それぞれ指定された要求の種類 ("<http://test/name>" と "<http://test/email>") を持つ 2 つの入力要求があるかどうかをチェックする条件が含まれています。 規則に一致する 2 つの要求が入力要求に含まれている場合、その名前要求が出力要求セットにコピーされます。 |
c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 ); |
正規表現の条件の例
次の表に、正規表現ベースの条件の例を示します。
| 条件の説明 | 条件の構文の例 |
|---|---|
| この規則には、正規表現を使用して "@fabrikam.com" で終わる電子メール要求があるかどうかをチェックする条件が含まれています。 規則に一致する要求が入力要求に見つかった場合、その要求が出力要求セットにコピーされます。 | c: [type == "http://test/email", value =~ "^. +@fabrikam.com$" ] => issue (claim = c ); |
発行ステートメント
カスタム規則は、要求規則にプログラミングした発行ステートメント (issue または add) に基づいて処理されます。 目的の結果に応じて issue ステートメントまたは add ステートメントを規則に組み込んで、入力要求セットまたは出力要求セットに値を設定します。 add ステートメントを明示的に使用するカスタム規則では、入力要求セットのみに要求値が設定されます。一方、issue ステートメントを使用するカスタム要求規則では、入力要求セットと出力要求セットの両方に要求値が設定されます。 これは、要求値が要求規則のセット内の将来の規則でのみ使用される場合に便利です。
たとえば、次の図において、入力方向の要求は要求発行エンジンによって入力要求セットに追加されます。 最初のカスタム要求規則が実行され、"domain user" の条件が満たされると、要求発行エンジンによって、add ステートメントを使用して規則内のロジックが処理され、値 Editor が入力要求セットに追加されます。 エディターの値が入力クレーム セットに存在するため、ルール 2 を正常に処理、ロジック内で問題ステートメントおよびの新しい値を生成する こんにちは, 、クレーム セットおよびルールの次のルールで使用する設定の入力要求を次のように設定します。 両方の出力に追加されます。 ルール 3 では、セットをそのロジックを処理するための入力として入力方向の要求に存在する値をすべて使用できるようになりました。
要求の発行操作
規則の本文は、要求の発行操作を表します。 この言語で認識される要求の発行操作には、次の 2 つがあります。
Issue ステートメント: issue ステートメントは、入力要求セットと出力要求セットの両方に対する要求を作成します。 たとえば、次のステートメントは、入力要求セットに基づいて新しい要求を発行します。
c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);Add ステートメント: add ステートメントは、入力要求セットのコレクションにのみ追加される新しい要求を作成します。 たとえば、次のステートメントは、入力要求セットに新しい要求を追加します。
c:[type == "Name", value == "domain user"] => add(type = "Role", value = "Editor");
規則の発行ステートメントは、条件が満たされたときに規則によって発行される要求を定義します。 引数とステートメントの動作の点で、発行ステートメントには次の 2 つの形式があります。
通常 — 通常の発行ステートメントでは、規則内のリテラル値または条件に一致する要求からの値を使用して要求を発行できます。 通常の発行ステートメントは、次の形式のどちらかまたは両方で構成できます。
要求のコピー: 要求のコピーは、既存の要求のコピーを出力要求セットに作成します。 この発行形式は、"issue" 発行ステートメントと組み合わせた場合にのみ有効になります。 "add" 発行ステートメントと組み合わせた場合は効果はありません。
新しい要求: この形式は、さまざまな要求プロパティの値に基づいて新しい要求を作成します。 Claim.Type を指定する必要があります。それ以外の要求プロパティは省略できます。 この形式では、引数の順序は無視されます。
属性ストア — この形式では、属性ストアから取得された値を使用して要求が作成されます。 単一の発行ステートメントを使用して複数の要求の種類を作成できます。これは、属性の取得中にネットワークまたはディスク入出力 (I/O) 操作を行う属性ストアに重要です。 そのため、ポリシー エンジンと属性ストアの間のラウンド トリップの数を制限することをお勧めします。 また、特定の要求の種類に対して複数の要求を作成することもできます。 属性ストアから特定の要求の種類に対して複数の値が返されると、発行ステートメントは、返された要求値のそれぞれに対して要求を自動的に作成します。 属性ストアの実装では、param 引数を使用して、クエリ引数内のプレースホルダーが param 引数に指定された値で置き換えられます。 プレースホルダーの構文は、.NET の String.Format() 関数の構文と同じです (たとえば、{1}、{2})。 この発行形式では、引数の順序が重要であり、次に示す文法に示されている順序に従う必要があります。
次の表では、要求規則の発行ステートメントの両方の種類について、いくつかの一般的な構文構造を示します。
| 発行ステートメントの種類 | 発行ステートメントの説明 | 発行ステートメントの構文例 |
|---|---|---|
| Normal | 次の規則は、ユーザーが指定された要求の種類と値を持つときに常に同じ要求を発行します。 | c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee"); |
| Normal | 次の規則は、ある要求の種類を別の要求の種類に変換します。 条件 "c" に一致する要求の値が発行ステートメントに使用されていることに注目してください。 | c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value ); |
| 属性ストア | 次のルールでは、入力方向の要求の値を使用して、Active Directory 属性ストアを照会します。 | c: [Type == "http://test/name" ] => issue (store = "Enterprise AD Attribute Store", types = ("http://test/email" ), query = ";mail;{0}", param = c.Value ) |
| 属性ストア | 次の規則は、入力方向の要求の値を使用して、事前に構成済みの構造化照会言語 (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 ); |
式
式は、要求セレクター制約と発行ステートメント パラメーターのどちらについても、右辺で使用します。 この言語でサポートされる式にはさまざまな種類があります。 この言語のすべての式は文字列ベースであるため、入力として受け取った文字列から文字列を生成します。 式では、数字やその他のデータ型 (たとえば、日時) はサポートされません。 この言語でサポートされる式の種類を次に示します。
文字列リテラル: 文字列値。両側を引用符 (") で区切ります。
式の文字列の連結: 結果は、左辺の値と右辺の値の連結によって生成された文字列です。
関数呼び出し: 関数は、識別子によって特定されます。パラメーターは、かっこ ("()") で囲まれたコンマ区切りの式のリストとして渡されます。
"<変数名>.(ドット)<プロパティ名>" 形式の要求のプロパティへのアクセス: 特定の変数の評価に対して識別された要求のプロパティの値の結果。 変数は、この形式で使用する前に要求セレクターにバインドする必要があります。 同じ要求セレクターの制約内の要求セレクターにバインドされた変数を使用することはできません。
次の要求プロパティを使用できます。
Claim.Type
Claim.Value
Claim.Issuer
Claim.OriginalIssuer
Claim.ValueType
Claim.Properties[property_name] (property_name が要求のプロパティ コレクション内に見つからない場合、このプロパティは空の文字列を返します)。
RegexReplace 関数を式内で使用して呼び出すことができます。 この関数は、入力式を受け取り、指定されたパターンと照合します。 パターンが一致すると、一致の出力が置換値に置き換えられます。
Exists 関数
Exists 関数を条件内で使用すると、条件に一致する要求が入力要求セット内に存在するかどうかを評価できます。 条件に一致する要求が存在すると、発行ステートメントが 1 回だけ呼び出されます。 次の例では、入力要求セット コレクション内に発行元 (issuer) が "MSFT" に設定されている要求が 1 つでもあれば、"origin" 要求が 1 回だけ発行されます。発行元 (issuer) が "MSFT" に設定されている要求がいくつあるかは関係ありません。 この関数を使用すると、重複する要求が発行されるのを防ぐことができます。
exists([issuer == "MSFT"])
=> issue(type = "origin", value = "Microsoft");
規則の本文
規則の本文には、発行ステートメントを 1 つだけ含めることができます。 Exists 関数を指定せずに条件を使用した場合、その条件部分が満たされるたびに規則の本文が 1 回実行されます。
その他の参照情報
フィードバック
以下は間もなく提供いたします。2024 年を通じて、コンテンツのフィードバック メカニズムとして GitHub の issue を段階的に廃止し、新しいフィードバック システムに置き換えます。 詳細については、「https://aka.ms/ContentUserFeedback」を参照してください。
フィードバックの送信と表示