宣告規則語言的角色

發行項
02/13/2024

Active Directory 同盟服務 (AD FS) 宣告規則語言做為傳入和傳出宣告之行為的系統管理建置組塊，而宣告引擎做為定義自訂規則的宣告規則語言中邏輯的處理引擎。如需宣告引擎如何處理所有規則的詳細資訊，請參閱宣告引擎的角色。

使用宣告規則語言建立自訂宣告規則

AD FS 可讓系統管理員選擇定義自訂規則，以便使用宣告規則語言來決定身分識別宣告的行為。您可以使用本主題中的宣告規則語言語法範例來建立自訂規則，以便列舉、加入、刪除和修改宣告以符合您的組織需求。您可以在 [使用自訂宣告傳送宣告] 規則範本中鍵入宣告規則語言語法，以建立自訂的規則。

規則會以分號分隔彼此。

如需何時使用自訂規則的詳細資訊，請參閱何時使用自訂宣告規則。

使用宣告規則範本來了解宣告規則語言語法

AD FS 也提供一組預先定義的宣告發佈，和可用來實作常見宣告規則的宣告接受規則範本。在給定信任的 [編輯宣告規則] 對話方塊中，您可以建立預先定義的規則，並檢視組成該規則的宣告規則語言語法，方法是按一下該規則的 [檢視規則語言] 索引標籤。使用本節的資訊和 [檢視規則語言] 技術可深入了解如何建構您自己的自訂規則。

如需宣告規則和宣告規則範本的詳細資訊，請參閱宣告規則的角色。

了解宣告規則語言的元件

宣告規則語言包含下列元件，以 “ =>” 運算子區隔：

條件
發佈陳述式

條件

您可以使用規則中的條件來檢查輸入宣告，並判斷是否應該執行規則的發佈陳述式。條件表示必須評估為 true 來執行規則主體部分的邏輯運算式。如果遺失此組件會假設邏輯為 true，也就是一律執行規則的主體。條件部分包含與 conjunction 邏輯運算子 (“&&”) 組合在一起的條件清單。清單中的所有條件必須都評估為 true，才會將整個條件組件評估為 true。條件可以是宣告選取運算子或彙總函式呼叫。這兩個條件是互斥的，這表示宣告選取器和彙總函式不能合併在單一規則條件組件中。

條件在規則中為選用。例如，下列規則沒有條件：

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

有三種類型的條件：

單一條件—這是最簡單的條件形式。只會針對一個運算式進行檢查；例如，windows account name = domain user。
多個條件—這種情況需要額外的檢查，才能處理規則主體中的多個運算式；例如，windows account name = domain user and group = contosopurchasers。

注意

存在另一個條件，但它是單一條件或多個條件的子集。這被稱為規則運算式 (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`>" and "<`http://test/email`>")。如果兩個符合的宣告位於輸入宣告中，則規則會將名稱宣告複製到輸出宣告集。	`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 的值加入至輸入宣告集。由於 Editor 的值會出現在輸入宣告集合中，因此規則 2 可在其邏輯中成功處理 issue 陳述式，並產生 Hello 的新值，系統會其新增到輸出宣告集和輸入宣告集，供規則集內的下一個規則使用。規則 3 現在可將輸入宣告集內出現的所有值做為輸入來處理其邏輯。

AD FS roles

宣告發佈動作

規則主體表示宣告發佈動作。語言可辨識兩種宣告發佈動作：

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");

規則的發佈陳述式定義在符合條件時，規則將發佈的宣告。有兩種與引數和陳述式行為相關的發佈陳述式：

Normal—Normal 發佈陳述式可使用規則中的常值或符合條件的宣告中值，以發出宣告。 normal 發佈陳述式可以包含一或兩個下列格式：
- 宣告複製：宣告複製會在輸出宣告集中建立現有宣告的副本。只有與 "issue" 發佈陳述式結合時，此發佈形式才有意義。若是與 “add” 發佈陳述式結合，則它沒有任何作用。
- 新宣告：此格式可創立新的宣告，提供各種宣告屬性的值。必須指定 Claim.Type，所有其他宣告屬性是選擇性的。會忽略此格式的引數順序。
屬性存放區—這種格式會建立宣告，包含從屬性存放區擷取的值。可以使用單一發佈陳述式建立多個宣告類型，對屬性擷取期間進行網路或磁碟輸入/輸出 (I/O) 作業的屬性存放區很重要。因此，最好限制原則引擎與屬性存放區之間的往返次數。也可合法對指定的宣告類型建立多個宣告。當屬性存放區傳回指定宣告類型的多個值時，發佈陳述式會自動為每個傳回的宣告值建立一個宣告。屬性存放區實作使用 param 引數，使用這些引數所提供的值來替代查詢引數中的預留位置。預留位置使用 .NET String.Format() 函式相同的語法 (例如 {1}、{2} 等等)。此發佈格式的引數順序很重要，而且必須是下列文法中規定的順序。

下表為宣告規則中兩種發佈陳述式描述一些常見的語法建構。

發佈陳述式類型	發佈陳述式描述	發佈陳述式語法範例
正常	每當使用者具有指定的宣告類型和值，下列規則永遠會發出相同的宣告：	`c: [type == "http://test/employee", value == "true"] => issue (type = "http://test/role", value = "employee");`
正常	下列規則會將一種宣告類型轉換成另一種。請注意，符合條件 "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 函式可用於條件中，評估輸入宣告集內是否有符合條件的宣告。如果存在任何相符的宣告，只會呼叫發佈陳述式一次。在下列範例中，如果宣告集合中至少有一個宣告將簽發者設為 "MSFT"，“origin” 宣告只會發佈一次 (無論有多少宣告將簽發者設為 "MSFT")。使用此函式可避免發佈重複的宣告。

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

規則主體

規則主體只能包含單一發佈陳述式。如果不使用 Exists 函數來使用條件，則每當條件組件符合時，會執行一次規則主體。

其他參考

建立規則使用自訂規則傳送宣告

共用方式為