Метод аутентификации. JWT/OIDC

Данный механизм может использовать внешние сертификаты X.509 в качестве части TLS или проверки подписи. Проверка подписей по сертификатам X.509, использующим SHA-1, устарела и по умолчанию отключена.

Метод jwt auth можно использовать для аутентификации в StarVault с помощью OIDC или путем предоставления JWT.

Метод OIDC позволяет выполнять аутентификацию через настроенный провайдер OIDC с помощью веб-браузера пользователя. Этот метод может быть инициирован из пользовательского интерфейса StarVault или командной строки. Кроме того, JWT может быть предоставлен напрямую. JWT криптографически проверяется с помощью локально предоставленных ключей, или, если настроено, для получения соответствующих ключей может использоваться служба OIDC Discovery. Выбор метода настраивается для каждой роли. Оба метода позволяют дополнительно обрабатывать данные утверждений в JWT. Сначала будут рассмотрены некоторые концепции, общие для обоих методов, а затем конкретные примеры использования OIDC и JWT.

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

1. Аутентификация OIDC

В данном разделе рассматривается настройка и использование ролей OIDC. Если необходимо напрямую предоставить JWT, обратитесь к разделу «Аутентификация JWT» ниже. Предполагается базовое знакомство с концепцией OIDC. Поток кода авторизации использует расширение Proof Key for Code Exchange (PKCE).

StarVault включает два встроенных потока авторизации OIDC: пользовательский интерфейс StarVault и CLI с использованием логина starvault.

1.1. Перенаправляющие URI

Важной частью конфигурации роли OIDC является правильная настройка URI перенаправления. Это должно быть сделано как в StarVault, так и в провайдере OIDC, и эти конфигурации должны совпадать. URI перенаправления задаются для роли с помощью параметра allowed_redirect_uris. Существуют разные URI перенаправления для настройки потоков StarVault UI и CLI, поэтому в зависимости от установки необходимо настроить один или оба.

1.2. CLI

Если вы планируете поддерживать аутентификацию через starvault login -method=oidc, необходимо задать URI перенаправления на localhost. Обычно это может быть: http://localhost:8250/oidc/callback. При необходимости при входе в систему через CLI можно указать другой хост и/или порт прослушивания, и URI с этим хостом/портом должен совпадать с одним из настроенных перенаправляемых URI. Эти же URI «localhost» должны быть добавлены и в провайдер.

1.3. Пользовательский интерфейс StarVault

Для входа в систему через StarVault UI требуется URI перенаправления вида: https://{host:port}/ui/vault/auth/{path}/oidc/callback.

Параметры host:port должны соответствовать серверу StarVault, а path - пути, по которому подключен бэкенд JWT (например, oidc или jwt).

Если для параметра oidc_response_mode установлено значение form_post, то для входа в систему через пользовательский интерфейс StarVault требуется URI перенаправления вида: https://{host:port}/v1/auth/{path}/oidc/callback.

Выполнить вход в систему возможно двумя способами:

Через пользовательский интрефейс StarVault

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

Через CLI

Для входа в систему CLI по умолчанию используется путь /oidc. Если этот метод авторизации был включен по другому пути, укажите в CLI -path=/my-path.

$ starvault login -method=oidc port=8400 role=test

Завершите вход в систему через провайдера OIDC. Будет выполнен автоматический запуск браузера. Пример URL: https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8400%2Foidc%2Fcallback&client_id=r3qXc2bix9eF…;

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

skip_browser (по умолчанию: «false») - переключает автоматический запуск браузера по умолчанию на URL-адрес входа в систему.

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

mount (по умолчанию: «oidc»)
listenaddress (по умолчанию: «localhost»)
порт (по умолчанию: 8250)
callbackhost (по умолчанию: «localhost»)
callbackmethod (по умолчанию: «http»)
callbackport (по умолчанию: значение, заданное для порта). Это значение используется в redirect_uri, в то время как port - это порт localhost, который использует слушатель. В расширенных настройках эти два параметра могут отличаться.

3. Конфигурация провайдера OIDC

Поток аутентификации OIDC был успешно протестирован с рядом провайдеров. Полное руководство по настройке приложений OAuth/OIDC выходит за рамки документации StarVault.

