適用於:Windows Server 2016、Windows Server 2012 R2、Windows Server 2012Applies To: Windows Server 2016, Windows Server 2012 R2, Windows Server 2012

宣告規則語言的角色The Role of the Claim Rule Language

Active Directory 同盟 Services (AD FS) 取得規則語言作為行為傳入的和傳出宣告的系統建置組塊時宣告引擎做為邏輯操作,以定義自訂規則理賠要求規則語言處理引擎。The Active Directory Federation Services (AD FS ) claim rule language acts as the administrative building block for the behavior of incoming and outgoing claims, while the claims engine acts as the processing engine for the logic in the claim rule language that defines the custom rule. 如需詳細資訊,了解如何處理所有規則宣告引擎、查看的角色宣告引擎的For more information about how all rules are processed by the claims engine, see The Role of the Claims Engine.

建立自訂宣告規則使用語言理賠要求規則Creating custom claim rules using the claim rule language

AD FS 提供系統管理員的選項,來定義自訂規則,他們可以用來判斷身分宣告理賠要求規則語言的行為。AD FS provides administrators with the option to define custom rules that they can use to determine the behavior of identity claims with the claim rule language. 您可以使用此主題中的理賠要求規則語言語法範例建立自訂規則列舉、新增、刪除,以及修改宣告貴組織的需求。You can use the claim rule language syntax examples in this topic to create a custom rule that enumerates, adds, deletes, and modifies claims to meet the needs of your organization. 您可以將自訂規則建置理賠要求規則語言語法中輸入傳送主張使用自訂取得規則範本。You can build custom rules by typing in the claim rule language syntax in the Send Claims Using a Custom Claim rule template.

規則會以分號彼此。Rules are separated from each other with semicolons.

如需有關使用規則自訂的時機,請查看使用自訂理賠要求規則For more information about when to use custom rules, see When to Use a Custom Claim Rule.

若要深入了解理賠要求規則語言語法使用理賠要求規則範本Using claim rule templates to learn about the claim rule language syntax

AD FS 也提供一組預先定義的理賠要求發行和承認,您可以使用來執行一般規則範本取得規則理賠要求。AD FS also provides a set of predefined claim issuance and claim acceptance rule templates that you can use to implement common claim rules. 編輯取得規則對話方塊中指定信任,您可以建立預先定義的規則-和檢視組成該規則理賠要求規則語言語法-,即可檢視規則語言該規則的索引標籤。In the Edit Claim Rules dialog box for a given trust, you can create a predefined rule—and view the claim rule language syntax that makes up that rule—by clicking the View Rule Language tab for that rule. 在本區段中使用的資訊和檢視規則語言技術可以提供深入了解如何建立您自己的自訂規則。Using the information in this section and the View Rule Language technique can provide insight into how to construct your own custom rules.

如需詳細資訊理賠要求規則和理賠要求規則範本,請查看的角色的取得規則For more detailed information about claim rules and claim rule templates, see The Role of Claim Rules.

了解理賠要求規則語言的元件Understanding the components of the claim rule language

