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

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

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

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

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

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

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

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

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

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

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

• Условие

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

Условия

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

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

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

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

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

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

Примечание.

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

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

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

Условия единичного -expression описаны в следующей таблице. Они создаются для простой проверки утверждения с указанным типом утверждения или для утверждения с указанным типом утверждения и значением утверждения.

Описание условия	Пример синтаксиса условия
Это правило имеет условие для проверки входного утверждения с указанным типом утверждения ("<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.

Описание условия	Пример синтаксиса условия
Это правило имеет условие для проверки двух входных утверждений, каждый из которых содержит указанный тип утверждения ("<http://test/name>" и "<http://test/email>". Если два совпадающих утверждения находятся в входных утверждениях, правило копирует утверждение имени в выходной набор утверждений.	c1: [type == "http://test/name"] && c2: [type == "http://test/email"] => issue (claim = c1 );

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

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

Описание условия	Пример синтаксиса условия
Это правило содержит условие, которое использует регулярное выражение для проверки утверждения типа e -mail, оканчивающегося на "@fabrikam.com". Если соответствующее утверждение найдено в входных утверждениях, правило копирует соответствующее утверждение в выходной набор утверждений.	c: [type == "http://test/email", value =~ "^. +@fabrikam.com$" ] => issue (claim = c );

Заявления о выпуске

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

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

роли AD FS

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

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

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

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

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

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

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

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

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

  • новая заявка: этот формат создает новую заявку, учитывая значения для различных свойств заявки. 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):	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 );

Выражения

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

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

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

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

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

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

• Claim.Type

• Claim.Value

• Утверждение.Издатель

• Claim.OriginalIssuer

• Claim.ValueType

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

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

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

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

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

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

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

Дополнительные ссылки

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