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

Метод OIDC позволяет выполнять аутентификацию через настроенный OIDC-провайдер с помощью веб-браузера пользователя. Аутентификацию можно начать из веб-интерфейса Stronghold или из командной строки. Также можно передать JWT напрямую. JWT криптографически проверяется с помощью локально заданных ключей или, если он настроен, через сервис OIDC Discovery, у которого запрашиваются нужные ключи. Способ аутентификации задаётся для каждой роли.

Оба способа позволяют дополнительно обрабатывать данные утверждений (claims) в JWT. На этой странице описаны понятия, общие для обоих способов, и сценарии входа через OIDC.

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

В этом разделе описаны настройка и использование ролей OIDC. Предполагается базовое знакомство с концепциями OIDC. Сценарий Authorization Code использует расширение Proof Key for Code Exchange (PKCE).

В Stronghold есть два встроенных сценария входа через OIDC: веб-интерфейс Stronghold и CLI (d8 stronghold login).

URI перенаправления

Если не используется callbackmode=device, важная часть настройки ролей OIDC — правильно заданные URI перенаправления. Их нужно задать и в Stronghold, и в OIDC-провайдере, и эти настройки должны совпадать. URI перенаправления задаются для роли в параметре allowed_redirect_uris. Для сценариев входа через веб-интерфейс Stronghold и через CLI используются разные URI перенаправления, поэтому в зависимости от установки настройте один или оба.

CLI

Если планируется аутентификация через d8 stronghold login -method=oidc и не используется callbackmode=device, задайте URI перенаправления с путём, который заканчивается на oidc/callback. При режиме по умолчанию callbackmode=client это обычно http://localhost:8250/oidc/callback. При callbackmode=direct используйте URI следующего вида:

https://<HOST>:<PORT>/v1/auth/<MOUNT_PATH>/oidc/callback

Где:

  • <HOST>:<PORT> — имя и порт сервера Stronghold;
  • <MOUNT_PATH> — путь, по которому смонтирован метод аутентификации, например oidc или jwt.

При входе через CLI можно указать другой хост и/или порт прослушивания. URI с этим хостом и портом должен совпадать с одним из настроенных URI перенаправления. Эти же URI нужно добавить в провайдер.

Stronghold UI

В Stronghold в DP URI перенаправления для веб-интерфейса Stronghold и для CLI настраиваются автоматически, если модуль stronghold работает в режиме управления Automatic.

Вход через OIDC (Stronghold UI)

Чтобы войти через веб-интерфейс Stronghold, выполните следующие шаги:

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

Вход через OIDC (CLI)

По умолчанию CLI использует путь монтирования oidc. В Stronghold в DP метод смонтирован по пути oidc_deckhouse. Если метод аутентификации смонтирован по другому пути, укажите его в параметре -path.

  • Stronghold в DP
  • Stronghold в Linux
$ d8 stronghold login -method=oidc -path=oidc_deckhouse role=test

Complete the login via your OIDC provider. Launching browser to:

    https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&client_id=r3qXc2bix9eF...

$ stronghold login -method=oidc role=test

Complete the login via your OIDC provider. Launching browser to:

    https://myco.auth0.com/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8250%2Foidc%2Fcallback&client_id=r3qXc2bix9eF...

Браузер открывает сгенерированный URL, чтобы завершить вход у провайдера. Если браузер не открывается автоматически, введите URL вручную. Параметр skip_browser (по умолчанию false) отключает автоматический запуск браузера.

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

  • mount (по умолчанию oidc) — путь монтирования метода аутентификации.
  • callbackmode (по умолчанию client) — режим обратного вызова:
    • client — подключение к порту на стороне CLI-клиента;
    • direct — прямое подключение к серверу Stronghold;
    • device — сценарий device flow без обратного вызова.
  • listenaddress (по умолчанию localhost) — только для режима client.
  • port (по умолчанию 8250) — только для режима client.
  • callbackhost (по умолчанию в режиме direct — хост сервера Stronghold, в остальных случаях — localhost).
  • callbackmethod (по умолчанию в режиме direct — схема сервера Stronghold, в остальных случаях — http) — схема, которая используется в OIDC redirect_uri.
  • callbackport (по умолчанию в режиме client — значение port, в остальных случаях — порт сервера Stronghold и суффикс /v1/auth/<MOUNT_PATH>, где <MOUNT_PATH> — значение параметра входа -path). Это значение используется в redirect_uri, а port — это порт на localhost, который прослушивает слушатель. В сложных конфигурациях эти значения могут различаться.

Настройка OIDC-провайдера

Зарегистрируйте Stronghold как клиентское приложение в OIDC-провайдере и добавьте URI перенаправления из раздела «URI перенаправления». Руководства для отдельных провайдеров: GitLab, Keycloak, Kubernetes.

Устранение неполадок в настройке OIDC

Для устранения неполадок в настройке OIDC используйте следующие советы:

  • Если параметр роли (например, bound_claims) требует значения-словаря (map), его нельзя задать отдельно через CLI Stronghold. В таких случаях запишите всю конфигурацию в виде одного JSON-объекта:

    • Stronghold в DP
    • Stronghold в Linux
    d8 stronghold 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
    stronghold 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

  • Следите за журналом Stronghold. В нём есть информация о сбоях проверки OIDC.

  • Убедитесь, что URI перенаправления в Stronghold и в провайдере точно совпадают. Проверьте: http/https, 127.0.0.1/localhost, номера портов, наличие слешей в конце.

  • Начните с минимальной конфигурации. Единственная настройка утверждений, обязательная для роли, — user_claim. Когда аутентификация заработает, добавьте привязки утверждений и копирование метаданных.

  • bound_audiences — необязательный параметр для ролей OIDC, обычно он не требуется. OIDC-провайдеры используют client_id в качестве аудитории, и проверка OIDC это учитывает.

  • Уточните, какие области (scopes) нужно запросить у провайдера, чтобы получить всю нужную информацию. Часто нужны области profile и groups. Добавьте их, задав для роли 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-токен в журналы сервера, если включено журналирование на уровне debug. Он помогает отлаживать настройку провайдера и проверять полученные утверждения. Данные утверждений записываются в журнал без изменений и могут содержать конфиденциальную информацию, поэтому не включайте этот параметр в production-окружении.

Дополнительные ресурсы

←
Методы аутентификации / Обзор
OIDC / Обзор
→