Skip to main content
Yahont может принимать JWT, выпущенный вашим поставщиком удостоверений или API-шлюзом, и использовать его для аутентификации запроса. Это полезно, когда другая система уже хранит идентификацию пользователя и обращается к Yahont от его имени — например, API-шлюз, портал или сервис, стоящий перед Yahont для собственных пользователей. Задайте в JWT_PUBLIC_KEY_URL URL, по которому доступен материал открытого ключа вашего издателя токенов. Когда переменная задана, Yahont принимает подписанный JWT в заголовке Authorization:
Эта возможность входит в Yahont Community Edition. Для неё не нужна лицензия Enterprise, и она работает одинаково в обеих редакциях. См. раздел Поддержка и стабильность ниже.

​
Настройка

1

Опубликуйте открытый ключ

Ваш поставщик удостоверений должен предоставлять ключ проверки по URL, доступному API-серверу Yahont. Yahont принимает два формата:
  • JWKS — документ JSON с массивом keys. Его публикуют Microsoft Entra ID, Okta, Auth0 и большинство других поставщиков по своему jwks_uri.
  • PEM — один открытый ключ RSA в кодировке PEM.
Yahont определяет формат по ответу. Ответ с Content-Type: application/json или с телом, начинающимся с {, читается как JWKS. Любое другое тело читается как PEM.
Большинство поставщиков удостоверений указывают URL JWKS в своём документе обнаружения OIDC по адресу https://<YOUR_IDP>/.well-known/openid-configuration в поле jwks_uri.
2

Настройте Yahont

Задайте переменную в файле .env.
.env
Перезапустите API-сервер, чтобы применить изменение.
3

Отправьте запрос

Поместите токен в заголовок Authorization любого вызова API Yahont. GET /api/me возвращает пользователя, которого определил Yahont, поэтому это хорошая первая проверка.

​
Требования к токену

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

​
Проверка аудитории и издателя

Yahont может проверять утверждения aud и iss. Когда ожидаемое значение задано, токен с несовпадающим утверждением отклоняется, и токен без утверждения тоже отклоняется (проверка «закрывается при сбое»). Принимаются и строковая, и массивная формы aud, а массив, содержащий ожидаемую аудиторию, совпадает. Задайте значения в Панель администратора → Безопасность и защита → Внешняя аутентификация JWT или с помощью переменных окружения: Настройка, для которой задана переменная окружения, закреплена: значение из окружения важнее всего сохранённого в панели администратора, а поле отображается как текст только для чтения. Так конфигурация, определяющая доступ, остаётся проверяемой конфигурацией как кодом, которую нельзя изменить изнутри приложения, даже из аккаунта администратора. Если переменная не задана, действует значение, сохранённое в панели администратора. При запуске Yahont копирует заданные значения окружения в базу данных, поэтому удаление переменной позже оставляет в силе её последнее закреплённое значение. URL открытого ключа, сохранённый через панель администратора, должен использовать https и проверяется по уровню защиты от SSRF развёртывания при сохранении и при каждой загрузке, а перенаправления подчиняются тем же правилам. URL, закреплённый переменной окружения, считается доверенной конфигурацией оператора и пропускает эти проверки, поэтому внутренние конечные точки остаются доступными, когда их настраивает оператор. Изменения, сделанные в панели администратора, записываются в журнал аудита с указанием действовавшего пользователя и старых и новых значений.

​
Выбор и ротация ключей

Когда URL отдаёт JWKS, Yahont выбирает ключ по kid в заголовке токена, затем по x5t. Если ничего не совпало, а в документе ровно один ключ, Yahont использует его. Yahont кэширует загруженный материал ключей. Если проверка не удалась, Yahont очищает кэш, снова загружает URL и повторяет один раз. Поэтому обычная ротация ключей не требует перезапуска.

​
Работа с пользователями

Запрос, аутентифицированный по JWT, обрабатывается как запрос любого другого вошедшего пользователя.
  • Создание пользователя при первом входе (just-in-time). Если в Yahont нет пользователя с этим адресом электронной почты, Yahont создаёт его. Аккаунт помечается подтверждённым и получает случайный пароль, который никогда не используется.
  • Существующие пользователи. Если адрес электронной почты принадлежит существующему пользователю, возвращается этот пользователь. Деактивированные пользователи отклоняются. Аккаунты, не предназначенные для веб-входа, отклоняются.
  • Политики доступа по-прежнему действуют. Адрес электронной почты должен удовлетворять тем же правилам списка приглашений и VALID_EMAIL_DOMAINS, что и любой другой способ входа.
  • Срок сессии. При TRACK_EXTERNAL_IDP_EXPIRY=true Yahont сохраняет exp токена как срок действия сессии пользователя во внешнем IdP.
Пользователь, созданный таким образом, не получает повышенных прав, за одним исключением: первый пользователь на пустом инстансе становится администратором независимо от способа входа, которым он создан. Предоставьте права администратора кому-либо ещё на странице Панель администратора → Пользователи или добавьте в группу, которая даёт нужные права.
Enterprise Edition добавляет два поведения на этом пути. Адреса электронной почты из списка администраторов по умолчанию становятся администраторами при создании. Создание нового пользователя также занимает место по лицензии, поэтому вход неизвестного пользователя завершается ошибкой, когда рабочее пространство достигает лимита мест. В Community Edition лимита мест нет.

​
Приоритет

Действительный cookie сессии Yahont имеет приоритет. Yahont читает заголовок Authorization только если у запроса нет сессии. API-ключи и персональные токены доступа используют тот же заголовок. Yahont сначала пробует путь JWT, а значение, не являющееся корректным JWT RS256, переходит к путям API-ключей и персональных токенов доступа. Эти учётные данные продолжают работать без изменений, когда задан JWT_PUBLIC_KEY_URL.

​
Поддержка и стабильность

JWT_PUBLIC_KEY_URL — документированный и поддерживаемый параметр конфигурации. Yahont относится к нему так же, как к любому другому опубликованному параметру на этой странице:
  • Имя переменной, заголовок Authorization: Bearer, требование RS256, допустимые форматы ключей и порядок утверждений идентификации входят в документированный интерфейс.
  • Автоматические тесты покрывают описанное выше поведение — вход существующего пользователя, создание пользователя при первом входе, отклонение токенов, подписанных неизвестным ключом, отклонение просроченных токенов и ротацию ключей без перезапуска.
  • Если в будущем релизе этот параметр изменится или будет заменён, изменение будет указано в примечаниях к этому релизу вместе с механизмом, который его заменяет.
Если вы планируете строить интеграцию на этом параметре, свяжитесь с нами. Мы будем рады изучить вашу архитектуру и рассказать обо всём в плане развития, что её касается.

​
Устранение неполадок

Yahont записывает в журнал API-сервера каждую неудачную проверку. Ищите эти сообщения в журналах api_server: Запрос, не прошедший проверку JWT, не отклоняется сразу. Он продолжается как неаутентифицированный, а конечная точка возвращает 401, если ей нужен пользователь.