Аутентификация по JWT

Способ аутентификации для ролей типа “jwt” проще, чем в OIDC, поскольку Deckhouse Stronghold требуется только проверить предоставленный JWT.

Проверка JWT

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

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

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

Аутентификация JWT через CLI

d8 stronghold write auth/<path-to-jwt-backend>/login role=demo jwt=...

Путь по умолчанию для бэкенда аутентификации JWT - /jwt, поэтому если вы используете бэкенд по умолчанию, то команда будет выглядеть так:

d8 stronghold write auth/jwt/login role=demo jwt=...

Если бэкенд JWT auth использует другой путь, используйте его.

Аутентификация 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
  }
}

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

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

Включите метод аутентификации JWT. Можно выбрать имя jwt или oidc. Бэкэнд будет монтироваться по выбранному имени.

d8 stronghold auth enable jwt
or
d8 stronghold auth enable oidc

Для настройки Deckhouse Stronghold используйте конечную точку /config. Для поддержки ролей JWT необходимо наличие локальных ключей, URL JWKS или URL OIDC Discovery. Для ролей OIDC необходимо наличие OIDC Discovery URL, OIDC Client ID и OIDC Client Secret.

d8 stronghold 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 пустыми.

d8 stronghold write auth/jwt/config \
   oidc_discovery_url="https://MYDOMAIN.eu.auth0.com/" \
   oidc_client_id="" \
   oidc_client_secret=""

Создайте именованную роль:

d8 stronghold write auth/jwt/role/demo \
  allowed_redirect_uris="http://localhost:8250/oidc/callback" \
  bound_subject="r3qX9DljwFIWhsiqwFiu38209F10atW6@clients" \
  bound_audiences="https://vault.plugin.auth.jwt.test" \
  user_claim="https://vault/user" \
  groups_claim="https://vault/groups" \
  policies=webapps \
  ttl=1h

Эта роль авторизует JWT с заданными утверждениями subject и audience, задает политику webapps и использует заданные утверждения user/groups для настройки псевдонимов Identity.

Связанные параметры

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

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

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

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

Связанные формулы могут быть опционально сконфигурированы с помощью globes. Globe - это определение шаблонов в тексте, которые могут быть заменены при выполнении операции. Например, если у пользователя есть glob *.conf, то при выполнении операции с этим glob все файлы с расширением .conf будут обработаны. Это полезно при автоматизации процессов, связанных с обработкой файлов.

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

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

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

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

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

Спецификации утверждений и 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 Pointer.