4. Устранение неполадок в конфигурации OIDC

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

Если параметр роли (например, bound_claims) требует значения карты, его нельзя установить отдельно с помощью StarVault CLI. В таких случаях лучше всего записать всю конфигурацию в виде одного JSON-объекта:
```
starvault write auth/oidc/role/demo -<<EOF
{
  "user_claim": "sub",
  "bound_audiences": "abc123",
  "role_type": "oidc",
  "policies": "demo",
  "ttl": "1h",
  "bound_claims": { "groups": ["mygroup/mysubgroup"] }
}
EOF
```
Следите за выходом журнала StarVault. Будет выводиться важная информация о сбоях проверки OIDC.
Убедитесь, что URI перенаправления корректны в StarVault и на провайдере. Они должны точно совпадать. Проверьте: http/https, 127.0.0.1/localhost, номера портов, наличие слэшей в конце.
Начните с простого. Единственная конфигурация утверждения, которая требуется роли, - это user_claim. После того как аутентификация будет работать, вы можете добавить дополнительные привязки утверждений и копирование метаданных.
bound_audiences является необязательным для ролей OIDC и обычно не требуется. Провайдеры OIDC будут использовать client_id в качестве аудитории, и валидация OIDC ожидает этого.
Уточните у своего провайдера, какие диапазоны необходимы для получения всей необходимой информации. Часто требуется запрашивать диапазоны профиль и группы, которые можно добавить, установив для роли параметр oidc_scopes=«profile,groups.
Если вы видите в журналах ошибки, связанные с претензиями, внимательно изучите документацию поставщика, чтобы понять, как он называет и структурирует свои претензии. В зависимости от провайдера, вы можете сконструировать простой запрос curl implicit grant для получения JWT, который вы можете проверить. Пример декодирования JWT (в данном случае расположенного в поле access_token JSON-ответа):
cat jwt.json | jq -r .access_token | cut -d. -f2 | base64 -D
Также доступна ролевая опция verbose_oidc_logging, которая будет записывать полученный токен OIDC в журналы сервера, если включено ведение журнала на уровне отладки. Это может быть полезно при отладке настройки провайдера и проверке того, что полученные претензии соответствуют вашим ожиданиям. Поскольку данные утверждений записываются дословно и могут содержать конфиденциальную информацию, эту опцию не следует использовать в производстве.

5. Аутентификация JWT

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

5.1. Проверка JWT

Подписи JWT будут проверяться по открытым ключам эмитента. Этот процесс может осуществляться тремя различными способами, хотя для одного бэкенда может быть настроен только один метод:

Статические ключи. Набор открытых ключей хранится непосредственно в конфигурации бэкенда.
JWKS. Настраивается URL-адрес JSON Web Key Set (JWKS) (и дополнительная цепочка сертификатов). Ключи будут извлекаться из этой конечной точки во время аутентификации.
IDC Discovery (и необязательная цепочка сертификатов). Ключи будут извлекаться из этого URL во время аутентификации. При использовании OIDC Discovery будут применяться критерии проверки OIDC (например, iss, aud и т. д.).

Если необходимо использовать несколько методов, можно установить и настроить другой экземпляр бэкенда по другому пути одним из способов:

Через CLI

По умолчанию используется путь /jwt. Если этот метод авторизации был включен по другому пути, укажите в CLI -path=/my-path.

$ starvault write auth/jwt/login role=demo jwt=...

Через API

По умолчанию используется конечная точка auth/jwt/login. Если этот метод авторизации был включен по другому пути, используйте это значение вместо jwt.

curl \
    --request POST \
    --data '{"jwt": "your_jwt", "role": "demo"}' \
    http://127.0.0.1:8200/v1/auth/jwt/login

Ответ будет содержать токен в auth.client_token:

{
  "auth": {
    "client_token": "38fe9691-e623-7238-f618-c94d4e7bc674",
    "accessor": "78e87a38-84ed-2692-538f-ca8b9f400ab3",
    "policies": ["default"],
    "metadata": {
      "role": "demo"
    },
    "lease_duration": 2764800,
    "renewable": true
  }
}

6. Конфигурация

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

