Механизм секретов Identity

Механизм секретов Identity — это решение для управления идентификацией в StarVault. Внутри него хранятся клиенты, которые распознаются StarVault. Каждый клиент называется сущностью. Сущность может иметь несколько псевдонимов. Например, один пользователь, имеющий учетные записи на GitHub и LDAP, может быть сопоставлен с одной сущностью в StarVault, которая имеет 2 псевдонима: один типа GitHub и один типа LDAP. Когда клиент проходит аутентификацию через любой из бэкендов (кроме бэкенда Token), StarVault создает новую сущность и прикрепляет к ней новый псевдоним, если соответствующая сущность еще не существует. Идентификатор сущности будет привязан к аутентифицированному токену. Когда такие токены используются, их идентификаторы сущностей регистрируются в журнале аудита, что позволяет отследить действия, совершенные конкретными пользователями.

Хранилище идентификаторов позволяет операторам управлять сущностями в StarVault. Можно создавать сущности и привязывать к ним псевдонимы с помощью ACL’d API. Для сущностей могут быть установлены политики, которые добавляют возможности токенам, привязанным к идентификаторам сущностей. Возможности, предоставляемые токенам через сущности, являются дополнением к существующим возможностям токена, а не заменой. Возможности токена, наследуемые от сущностей, вычисляются динамически во время запроса. Это обеспечивает гибкость в управлении доступом к уже выпущенным токенам.

Этот механизм секретов будет установлен по умолчанию. Его нельзя отключить или переместить. Для получения более подробной информации об идентификации обратитесь к документации Identity.

Механизм секретов StarVault Identity поддерживает несколько различных функций. Каждая функция описана на отдельной странице документации:

токены Identity
OIDC Identity провайдер

1. Удостоверяющие токены

1.1. Введение

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

1.2. Роли и ключи

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

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

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

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

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

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

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

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

Name

Description

identity.entity.id

Удостоверение организации

identity.entity.name

Имя объекта

identity.entity.groups.ids

Удостоверение групп, в которых состоит объект

identity.entity.groups.names

Имена групп, в которых состоит объект

identity.entity.metadata

Метаданные, связанные с объектом

identity.entity.metadata.<metadata key>

Метаданные, связанные с объектом для данного ключа

identity.entity.aliases.<mount accessor>.id

Удостоверение псевдонима объекта для данной точки монтирования

identity.entity.aliases.<mount accessor>.name

Имя псевдонима объекта для данной точки монтирования

identity.entity.aliases.<mount accessor>.metadata

Метаданные, связанные с псевдонимом для данной точки монтирования

identity.entity.aliases.<mount accessor>.metadata.<metadata key>

Метаданные, связанные с псевдонимом для данной точки монтирования и ключа метаданных

identity.entity.aliases.<mount accessor>.custom_metadata

Пользовательские метаданные, связанные с псевдонимом для данной точки монтирования

identity.entity.aliases.<mount accessor>.custom_metadata.<custom_metadata key>

Пользовательские метаданные, связанные с псевдонимом для данной точки монтирования и custom metadata key

time.now

Текущее время в виде секунд с начала эпохи

time.now.plus.<duration>

Текущее время плюс продолжительность в формате строки

time.now.minus.<duration>

Текущее время минус продолжительность в формате строки

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

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

1.5. Проверка подлинности удостоверяющих токенов, сгенерированных StarVault

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

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

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

1.6. Соображения по поводу издателя

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

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

2. Идентифицирующий провайдер OIDC

StarVault является провайдером идентификации OpenID Connect (OIDC). Это позволяет клиентским приложениям, использующим протокол OIDC, использовать источник идентификации StarVault и широкий спектр методов аутентификации при проверке подлинности конечных пользователей. Клиентские приложения могут настроить свою логику аутентификации на взаимодействие с StarVault. После этого StarVault будет выступать в качестве моста к другим поставщикам идентификационных данных с помощью существующих методов аутентификации. Клиентские приложения также могут получать идентификационную информацию для своих конечных пользователей, используя пользовательский шаблон идентификационной информации StarVault.

Более подробную информацию о ресурсах конфигурации и конечных точках OIDC можно найти на странице концепций провайдеров OIDC.

2.1. Настройка

Система провайдеров StarVault OIDC построена на основе механизма секретов идентификации. Этот механизм секретов установлен по умолчанию, его нельзя отключить или переместить.