宣告規則語言包含下列元件,以「= > [電信業者:The claim rule language consists of the following components, separated by the “ =>” operator:

  • 條件A condition

  • 發行隱私權聲明An issuance statement

條件Conditions

您可以使用規則中條件,請輸入的宣告並判斷是否應該會執行規則的發行聲明。You can use conditions in a rule to check input claims and determine whether the issuance statement of the rule should be executed. 條件代表必須評估邏輯運算式為 true,以執行規則主體部分。A condition represents a logical expression that must be evaluated to true to execute the rule body part. 如果這是遺失,假設邏輯 true;是的一定會執行規則的問候語。If this part is missing, a logical true is assumed; that is, the rule’s body is always executed. 條件組件包含條件結合一起搭配使用的邏輯電信業者的清單 (」與與」)。The conditions part contains a list of conditions that are combined together with the conjunction logical operator (“&&” ). 必須評估清單中所有的條件為 true 評估整個條件部分為 true。All conditions in the list must be evaluated to true for the whole conditional part to be evaluated to true. 這個條件可以是宣告選擇電信業者或彙總函式通話。The condition can be either a claims selection operator or an aggregate function call. 這兩互相專屬,這表示,取得器,無法在單一規則條件部分結合彙總的功能。These two are mutually exclusive, which means that claim selectors and aggregate functions cannot be combined in a single rule conditions part.

條件為選擇性規則。Conditions are optional in rules. 例如,下列規則不需要的條件:For example, the following rule does not have a condition:

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

有三種類型的條件:There are three types of conditions:

  • 單一條件 — 這是最簡單的條件。Single condition—This is the simplest form of a condition. 檢查有針對只有一個運算式;例如,windows 考慮名稱 = 使用者網域。Checks are made for only one expression; for example, windows account name = domain user.

  • 多個條件,這個條件需要其他檢查處理多個運算式本文規則。例如,windows 考慮名稱 = 網域使用者和群組 = contosopurchasers。Multiple condition—This condition requires additional checks to process multiple expressions in the rule body; for example, windows account name = domain user and group = contosopurchasers.

注意

另一個條件存在,但它子集單一條件或多個條件。Another condition exists, but it is a subset of either the single condition or the multiple condition. 這就是運算式 (Regex) 條件。It is referred to as a regular expression (Regex ) condition. 它用來輸入的運算式並符合運算式與指定的模式。It is used to take an input expression and match the expression with a given pattern. 可以使用的方式是一個範例如下所示。An example of how it is can be used is shown below.

下列範例顯示一些語法建構,為基礎的條件類型,您可以使用建立自訂規則。The following examples show a few of the syntax constructions, which are based on the condition types, that you can use to create custom rules.

單一-條件範例Single -condition examples

單一-運算式條件的如下表所示。Single -expression conditions are described in the following table. 只需主張指定的宣告類型或指定的宣告類型的理賠要求檢查並取得值建構。They are constructed to simply check for a claim with a specified claim type or for a claim with a specified claim type and claim value.

條件描述Condition description 條件語法範例Condition syntax example
此規則具有檢查指定的宣告類型 (」http://test/name「) 的輸入宣告條件。This rule has a condition to check for an input claim with a specified claim type ("http://test/name" ). 如果相符理賠要求輸入宣告中,規則複製的符合宣告或輸出宣告組宣告。If a matching claim is in the input claims, the rule copies the matching claim or claims to the output claims set. c: [type == "http://test/name"] => issue(claim = c );
此規則已條件檢查輸入宣告指定的宣告類型 (」http://test/name」),以及取得值 (」Terry」)。This rule has a condition to check for an input claim with a specified claim type ("http://test/name" ) and claim value (“Terry” ). 如果相符理賠要求輸入宣告中,規則複製的符合宣告或輸出宣告組宣告。If a matching claim is in the input claims, the rule copies the matching claim or claims to the output claims set. c: [type == "http://test/name", value == "Terry"] => issue(claim = c);

更多的下一節,包括條件,用來檢查有多個宣告、條件檢查理賠要求的發行者和條件檢查的值符合運算式模式中顯示複雜的條件。More -complex conditions are shown in the next section, including conditions to check for multiple claims, conditions to check the issuer of a claim, and conditions to check for values that match a regular expression pattern.

多個-條件範例Multiple -condition examples

下表中提供的範例的多個-運算式條件。The following table provides an example of multiple -expression conditions.

條件描述Condition description 條件語法範例Condition syntax example
此規則具有來檢查有兩個輸入宣告、條件每一個都有指定的宣告類型(」http://test/name」和「http://test/email」)。This rule has a condition to check for two input claims, each with a specified claim type ("http://test/name" and "http://test/email" ). 如果有兩個符合宣告輸入宣告,規則複製輸出宣告組名稱理賠要求。If the two matching claims are in the input claims, the rule copies the name claim to the output claims set. c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 );

一般-條件範例Regular -condition examples

下表會提供一般,運算式的範例-型條件。The following table provides an example of a regular, expression -based condition.

條件描述Condition description 條件語法範例Condition syntax example
此規則具有條件,使用 e 檢查運算式-結尾的電子郵件宣告並」@fabrikam.com「。This rule has a condition that uses a regular expression to check for an e -mail claim ending in “@fabrikam.com”. 如果輸入宣告中找到符合理賠要求,規則複製輸出宣告組符合理賠要求。If a matching claim is found in the input claims, the rule copies the matching claim to the output claims set. 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. 想要的結果,問題聲明而定,或新增聲明可寫入填入輸入的宣告組規則或輸出宣告設定。Depending on the desired outcome, either the issue statement or add statement can be written into the rule to populate the input claim set or the output claim set. 使用新增聲明明確自訂規則會填入理賠要求時使用的問題聲明自訂宣告規則會填入宣告值這兩個輸入宣告設定和輸出中取得設定,值輸入,才能取得設定。A custom rule that uses the add statement explicitly populates claim values only to the input claim set while a custom claim rule that uses the issue statement populates claim values in both the input claim set and in the output claim set. 宣告值適用於只要未來規則理賠要求規則集中時,這非常有用。This can be useful when a claim value is intended to be used only by future rules in the set of claim rules.

例如,圖,連入宣告被新增到輸入宣告設定宣告發行引擎。For example, in the following illustration, the incoming claim is added to the input claim set by the claims issuance engine. 當的第一個自訂宣告規則執行並滿意網域使用者的準則,宣告發行引擎處理規則使用新增聲明,並值的邏輯編輯器]輸入的宣告設定中新增了。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. 編輯器的值為輸入理賠要求將在因為規則 2 的成功處理問題隱私權聲明中的邏輯和產生為新的Hello的中新增了這兩個輸出取得設定與設定的使用規則中的下一步規則輸入宣告設定。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 現在可以使用所有在於輸入宣告設定為處理其邏輯輸入值。Rule 3 can now use all of the values that are present in the input claim set as input for processing its logic.

AD FS 角色

宣告發行動作Claim issuance actions

規則主體表示宣告發行動作。The rule body represents a claim issuance action. 有兩種語言辨識理賠要求發行動作:There are two claim issuance actions that the language recognizes:

  • 發行隱私權聲明:問題聲明建立移至輸入及輸出取得集理賠要求。Issue statement: The issue statement creates a claim that goes to both input and output claim sets. 例如,下列聲明問題新理賠要求根據其輸入的宣告設定:For example, the following statement issues a new claim based on its input claim set:

    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. 例如,下列隱私權聲明加入新理賠要求輸入的宣告集:For example, the following statement adds a new claim to the input claim set:

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

發行聲明的規則定義宣告將會發出規則時符合的條件。The issuance statement of a rule defines what claims will be issued by the rule when the conditions are matched. 有兩種發行聲明引數和聲明行為相關形式:There are two forms of issuance statements regarding arguments and the statement behavior:

  • 一般-一般發行聲明可發行主張使用規則對應值或來自宣告符合的條件的值。Normal—Normal issuance statements can issue claims by using literal values in the rule or the values from claims that match the conditions. 一般發行隱私權聲明可以包含下列一或多個下列格式:A normal issuance statement can consist of one or both of the following formats:

    • 取得複製: 宣告複製輸出理賠要求將在建立宣告現有的複本。Claim copy: The claim copy creates a copy of the existing claim in the output claim set. 此發行表單只合理時它加上「問題「發行聲明。This issuance form only makes sense when it is combined with the “issue” issuance statement. 時它以 [新增] 的 \ [發行隱私權聲明結合,它不需任何作用。When it is combined with the “add” issuance statement, it does not have any effect.

    • 新的宣告:這格式化 reates 新宣告,請提供的各種取得屬性的值。New claim: This format reates a new claim, given the values for various claim properties. 必須指定 Claim.Type;所有其他宣告屬性是選擇性的。Claim.Type must be specified; all other claim properties are optional. 此表單引數順序會略過。The order of arguments for this form is ignored.

  • 屬性市集:值,從屬性存放區擷取此表單建立主張。Attribute Store—This form creates claims with values that are retrieved from an attribute store. 也可透過單一發行聲明,這很重要,並讓網路或輸入/輸出 (I/O) 操作期間屬性擷取屬性商店建立多個宣告類型。It is possible to create multiple claim types by using a single issuance statement, which is important for attribute stores that make network or disk input/output (I/O ) operations during the attribute retrieval. 因此,它會限制原則引擎和屬性市集之間來回數目。Therefore, it is desirable to limit the number of round trips between the policy engine and the attribute store. 它也是法律建立多個宣告指定的宣告類型。It is also legal to create multiple claims for a given claim type. 屬性網上商店退貨宣告特定的類型的多個值,發行聲明會自動建立每個傳回的宣告值理賠的要求。When the attribute store returns multiple values for a given claim type, the issuance statement automatically creates a claim for each returned claim value. 屬性存放區實作使用參數引數替代查詢引數值參數引數所提供的版面配置。An attribute store implementation uses the param arguments to substitute the placeholders in the query argument with values that are provided in param arguments. 預留位置使用相同的語法為.NET a0()功能(例如,{1}、{2},等等)。The placeholders use the same syntax as the .NET String.Format ( ) function (for example, {1}, {2}, and so on ). 這種發行的引數順序很重要,以及必須在下列文法規定的訂單。The order of the arguments for this form of issuance is important, and it must be the order which is prescribed in the following grammar.

下表描述一些常見的語法建構這兩種類型的發行聲明中理賠要求規則。The following table describes some common syntax constructions for both types of issuance statements in claim rules.

發行隱私權聲明類型Issuance statement type 發行隱私權聲明描述Issuance statement description 發行隱私權聲明語法範例Issuance statement syntax example
一般Normal 下列規則一律會發出相同宣告時使用者的類型指定理賠要求和值:The following rule always emits the same claim whenever a user has the specified claim type and value: c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee");
一般Normal 下列規則會轉換成另一個宣告類型。The following rule converts one claim type into another. 請注意宣告符合的條件 [c] 的值為用於發行聲明。Notice that the value of the claim that matches the condition "c" is used in the issuance statement. c: [type == "http://test/group" ] => issue (type = "http://test/role", value = c.Value );
屬性網上商店Attribute store 下列規則查詢 Active Directory 屬性網上商店使用連入宣告的值:The following rule uses the value of an incoming claim to query the Active Directory attribute store: c: [Type == "http://test/name" ] => issue (store = "Enterprise AD Attribute Store", types = ("http://test/email" ), query = ";mail;{0}", param = c.Value )
屬性網上商店Attribute store 下列規則查詢先前所設定的結構化查詢的語言 (SQL) 屬性網上商店使用連入宣告的值:The following rule uses the value of an incoming claim to query a previously configured Structured Query Language (SQL ) attribute store: 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

運算式用於右側發行隱私權聲明參數和宣告選取器限制。Expressions are used on the right side for both claims selector constraints and issuance statement parameters. 有幾種語言支援運算式。There are various kinds of expressions that the language supports. 所有運算式中的語言都的字串基礎,這表示它們字串需要做的輸入與產生字串。All expressions in the language are string based, which means that they take strings as input and produce strings. 數字或其他資料類型,例如的日期/時間,以運算式不受支援。Numbers or other data types, such as date/time, in expressions are not supported. 以下是運算式語言支援的類型:The following are the types of expressions that the language supports:

  • 常字串:值,以在這兩個側邊報價(')字元分隔的字串。String literal: String value, delimited by the quote (“ ) character on both sides.

  • 字串全名連續運算式:結果是左右值全名連續所建立的字串。String concatenation of expressions: The result is a string that is produced by concatenation of the left and right values.

  • 事件:函式由識別字,並且以逗號傳遞參數-運算式中括弧分隔的清單 (」()」)。Function call: The function is identified by an identifier, and the parameters are passed as a comma -delimited list of expressions enclosed in brackets (“ ( )” ).

  • 宣告的屬性存取點變數名稱屬性名稱的格式:值的辨識理賠要求屬性,指定的變數價值的結果。Claim’s property access in the form of a variable name DOT property name: The result of the value of the identified claim’s property for a given variable valuation. 變數必須先繫結至宣告選取器之前用於這種方式。The variable must first be bound to a claims selector before it can be used in this way. 您不能使用繫結至宣告選取器中限制該相同宣告選擇器的變數。It is illegal to use the variable that is bound to a claims selector inside the constraints for that same claims selector.

適用於存取下列理賠要求屬性︰The following claim properties are available for access:

  • Claim.TypeClaim.Type

  • Claim.ValueClaim.Value

  • Claim.IssuerClaim.Issuer

  • Claim.OriginalIssuerClaim.OriginalIssuer

  • Claim.ValueTypeClaim.ValueType

  • Claim.Properties[property_name](這個屬性如果理賠要求屬性收藏中找不到屬性 _name 傳回空字串。Claim.Properties[property_name] (This property returns an empty string if the property _name cannot be found in the claim’s properties collection. ))

若要撥打電話運算式中,您可以使用 RegexReplace 函式。You can use the RegexReplace function to call inside an expression. 這項功能會輸入的運算式,並比對指定的模式。This function takes an input expression and matches it with the given pattern. 如果符合模式,相符項目的輸出會取代取代值。If the pattern matches, the output of the match is replaced with the replacement value.

有函式Exists functions

存在函式可用於條件評估是否符合的條件存在於輸入宣告設定理賠要求。The Exists function can be used in a condition to evaluate whether a claim that matches the condition exists in the input claim set. 如果有任何符合宣告,發行聲明呼叫一次。If any matching claim exists, the issuance statement is called only once. 下列範例中,在 [來源] 理賠要求發出一次,如果已設定為「MSFT「發行者輸入的宣告設定收藏中的至少一個理賠要求,不論是有許多方式主張發行者為「MSFT」。In the following example, the “origin” claim is issued exactly once—if there is at least one claim in the input claim set collection that has the issuer set to “MSFT”, no matter how many claims have the issuer set to “MSFT”. 使用這項功能將可避免從發行重複宣告。Using this function prevents duplicate claims from being issued.

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

本文規則Rule body

規則主體可能包含只有單一發行聲明。The rule body can contain only a single issuance statement. 如果不使用存在函式條件,規則主體是每當符合的條件部分執行一次。If conditions are used without using the Exists function, the rule body is executed once for each time that the conditions part is matched.

其他參考資料Additional references

建立傳送主張使用自訂規則規則Create a Rule to Send Claims Using a Custom Rule