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

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

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

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

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

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

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

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

Дополнительные сведения о правилах утверждений и шаблонах правил утверждений см. в разделе "Роль правил утверждений".

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

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

• Условие

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

Условия

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

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

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

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

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

• Для обработки нескольких выражений в тексте правила требуется дополнительное проверка; например, имя учетной записи Windows = пользователь домена и группа = 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>" и "<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 );

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

Пользовательские правила обрабатываются на основе инструкций выдачи (выдачи или добавления ), которые вы программируете в правило утверждения. В зависимости от требуемого результата инструкцию вопроса или инструкцию add можно записать в правило, чтобы заполнить входной набор утверждений или выходной набор утверждений. Пользовательское правило, использующее инструкцию add, явно заполняет значения утверждений только входным набором утверждений, в то время как настраиваемое правило утверждения, использующее инструкцию вопроса, заполняет значения утверждений как в наборе входных утверждений, так и в выходном наборе утверждений. Это может быть полезно, если значение утверждения предназначено только для будущих правил в наборе правил утверждений.

Например, на следующем рисунке входящее утверждение добавляется в входное утверждение, заданное подсистемой выдачи утверждений. Когда выполняется первое пользовательское правило утверждения и критерии пользователя домена, подсистема выдачи утверждений обрабатывает логику в правиле с помощью инструкции add, а значение editor добавляется в входной набор утверждений. Так как значение редактора присутствует в входном наборе утверждений, правило 2 может успешно обработать оператор проблемы в своей логике и создать новое значение Hello, которое добавляется как к набору выходных утверждений, так и к входному утверждению, заданному для использования следующим правилом в наборе правил. Правило 3 теперь может использовать все значения, которые присутствуют в входном наборе утверждений в качестве входных данных для обработки логики.

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

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

• Заявление о проблеме. Оператор вопроса создает утверждение, которое передается как входным, так и выходным наборам утверждений. Например, следующая инструкция выдает новое утверждение на основе входного набора утверждений:

  c:[type == "Name"] => issue(type = "Greeting", value = "Hello " + c.value);

• Добавление инструкции. Инструкция add создает новое утверждение, которое добавляется только в коллекцию входных наборов утверждений. Например, следующая инструкция добавляет новое утверждение в набор входных утверждений:

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

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

• Обычные — обычные операторы выдачи могут выдавать утверждения с помощью литеральных значений в правиле или значений из утверждений, которые соответствуют условиям. Обычный оператор выдачи может состоять из одного или обоих из следующих форматов:

  • Копия утверждений: копия утверждения создает копию существующего утверждения в выходном наборе утверждений. Эта форма выдачи имеет смысл только в том случае, если она сочетается с оператором выдачи "issue". Если он сочетается с оператором выдачи add, он не имеет никакого эффекта.

  • Новое утверждение: этот формат создает новое утверждение, учитывая значения для различных свойств утверждений. Claim.Type необходимо указать; все остальные свойства утверждения являются необязательными. Порядок аргументов для этой формы игнорируется.

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

Выражения

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

• Строковый литерал: строковое значение, разделенное символом кавычки (" ) на обеих сторонах.

• Объединение строк выражений: результатом является строка, созданная объединением левых и правых значений.

• Вызов функции: функция определяется идентификатором, и параметры передаются в виде разделенного запятыми списка выражений, заключенных в скобки (" ()".

• Доступ к свойству утверждения в виде имени свойства DOT переменной: результат значения свойства определенного утверждения для заданной оценки переменной. Переменная сначала должна быть привязана к селектору утверждений, прежде чем его можно будет использовать таким образом. Недопустимо использовать переменную, привязанную к селектору утверждений внутри ограничений для того же селектора утверждений.

Для доступа доступны следующие свойства утверждений:

• Claim.Type

• Claim.Value

• Claim.Issuer

• Claim.OriginalIssuer

• Claim.ValueType

• Claim.Properties[property_name] (Это свойство возвращает пустую строку, если свойство _name не удается найти в коллекции свойств утверждения).

Функцию RegexReplace можно использовать для вызова внутри выражения. Эта функция принимает входное выражение и сопоставляет его с заданным шаблоном. Если шаблон совпадает, выходные данные совпадения заменяются значением замены.

Существуют функции

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

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

Текст правила

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

Дополнительная справка

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