Для улучшения работы сайта мы используем файлы cookies. Оставаясь на сайте, вы соглашаетесь с политикой обработки персональных данных.

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

В данной документации представлено API для плагина метода аутентификации JWT/OIDC StarVault. Чтобы узнать больше об использовании и работе, смотрите документацию метода StarVault JWT/OIDC.

Данный механизм может использовать внешние сертификаты X.509 в качестве части TLS или проверки подписи.

Проверка подписей на сертификаты X.509 с использованием SHA-1 устарела и больше не может использоваться без обходного решения.

В данном руководстве предполагается, что плагин подключен по пути /auth/jwt в StarVault. Поскольку возможно включать методы аутентификации в любом месте, пожалуйста, обновите ваши вызовы API соответственно.

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

Настраивает информацию о валидации, которая будет использоваться глобально для всех ролей. Должен быть установлен один (и только один) из параметров oidc_discovery_url, jwks_url и jwt_validation_pubkeys.

Метод Путь

POST

/auth/jwt/config

1.1. Параметры

  • oidc_discovery_url (string: <optional>) - URL OIDC Discovery без какого-либо компонента .well-known (базовый путь). Не может использоваться с jwks_url или jwt_validation_pubkeys.

  • oidc_discovery_ca_pem (string: <optional>) - содержимое CA сертификата или цепочки сертификатов в формате PEM, используемое для проверки соединений с URL OIDC Discovery. Если не установлено, используются системные сертификаты.

  • oidc_client_id (string: <optional>) - OAuth Client ID от провайдера для ролей OIDC.

  • oidc_client_secret (string: <optional>) - OAuth Client Secret от провайдера для ролей OIDC.

  • oidc_response_mode (string: <optional>) - режим ответа, который будет использоваться в OAuth2 запросе. Разрешенные значения: query и form_post. По умолчанию query.

  • oidc_response_types (строка, разделенная запятыми, или массив строк: <optional>) - типы ответа для запроса. Разрешенные значения: code и id_token. По умолчанию code.

"id_token" может использоваться только если oidc_response_mode установлен в form_post.

  • jwks_url (string: <optional>) - URL JWKS для аутентификации подписей. Не может использоваться с oidc_discovery_url или jwt_validation_pubkeys.

  • jwks_ca_pem (string: <optional>) - содержимое CA сертификата или цепочки сертификатов в формате PEM, используемое для проверки соединений с URL JWKS. Если не установлено, используются системные сертификаты.

  • jwt_validation_pubkeys (строка, разделенная запятыми, или массив строк: <optional>) - список публичных ключей в формате PEM для аутентификации подписей локально. Не может использоваться с jwks_url или oidc_discovery_url.

  • bound_issuer (string: <optional>) - значение, с которым будет сопоставлено утверждение iss в JWT.

  • jwt_supported_algs (строка, разделенная запятыми, или массив строк: <optional>) - список поддерживаемых алгоритмов подписи. По умолчанию [RS256] для ролей OIDC. По умолчанию все доступные алгоритмы для ролей JWT.

  • default_role (string: <optional>) - роль по умолчанию, которая будет использоваться, если не указана при входе.

  • provider_config (map: <optional>) - опции конфигурации для специфичной обработки провайдеров. Провайдеры со специфичной обработкой включают: Azure, Google, SecureAuth, IBM ISAM. Опции описаны в разделе каждого провайдера в Настройке OIDC провайдера.

  • override_allowed_server_names (строка, разделенная запятыми, или массив строк: <optional>) - список имен хостов, принимаемых при выполнении проверки TLS, которую применяют как к OIDC, так и к JWKS. Это переопределяет стандартные проверки, которые ожидают, что субъект TLS соответствует имени хоста, указанному в URL соединения.

  • namespace_in_state (bool: true) - передает пространство имен в параметре состояния OIDC вместо использования отдельного параметра запроса. С учетом этой настройки разрешенные URL перенаправления в StarVault и на стороне провайдера не должны содержать параметр запроса namespace. Это означает, что на стороне провайдера необходимо поддерживать только одну запись URL перенаправления для всех пространств имен хранилища, которые будут аутентифицироваться через него. По умолчанию true для новых конфигураций.

  • skip_jwks_validation (bool: false) - когда true и указаны oidc_discovery_url или jwks_url, если соединение не удается загрузить, будет выдано предупреждение и статус можно будет проверить позже, прочитав конечную точку конфигурации. Когда false, сохранение конфигурации не удастся, если проверка поставщика не сможет завершиться успешно.

