Роль языка правила утверждения

Язык правил утверждений служб федерации Active Directory (AD FS) служит административной основой для поведения входящих и исходящих утверждений, а механизм обработки утверждений обрабатывает логику языка правил утверждений, которая определяет пользовательское правило. Дополнительные сведения о том, как обрабатываются подсистемой утверждений все правила, см. в разделе Роль подсистемы утверждений.

Создание пользовательских правил утверждений с помощью языка правил утверждений

AD FS предоставляет администраторам возможность задавать пользовательские правила, которые они могут использовать для определения поведения удостоверений с помощью языка правил утверждений. Примеры синтаксиса языка правил утверждений в этом разделе можно использовать для создания настраиваемого правила, которое перечисляет, добавляет, удаляет и изменяет утверждения в соответствии с потребностями вашей организации. Пользовательские правила можно создать, введя синтаксис языка правил утверждений в шаблоне правила Send Claims Using a Custom Claims rule template.

Правила отделяются друг от друга точкой с запятой.

Дополнительные сведения об использовании пользовательских правил см. в разделе Когда следует использовать пользовательское правило утверждения.

Использование шаблонов правил утверждений для изучения синтаксиса языка правила утверждения

AD FS также предоставляет набор стандартных шаблонов правил выдачи утверждений и правил принятия утверждений, которые можно использовать для реализации общих правил утверждений. В диалоговом окне "Изменить правила утверждений" для заданного доверия можно создать предопределенное правило, а также просмотреть синтаксис языка этого правила, щелкнув вкладку "Просмотр языка правила" для данного правила. Используя информацию из этого раздела и технику представления языка правил, можно получить представление о том, как можно создавать собственные пользовательские правила.

Чтобы получить более подробную информацию о правилах утверждений и шаблонах правил утверждений, см. Роль правил утверждений.

Общие сведения о компонентах языка правила утверждения

Язык правил утверждений состоит из следующих компонентов, разделенных оператором "=>":

• A condition

• Инструкция выдачи

Conditions

Вы можете использовать условия в правиле, чтобы проверить входные утверждения и определить, следует ли выполнять инструкцию выдачи правила. Условие представляет логическое выражение, которое должно быть оценено как true для выполнения части текста правила. Если эта часть отсутствует, предполагается логическое значение 'истина'; то есть правило всегда выполняется. Часть условий содержит список условий, объединенных вместе с логическим оператором сочетания ("&&". Все условия в списке должны быть оценены как истинные, чтобы вся условная часть была также оценена как истинная. Условие может быть оператором выбора утверждений или вызовом статистической функции. Эти два являются взаимоисключающими, что означает, что селекторы утверждений и агрегатные функции нельзя объединить в одной части условий правила.

Условия являются необязательными в правилах. Например, следующее правило не имеет условия:

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

Существует три типа условий:

• Одно условие — это простейшая форма условия. Проверки выполняются только для одного выражения; Например, имя учетной записи Windows = пользователь домена.

• Множественное условие — это условие требует дополнительных проверок для обработки нескольких выражений в теле правила; например, "имя учетной записи Windows" = "пользователь домена" и "группа" = contosopurchasers.

Note

Другое условие существует, но это подмножество одного или нескольких условий. Он называется условием регулярного выражения (Regex). Он используется для принятия входного выражения и сопоставления выражения с заданным шаблоном. Ниже показан пример использования.

В следующих примерах показано несколько конструкций синтаксиса, основанных на типах условий, которые можно использовать для создания пользовательских правил.

Примеры отдельных -condition

Условия единичного -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>". Если два совпадающих утверждения находятся в входных утверждениях, правило копирует утверждение имени в выходной набор утверждений.	c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 );

Примеры обычных условий

В следующей таблице приведен пример условия с регулярным выражением -based.

Condition description	Пример синтаксиса условия
Это правило содержит условие, которое использует регулярное выражение для проверки утверждения типа e -mail, оканчивающегося на "@fabrikam.com". Если соответствующее утверждение найдено в входных утверждениях, правило копирует соответствующее утверждение в выходной набор утверждений.	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, явно заполняет значения утверждений только входным набором утверждений, в то время как пользовательское правило, использующее инструкцию issue, заполняет значения утверждений как в наборе входных утверждений, так и в выходном наборе утверждений. Это может быть полезно, если значение переменной утверждения предназначено только для использования будущими правилами в наборе правил утверждений.

Например, на следующем рисунке входящее утверждение добавляется в входное утверждение, заданное подсистемой выдачи утверждений. 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 теперь может использовать все значения, которые присутствуют в входном наборе утверждений в качестве входных данных для обработки логики.

роли AD FS

Действия по выдаче претензий

Тело правила представляет действие по выдаче заявлений. Существуют два действия по выдаче заявлений, которые распознает язык:

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

Утверждение о выдаче правила определяет, какие утверждения будут выдаваться правилом при выполнении условий. Существует две формы утверждений о выдаче относительно аргументов и поведения утверждений.

• 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. Можно создать несколько типов утверждений с помощью одной инструкции выдачи, что важно для хранилищ атрибутов, выполняющих операции ввода-вывода сети или диска во время извлечения атрибута. Поэтому желательно ограничить количество круговых путей между подсистемой политики и хранилищем атрибутов. Также допускается создать несколько требований для заданного типа требований. Когда хранилище атрибутов возвращает несколько значений для заданного типа утверждения, инструкция выдачи автоматически создает утверждение для каждого возвращаемого значения утверждения. Реализация хранилища атрибутов использует аргументы 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 );
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

Функция "Существует" может использоваться в условии для оценки того, существует ли утверждение, соответствующее условию, в входном наборе утверждений. Если существует какой-либо совпадающий запрос, операция выдачи выполняется только один раз. В следующем примере утверждение "origin" выдается ровно один раз — если в коллекции входных утверждений имеется хотя бы одно утверждение, где эмитент установлен на «MSFT», независимо от того, сколько утверждений имеют эмитента, установленного на «MSFT». Использование этой функции предотвращает выдачу повторяющихся утверждений.

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

Rule body

Текст правила может содержать только одну инструкцию выдачи. Если условия используются без использования функции "Существует", текст правила выполняется один раз при каждом сопоставлении части условий.

Additional references

Создайте правило для отправки запросов с помощью настраиваемого правила