Включите метод аутентификации JWT. Можно использовать имя jwt или oidc. Бэкэнд будет смонтирован по выбранному имени.
```
$ starvault auth enable jwt
```
или
```
$ starvault auth enable oidc
```
Используйте конечную точку /config для настройки StarVault. Для поддержки ролей JWT необходимо наличие либо локальных ключей, либо URL JWKS, либо URL OIDC Discovery. Для ролей OIDC требуется URL-адрес OIDC Discovery, идентификатор клиента OIDC и секрет клиента OIDC. Список доступных параметров конфигурации см. в документации по API.
```
$ starvault write auth/jwt/config \
    oidc_discovery_url="https://myco.auth0.com/" \
    oidc_client_id="m5i8bj3iofytj" \
    oidc_client_secret="f4ubv72nfiu23hnsj" \
    default_role="demo"
```
Если вам нужно выполнить проверку JWT с помощью валидации JWT-токена, оставьте oidc_client_id и oidc_client_secret пустыми.
```
$ starvault write auth/jwt/config \
   oidc_discovery_url="https://MYDOMAIN.eu.auth0.com/" \
   oidc_client_id="" \
   oidc_client_secret="" \
```
Создайте именованную роль:
```
starvault write auth/jwt/role/demo \
    allowed_redirect_uris="http://localhost:8250/oidc/callback" \
    bound_subject="r3qX9DljwFIWhsiqwFiu38209F10atW6@clients" \
    bound_audiences="https://starvault.plugin.auth.jwt.test" \
    user_claim="https://starvault/user" \
    groups_claim="https://starvault/groups" \
    policies=webapps \
    ttl=1h
```
Эта роль авторизует JWT с заданными утверждениями subject и audience, назначает политику webapps и использует заданные утверждения user/groups для настройки псевдонимов Identity.

Полный список параметров конфигурации приведен в документации по API.

6.1. Связанные требования

После того как JWT был подтвержден как правильно подписанный и не истекший, поток авторизации проверит соответствие всех настроенных «связанных» параметров. В некоторых случаях существуют специальные параметры, например bound_subject, которые должны совпадать с параметром sub в JWT. Роль также может быть настроена на проверку произвольных утверждений с помощью карты bound_claims. Карта содержит набор утверждений и их необходимые значения. Например, предположим, что для bound_claims установлено значение:

{
  "division": "Europe",
  "department": "Engineering"
}

Только JWT, содержащие утверждения division и department и соответствующие значения Europe и Engineering, будут авторизованы. Если ожидаемое значение представляет собой список, утверждение должно соответствовать одному из элементов в списке. Чтобы ограничить авторизацию набором адресов электронной почты:

{
  "email": ["fred@example.com", "julie@example.com"]
}

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

6.2. Утверждения как метаданные

Данные из утверждений можно скопировать в результирующие метаданные токена аутентификации и псевдонима, настроив claim_mappings. Этот параметр роли представляет собой карту элементов для копирования. Элементы карты имеют вид: «<JWT claim>«:»<metadata key>». Предположим, что параметр claim_mappings имеет значение:

{
    "division": "organization",
    "department": "department"
}

Это указывает, что значение утверждения JWT department должно быть скопировано в ключ метаданных department. Значение утверждения JWT department также будет скопировано в метаданные, но сохранит имя ключа. Если утверждение настроено в claim_mappings, оно должно существовать в JWT, иначе аутентификация не пройдет.

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

6.3. Спецификации требований и указатель JSON

Некоторые параметры (например, bound_claims, groups_claim, claim_mappings, user_claim) используются для указания на данные внутри JWT. Если нужный ключ находится на верхнем уровне JWT, его имя может быть указано напрямую. Если он вложен на более низком уровне, можно использовать JSON-указатель.

Предположим, что необходимо сослаться на следующие данные JSON:

{
  "division": "North America",
  "groups": {
    "primary": "Engineering",
    "secondary": "Software"
  }
}

Параметр division будет ссылаться на North America, поскольку это ключ верхнего уровня. Параметр /groups/primary использует синтаксис JSON Pointer для ссылки на Engineering на более низком уровне. В качестве селектора можно использовать любой правильный указатель JSON. Полное описание синтаксиса см. в JSON Pointer RFC.