Пример тела запроса:
{
  "oidc_discovery_url": "https://myco.auth0.com/",
  "bound_issuer": "https://myco.auth0.com/"
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/config

2. Чтение конфигурации

Возвращает ранее настроенную конфигурацию.

Метод Путь

GET

/auth/jwt/config
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/auth/jwt/config
Пример ответа:
{
  "data": {
    "oidc_discovery_url": "https://myco.auth0.com/",
    "oidc_discovery_ca_pem": [],
    "bound_issuer": "https://myco.auth0.com/",
    "jwt_validation_pubkeys": []
  },
  ...
}

3. Создание/Обновление роли

Регистрация роли в методе. Типы ролей имеют специфические сущности, которые могут выполнять операции входа через эту конечную точку. Ограничения, специфичные для типа роли, должны быть установлены на роли. Эти ограничения применяются к аутентифицированным сущностям, пытающимся войти в систему. Должно быть установлено хотя бы одно из связанных значений.

Метод Путь

POST

/auth/jwt/role/:name

3.1. Параметры

  • name (string: <required>) - имя роли.

  • role_type (string: <optional>) - тип роли, либо "oidc" (по умолчанию), либо "jwt".

  • bound_audiences (array: <optional>) - список утверждений aud для соответствия. Любое соответствие достаточно. Для ролей "jwt" требуется как минимум одно из bound_audiences, bound_subject, bound_claims или token_bound_cidrs. Опционально для ролей "oidc".

  • user_claim (string: <required>) - утверждение, которое будет использоваться для уникальной идентификации пользователя; это будет использоваться как имя для созданного алиаса сущности идентичности в результате успешного входа. Значение утверждения должно быть строкой.

  • user_claim_json_pointer (bool: false) - указывает, использует ли значение user_claim синтаксис JSON pointer для обращения к утверждениям. По умолчанию значение user_claim не будет использовать JSON pointer.

  • clock_skew_leeway (int или string: <optional>) - сколько свободы времени следует добавить ко всем утверждениям, чтобы учесть расхождение часов в секундах. По умолчанию 60 секунд, если установлено 0, и может быть отключено, если установлено -1. Принимает целое число секунд или строку формата продолжительности Go. Применимо только с "jwt" ролями.

  • expiration_leeway (int или string: <optional>) - сколько свободы времени следует добавить к утверждениям срока действия (exp), чтобы учесть расхождение часов в секундах. По умолчанию 150 секунд, если установлено 0, и может быть отключено, если установлено -1. Принимает целое число секунд или строку формата продолжительности Go. Применимо только с "jwt" ролями.

  • not_before_leeway (int или string: <optional>) - сколько свободы времени следует добавить к утверждениям not before (nbf), чтобы учесть расхождение часов в секундах. По умолчанию 150 секунд, если установлено 0, и может быть отключено, если установлено -1. Принимает целое число секунд или строку формата продолжительности Go. Применимо только с "jwt" ролями.

  • bound_subject (string: <optional>) - если установлено, требует, чтобы утверждение sub соответствовало этому значению.

  • bound_claims (map: <optional>) - если установлено, отображение утверждений (ключей) для совпадения с соответствующими значениями утверждений (значениями). Ожидаемое значение может быть одной строкой или списком строк. Интерпретация значений связанных утверждений настраивается с помощью bound_claims_type. Ключи поддерживают синтаксис JSON pointer для обращения к утверждениям.

  • bound_claims_type (string: "string") - настраивает интерпретацию значений bound_claims. Если string (по умолчанию), значения будут рассматриваться как строковые литералы и должны совпадать точно. Если установлено на glob, значения будут интерпретированы как шаблоны, где * соответствует любому количеству символов.

  • groups_claim (string: <optional>) - утверждение, которое будет использоваться для уникальной идентификации набора групп, к которым принадлежит пользователь; это будет использоваться как имена для созданных из-за успешного входа алиасов группы идентичности. Значение утверждения должно быть списком строк. Поддерживает синтаксис JSON pointer для обращения к утверждениям.

  • claim_mappings (map: <optional>) - если установлено, отображение утверждений (ключей), которые будут скопированы в указанные метаданные (значения). Ключи поддерживают синтаксис JSON pointer для обращения к утверждениям.

  • oauth2_metadata (list: <optional>) - если установлено, список типов токенов, которые поступают от OIDC провайдера, которые нужно вернуть в метаданных. Типы могут быть любыми из access_token, id_token или refresh_token, и при наличии значения возвращаются в соответствующих полях метаданных с префиксами oauth2_. Обратите внимание, что эти токены могут потенциально включать конфиденциальную безопасность, поэтому проявляйте осторожность перед их включением и убедитесь, что клиент обрабатывает информацию безопасно.

  • oidc_scopes (list: <optional>) - если установлено, список OIDC скоупов, которые будут использоваться с OIDC ролью. Стандартный скоуп "openid" автоматически включается и не требует указания.

  • allowed_redirect_uris (list: <required, кроме режима обратного вызова устройства>) - список разрешенных значений для redirect_uri во время OIDC входов.

  • callback_mode (string: <optional>) - режим обратного вызова от OIDC провайдера, либо client (по умолчанию), чтобы выполнить обратный вызов к клиенту, direct для выполнения обратного вызова к серверу StarVault или "device" для устройства, у которого нет обратного вызова.

  • poll_interval (int: <optional>) - интервал опроса в секундах для режимов устройства и прямого обратного вызова, значение по умолчанию от сервера авторизации для потока устройства или '5'.

  • verbose_oidc_logging (bool: false) - логировать полученные OIDC токены и утверждения при активном режиме отладки. Не рекомендуется в производстве, поскольку в ответах OIDC могут присутствовать конфиденциальные данные.

  • max_age (int или string: <optional>) - указывает допустимое прошедшее время в секундах с момента последней активной аутентификации пользователя с OIDC провайдером. Если установлено, параметр запроса max_age будет включен в запрос аутентификации. См. AuthRequest для получения дополнительных деталей. Принимает целое число секунд или строку формата продолжительности Go.

  • token_policies_template_claims (bool: false) - когда включено, позволяет элементам в token_policies содержать шаблоны, которые вычисляются со всеми утверждениями на подлежащем JWT или OIDC ID токене. Это использует sdk/helper/template, основанный на text/template для шаблонирования. Шаблоны, которые приводят к пустой строке, удаляются, и все ссылки на утверждения должны существовать на аутентифицирующем токене. См. примеры ниже.

3.2. Примеры шаблонов ACL политики

Если данный JWT содержит пользовательские утверждения для project_id, environment и branch (например, из CI интеграции) и существует политика ACL для project_1234/env_prod/branch_main, это можно закодировать следующим образом:

Пример:
token_policies=["project_{{.project_id}}/env_{{.environment}}/branch_{{.branch}}"]

Чтобы сделать это условным в зависимости от того, является ли окружение prod, это можно закодировать следующим образом:

Пример:
token_policies=["{{if eq \"prod\" .environment}}project_{{.project_id}}/env_{{.environment}}/branch_{{.branch}}{{end}}"]

И эта политика ACL будет пустой (и, следовательно, удаленной), если значение утверждения environment на токене, используемом во время аутентификации, было testing или staging.

Чтобы сослаться на утверждения, которые не всегда присутствуют в токене, вы можете обернуть выражение в проверку if, используя функцию index:

Пример:
{{ if ne nil (index . "optional_claim") }}
... какое-то выражение с .optional_claim ...
{{ end }}
Пример тела запроса:
{
  "policies": ["dev", "prod"],
  "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
  "bound_audiences": "https://myco.test",
  "user_claim": "https://StarVault/user",
  "groups_claim": "https://StarVault/groups",
  "bound_claims": {
    "department": "engineering",
    "sector": "7g"
  },
  "claim_mappings": {
    "preferred_language": "language",
    "group": "group"
  }
}
Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role

4. Чтение роли

Возвращает ранее зарегистрированную конфигурацию роли.

Метод Путь

GET

/auth/jwt/role/:name

4.1. Параметры

  • name (string: <required>) - имя роли.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role
Пример ответа:
{
  "data": {
    "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients",
    "bound_audiences": [
      "https://myco.test"
    ],
    "bound_cidrs": [],
    "user_claim": "https://StarVault/user",
    "groups_claim": "https://StarVault/groups",
    "policies": [
      "dev",
      "prod"
    ],
    "period": 0,
    "ttl": 0,
    "num_uses": 0,
    "max_ttl": 0
  },
  ...
}

5. Список ролей

Перечислить все роли, зарегистрированные с помощью плагина.

Метод Путь

LIST

/auth/jwt/role

5.1. Параметры

  • after (string: "") - необязательная запись, с которой следует начинать перечисление для постраничной навигации; не требуется существовать.

  • limit (int: 0) - необязательное количество записей для возврата; по умолчанию возвращаются все записи.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://127.0.0.1:8200/v1/auth/jwt/role
Пример ответа:
{
  "data": {
    "keys": [
      "dev-role",
      "prod-role"
    ]
  },
  ...
}

6. Удаление роли

Удаляет ранее зарегистрированную роль.

Метод Путь

DELETE

/auth/jwt/role/:name

6.1. Параметры

  • name (string: <required>) - Имя роли.

Пример запроса:
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/auth/jwt/role/dev-role

7. Запрос URL авторизации OIDC

Получите URL авторизации от StarVault для начала потока входа OIDC.

Ответ будет включать auth_url, куда пользователю необходимо перейти в веб-браузере для завершения потока входа.

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

Метод Путь

POST

/auth/jwt/oidc/auth_url

7.1. Параметры

  • role (string: <optional>) - имя роли, против которой осуществляется попытка входа. По умолчанию используется настроенная default_role, если не указана.

  • redirect_uri (string: <required, кроме режима обратного вызова устройства>) - путь к обратному вызову для завершения входа. Это будет в форме "https://…​/oidc/callback", где начальная часть зависит от вашего местоположения сервера StarVault, порта и монтирования плагина JWT. Это должно быть настроено в StarVault и провайдере. См. Redirect URIs для получения дополнительной информации.

  • client_nonce (string: <optional>) - необязательный nonce, предоставленный клиентом, который должен совпадать с значением client_nonce, предоставленным во время последующего запроса к callback API .

7.2. Примеры полезной нагрузки

Для режимов клиента или прямого обратного вызова:

{
  "role": "dev-role",
  "redirect_uri": "https://StarVault.myco.com:8200/ui/StarVault/auth/jwt/oidc/callback",
  "client_nonce": "ni42i2idj2jj"
}

Для режима обратного вызова устройства:

{
  "role": "dev-role",
  "client_nonce": "ni42i2idj2jj"
}
Пример запроса:
$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/auth_url

Для режимов клиента или прямого обратного вызова:

Примеры ответов:
{
  "request_id": "c701169c-64f8-26cc-0315-078e8c3ce897",
  "data": {
    "auth_url": "https://myco.auth0.com/authorize?client_id=r3qXcK2bezU3Sbmh0K16fatW6&nonce=851b69a9bfa5a6a5668111314414e3687891a599&redirect_uri=https%3A%2F%2FStarVault.myco.com3A8200%2Fui%2FStarVault%2Fauth%2Fjwt%2Foidc%2Fcallback&response_type=code&scope=openid+email+profile&state=1011e726d24960e09cfca2e04b36b38593cb6a22"
  },
  ...
}

Для режима обратного вызова устройства:

{
  "request_id": "c701169c-64f8-26cc-0315-078e8c3ce897",
  "data": {
    "auth_url": "https://myco.auth0.com/device",
    "user_code": "ABCDEFGHIJK"
  },
  ...
}

8. Обратный вызов OIDC

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

Это обычно инициируется сервером авторизации в клиентских или прямых режимах обратного вызова и не используется в режиме обратного вызова устройства.

Метод Путь

GET

/auth/jwt/oidc/callback

q === Параметры

  • state (string: <required>) - непрозрачный идентификатор состояния, который является частью URL авторизации и будет включен в перенаправление после успешной аутентификации на провайдере.

  • code (string: <optional>) - код авторизации, сгенерированный провайдером, который StarVault обменяет на ID токен. Обязателен, если не указан id_token.

  • id_token (string: <optional>) - если указан вместо кода авторизации, будет использоваться напрямую вместо обмена кода, чтобы получить его. Обязателен, если не указан code.

  • client_nonce (string: <optional>) - необязательный nonce, предоставленный клиентом, который должен совпадать с значением client_nonce, предоставленным во время предыдущего запроса к API auth_url.

  • error_description (string: <optional>) - подробное описание ошибки, если произошла ошибка. Если присутствует, будет включено в сообщение об ошибке, возвращаемое запрашивающему.

Пример запроса:
$ curl \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/callback?state=n2kfh3nsl&code=mn2ldl2nv98h2jl&client_nonce=ni42i2idj2jj
Пример ответа:
{
    "auth": {
        "client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies": [
            "default",
            "dev",
            "prod"
        ],
        "lease_duration": 2764800,
        "renewable": true
    },
    ...
}

9. Опрос OIDC

Опрос ответа при использовании прямого или устройства режима обратного вызова для завершения входа. Ответ от API auth_url возвращает элемент данных poll_interval, содержащий количество секунд, которое клиент должен подождать между вызовами API опроса.

Если обратный вызов прямого режима или устройство авторизации еще не произошло, код HTTP ответа будет 400 и будет включать список JSON errors, включая либо authorization_pending, либо slow_down. Если ответ slow_down, клиент должен добавить дополнительное время перед повторным вызовом API опроса.

Когда обратный вызов или авторизация произошли, ответ будет включать либо другое сообщение об ошибках, либо успешно вернуть токен авторизации.

Метод Путь

GET

/auth/jwt/oidc/poll

9.1. Параметры

  • state (string: <required>) - непрозрачный идентификатор состояния, который был частью URL авторизации и должен соответствовать состоянию, возвращенному провайдером OIDC.

  • client_nonce (string: <optional>) - необязательный nonce, предоставленный клиентом, который должен совпадать с значением client_nonce, предоставленным во время предыдущего запроса к API [auth_url].

Пример тела запроса:
{
  "state": "n2kfh3nsl",
  "client_nonce": "ni42i2idj2jj"
}
Пример запроса:
$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/oidc/poll

Когда ответ еще не произошел:

Примеры ответов:
{
  "errors": [
    "authorization_pending"
  ]
}

При успешном завершении:

{
    "auth": {
        "client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies": [
            "default",
            "dev",
            "prod"
        ],
        "lease_duration": 2764800,
        "renewable": true
    },
    ...
}

10. JWT вход

Получите токен. Эта конечная точка принимает подписанный JSON Web Token (JWT) и имя роли для некоторой сущности. Он проверяет подпись JWT для аутентификации этой сущности и затем авторизует сущность для данной роли.

Метод Путь

POST

/auth/jwt/login

10.1. Параметры

  • role (string: <optional>) - имя роли, против которой осуществляется попытка входа. По умолчанию используется настроенная default_role, если не указана.

  • jwt (string: <required>) - подписанный JSON Web Token (JWT).

Пример тела запроса:
{
  "role": "dev-role",
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
Пример запроса:
$ curl \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/auth/jwt/login
Пример ответа:
{
    "auth": {
        "client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
        "accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
        "policies": [
            "default",
            "dev",
            "prod"
        ],
        "lease_duration": 2764800,
        "renewable": true
    },
    ...
}