Каждое пространство имен StarVault имеет провайдера и ключ OIDC по умолчанию. Эта встроенная конфигурация позволяет клиентским приложениям начать использовать StarVault в качестве источника идентификации с минимальными настройками. Подробные сведения о встроенной конфигурации и дополнительных опциях см. на странице Концепции провайдера OIDC.

В следующих шагах показана минимальная конфигурация, позволяющая клиентскому приложению использовать StarVault в качестве провайдера OIDC.

Включите метод авторизации StarVault:
```
$ starvault auth enable userpass
Success! Enabled userpass auth method at: userpass/
```
В потоке OIDC можно использовать любой метод авторизации StarVault. Для простоты включите метод аутентификации userpass.
Создайте пользователя
```
$ starvault write auth/userpass/users/end-user password="securepassword"
Success! Data written to: auth/userpass/users/end-user
```
Этот пользователь будет проходить аутентификацию в StarVault через клиентское приложение, иначе называемое доверенной стороной OIDC.
Создайте клиентское приложение:
```
$ starvault write identity/oidc/client/my-webapp \
  redirect_uris="https://localhost:9702/auth/oidc-callback" \
  assignments="allow_all"
Success! Data written to: identity/oidc/client/my-webapp
```
Эта операция создает клиентское приложение, которое можно использовать для настройки полагающейся стороны OIDC. Подробные сведения о различных типах клиентов, включая confidential и public, см. в разделе "Клиентские приложения".

Параметр assignments ограничивает сущности и группы StarVault, которым разрешена аутентификация через клиентское приложение. По умолчанию ни одной сущности StarVault не разрешено. Чтобы разрешить аутентификацию всем сущностям StarVault, используется встроенное назначение allow_all.

Прочтите учетные данные клиента

$ starvault read identity/oidc/client/my-webapp

**Вывод:**
Key	Value
---	----
access_token_ttl	24h
assignments	[allow_all]
client_id	GSDTnn3KaOrLpNlVGlYLS9TVsZgOTweO
client_secret	hvo_secret_gBKHcTP58C4aq7FqPWsuqKgpiiegd7ahpifGae9WGkHRCwFEJTZA9KGdNVpzE0r8
client_type	confidential
id_token_ttl	24h
key	default
redirect_uris	[https://localhost:9702/auth/oidc-callback]

Client_id и client_secret - это учетные данные клиентского приложения. Эти значения обычно требуются при настройке доверяющей стороны OIDC.

Прочтите конфигурацию обнаружения OIDC:

$ curl -s http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/openid-configuration
{
  "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/default",
  "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/.well-known/keys",
  "authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/default/authorize",
  "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/token",
  "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/default/userinfo",
  "request_parameter_supported": false,
  "request_uri_parameter_supported": false,
  "id_token_signing_alg_values_supported": [
    "RS256",
    "RS384",
    "RS512",
    "ES256",
    "ES384",
    "ES512",
    "EdDSA"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "openid"
  ],
  "subject_types_supported": [
    "public"
  ],
  "grant_types_supported": [
    "authorization_code"
  ],
  "token_endpoint_auth_methods_supported": [
    "none",
    "client_secret_basic",
    "client_secret_post"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Каждый провайдер StarVault OIDC публикует метаданные обнаружения. Значение issuer обычно требуется при настройке полагающейся стороны OIDC.

2.2. Использование

После настройки метода аутентификации StarVault и клиентского приложения следующие сведения можно использовать для настройки доверяющей стороны OIDC на делегирование аутентификации конечного пользователя в StarVault.

cliend_id - идентификатор клиентского приложения
client_secret- секрет клиентского приложения
issuer- эмитент (issuer) провайдера OIDC в StarVault

Обратитесь к документации конкретного OIDC-получателя (relying party) для получения сведений об использовании.

2.3. Поддерживаемые потоки

Функциональность OIDC-провайдера в StarVault в настоящее время поддерживает следующий поток аутентификации:

поток авторизационного кода (Authorization Code Flow)

3. API

Движок секретов Identity имеет полноценный HTTP API. Более подробную информацию можно найти в разделе API механизма секретов Identity.

Кроме того, StarVault может быть настроен как провайдер идентификации OIDC. Более подробную информацию можно найти в API провайдера идентификации OIDC.