Преобразование утверждений

При аутентификации через сторонний ЦИ на сервер передается маркер доступа, содержащий некоторый набор утверждений о пользователе. Некоторые ЦИ позволяют настраивать содержимое маркера, но часто такой возможности нет.

Для успешной аутентификации в ЦИ должен быть предоставлен маркер, содержащий два утверждения:

  • Name
    SAML: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
    JWT: unique_name
  • Role
    SAML: http://schemas.microsoft.com/ws/2008/06/identity/claims/role
    JWT: role

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

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

Правила преобразования утверждений

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

Каждое правило состоит из двух частей:

  1. Селектора, определяющего какие входящие утверждения должны обрабатываться правилом.
  2. Модификатора, определяющего какие действия нужно сделать с выбранными селектором утверждениями.

Общий вид правила:

id:[condition]=>action(body);

Процесс преобразования состоит из следующих шагов:

  1. Копирование всех входящих утверждений в рабочий набор.
  2. Применение селектора для выбора утверждений из рабочего набора.
  3. Применение модификатора для всех утверждений, выбранных селектором.
  4. Сохранение результата в рабочий набор и (опционально) в выходной набор.
  5. Шаги 2-4 повторяются для каждого правила.
  6. Результатом работы является выходной набор утверждений.

Рассмотрим более подробно каждый компонент правила.

Селекторы

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

id:[condition]

, где

  1. id - идентификатор выбранного утверждения, с помощью этого идентификатора на выбранное утверждение можно ссылаться в модификаторе.
  2. condition - условие выбора. Если в рабочем наборе есть утверждение, удовлетворяющее условию, оно будет передано модификатору и ему будет присвоен идентификатор id.

Условия бывают двух видов:

  1. Пустое условие: id:[] - под это условие подходит любое утверждение.
  2. Выборка по свойству утверждения: id:[prop1 == value1, prop2 == value2] - под это условие подходит утверждение, свойство prop1 которого равно value1, свойство prop2 равно value2.

Утверждение обладает следующими свойствами:

  1. type - тип утверждения.
  2. value - значение утверждения.

В условии могут быть указаны все свойства, либо только часть из них.

Если селектор не нашел подходящих под условие утверждений, модификатор не вызывается.

В правиле можно использовать несколько селекторов, при этом модификатор выполняется только в том случае, если удовлетворены условия всех селекторов (то есть все селекторы нашли хотя бы одно утверждение). При указании нескольких селекторов правило имеет вид

id1:[condition] && id2:[condition]=>action(body)

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

К агрегатным селекторам относятся

Пустой селектор

=>action(body)

Условие данного селектора всегда выполняется, поэтому модификатор всегда будет выполнен. Данный селектор подходит для добавления в выходные утверждения с константным значением и типом.

Функция EXISTS

EXISTS([condition])=>action(body)

Если существуют утверждения, удовлетворяющие условию данного селектора, то модификатор будет выполнен.

Функция NOT EXISTS

NOT EXISTS([condition])=>action(body)

Если не существуют утверждения, удовлетворяющие условию данного селектора, то модификатор будет выполнен.

Функция COUNT

COUNT([condition]) op int=>action(body)

Данный селектор вычисляет количество утверждений, удовлетворяющий условию, и сравнивает его с заданным значением int с помощью соответствующей операции сравнения op. В качестве op может выступать >, >=, <, <=, ==, !=, если результат сравнения истина, то будет выполнен модификатор.

Модификаторы

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

action(body)

, где

  • action - действие. Можете принимать значение issue или add. Действие issue добавляет модифицированное утверждение в рабочий и выходной набор утверждений, действие add - только в рабочий.
  • body - тело модификатора, определяющее, какую операцию нужно сделать с выбранным утверждением.

Модификатор может выполнять две операции: копирование утверждения и создание нового утверждения. Далее рассмотрим каждую операцию подробно.

Копирование утверждения

Выбранное утверждение копируется в соответствующий набор(ы) без изменений. Тело модификатора имеет вид

claim=id

Модификатор позволяет ссылаться только на один идентификатор.

Пример

c1:[type == "email"] => issue(claim = c1);

Создание нового утверждения

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

type = type_value, value = value_value

В качестве type_value и value_value могут выступать следующие выражения:

Строковые литералы

Строки, заключенные в кавычки.

Пример

c1:[type == "role", value="admin"] => issue(type = "main_role", value = "admin");

Свойства выбранных утверждений

Можно ссылаться на свойства type и value выбранных селектором утверждений, используя идентификаторы.

Пример

c1:[type == "role"] => issue(type = "main_role", value = с1.value);

Конкатенация значений

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

Пример

c1:[type == "role"] => issue(type = c1.type + "_ext", value = с1.value + "_ext");

Функция REPLACE

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

Функция имеет вид

REPLACE(old_val, new_val, arg)

Пример

c1:[type == "role"] => issue(type = c1.type, value = REPLACE("admin", "admins", c1.value));

Количество результирующих утверждений

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

Пример

Рассмотрим следующий входной набор утверждений

{ Type : "email", Value : "test@example.com" }
{ Type : "email", Value : "test2@example.com" }
{ Type : "role", Value : "admin" }
{ Type : "role", Value : "user" }

Пусть задано следующее правило преобразования:

c1:[type == "role"] && c2:[type == "email"] => issue(type = c1.value + c2.type, value = c2.value);

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

{ Type : "adminemail", Value : "test@example.com" }
{ Type : "adminemail", Value : "test2@example.com" }
{ Type : "useremail", Value : "test@example.com" }
{ Type : "useremail", Value : "test2@example.com" }