OIDC identity tokens

Информация об идентификации используется во всем Stronghold, но её также можно экспортировать для для использования другими приложениями. Авторизованный пользователь/приложение может запросить токен который содержит информацию об идентификации для связанной с ним сущности. Эти токены представляют собой подписанные JWT, соответствующие структуре OIDC ID token. Открытые ключи, используемые для аутентификации токенов, публикуются Stronghold на неаутентифицированном эндпоинте в соответствии с соглашениями OIDC discovery и JWKS, которые которые должны быть непосредственно использованы библиотеками JWT/OIDC. Эндпоинт интроспекции также предоставляется Stronghold для проверки токена.

Роли и ключи

OIDC-совместимые ID-токены генерируются на основе роли, которая позволяет конфигурировать требования к токену с помощью системы шаблонов, ttl токена и способ указать, какой «ключ» будет использоваться для подписи токена. Шаблон роли является необязательным параметром для настройки содержимого токена и описывается в следующем разделе. TTL токена контролирует время действия токена, по истечении которого библиотеки проверки будут считать токен недействительным. Все роли имеют связанный с ними client_id, который будет добавляется к параметру aud токена. Библиотеки JWT/OIDC обычно требуют это значение. Параметр может быть установлен оператором в выбранное значение, либо Если значение не задано, будет использоваться значение, сгенерированное Stronghold.

Параметр key роли связывает роль с существующим именованным ключом (несколько ролей могут ссылаться на один и тот же ключ). Невозможно сгенерировать неподписанный ID-токен.

Именованный ключ - это пара открытый/закрытый ключ, сгенерированная Stronghold. Закрытый ключ используется для подписи идентификационных токенов, а открытый ключ используется клиентами для для проверки подписи. Ключи регулярно ротируются, при этом генерируется новая пара ключей генерируется новая пара ключей, а предыдущий публичный ключ сохраняется в течение ограниченного времени для проверки.

В конфигурации именованного ключа указываются период ротации, время проверки, алгоритм подписи и разрешённые идентификаторы клиентов. Период ротации определяет частоту, с которой генерируется новый ключ подписи и удаляется закрытая часть предыдущего ключа подписи удаляется. Verification ttl - это время, в течение которого открытый ключ время, в течение которого открытый ключ сохраняется для проверки после ротации. По умолчанию ключи поворачиваются каждые 24 часа и остаются доступными для проверки в течение 24 часов после их ротации.

Список разрешённых идентификаторов клиентов ключа ограничивает, какие роли могут ссылаться на этот ключ. Параметр может быть установлен в *, чтобы разрешить все роли. Оценка валидности производится когда токен запрашивается, а не во время конфигурации.

Содержание и шаблоны токенов

Токены идентификации всегда будут содержать, как минимум, требования OIDC:

• iss - URL эмитента
• sub - идентификатор организации-заявителя
• aud - client_id для роли
• iat - Время выдачи
• exp - Время истечения срока действия токена

Кроме того, оператор может настроить шаблоны для каждой роли, которые позволяют добавлять различные другую информацию о сущности, которая может быть добавлена к токену. Шаблоны структурированы как JSON с заменяемыми параметрами. Синтаксис параметров такой же что и для ACL Path Templating.

Например:

{
  "color": {{identity.entity.metadata.color}},
  "userinfo": {
     "username": {{identity.entity.aliases.usermap_123.metadata.username}},
     "groups": {{identity.entity.groups.names}}
  },
  "nbf": {{time.now}}
}

Когда запрашивается токен, результирующий шаблон может быть заполнен следующим образом:

{
  "color": "green",
  "userinfo": {
     "username": "bob",
     "groups": ["web", "engr", "default"]
  },
  "nbf": 1561411915
}

которые будут объединены с базовыми утверждениями OIDC в окончательный токен:

{
  "iss": "https://10.1.1.45:8200/v1/identity/oidc",
  "sub": "a2cd63d3-5364-406f-980e-8d71bb0692f5",
  "aud": "SxSouteCYPBoaTFy94hFghmekos",
  "iat": 1561411915,
  "exp": 1561412215,
  "color": "green",
  "userinfo": {
    "username": "bob",
    "groups": ["web", "engr", "default"]
  },
  "nbf": 1561411915
}

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

Параметры шаблона, которые отсутствуют для сущности, например метаданные, которые или несуществующий аксессуар псевдонима, являются просто пустыми строки или объекты, в зависимости от типа данных.

Шаблоны настраиваются на роль и могут быть дополнительно закодированы в base64.

Полный список параметров шаблона приведён ниже:

Генерация токенов

Аутентифицированный клиент может запросить токен, используя генерацию токена эндпоинта. Токен будет сгенерирован в соответствии со спецификациями запрашиваемой роли для запрашивающей сущности. Невозможно сгенерировать токен для произвольной сущности.

Проверка подлинности идентификационных токенов, сгенерированных Stronghold

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

Stronghold будет обслуживать стандартные «.well-known» эндпоинты, которые позволяют легко интегрироваться с библиотеками проверки OIDC. Настройка библиотек обычно включает в себя предоставление URL эмитента и идентификатор клиента. Библиотека будет обрабатывать запросы ключей и проверять подписи и требования к утверждениям на токенах. Преимущество этого подхода заключается в том, что требуется только доступ к Stronghold, а не авторизация, поскольку .well-known эндпоинты не проходят аутентификацию.

В качестве альтернативы токен может быть отправлен в Stronghold для проверки через эндпоинт introspection endpoint. В ответе будет указано, является ли токен «активным» или нет, а также любые ошибки, возникшие при проверке. Помимо того, что клиент может просто делегировать проверку Stronghold, использование этого эндпоинта включает в себя дополнительную проверку того, является ли сущность все ещё активной или нет, то есть то, что что невозможно определить только по токену. В отличие от .well-known endpoint, доступ к introspection endpoint требуется действительный токен Stronghold и достаточная авторизации.

Соображения по поводу эмитента

Система идентификационных токенов имеет один настраиваемый параметр: эмитент. Эмитент параметр iss особенно важен для правильной проверки токена клиентами. Потребители токена будут запрашивать открытые ключи у Stronghold, используя URL эмитента, поэтому он должен быть доступен по сети. Более того, возвращаемый набор ключей будет включать эмитента, который должен соответствовать запросу.

По умолчанию Stronghold устанавливает эмитента в адрес экземпляра Stronghold api_addr. Это означает, что токены выпущенные в данном кластере, должны быть подтверждены в пределах этого кластера. В качестве альтернативы, параметр issuer может быть задан явно. Этот адрес должен указывать на путь к идентификатору/oidc для экземпляра Stronghold (например. https://stronghold.example.com:8200/v1/identity/oidc) и должен быть доступным для любого клиента, пытающегося подтвердить идентификационные токены.