> ## Documentation Index > Fetch the complete documentation index at: https://docs.yahont.ai/llms.txt > Use this file to discover all available pages before exploring further. # Аутентификация по заголовку JWT > Аутентификация запросов API с помощью JWT, выпущенных вашим поставщиком удостоверений Yahont может принимать JWT, выпущенный вашим поставщиком удостоверений или API-шлюзом, и использовать его для аутентификации запроса. Это полезно, когда другая система уже хранит идентификацию пользователя и обращается к Yahont от его имени — например, API-шлюз, портал или сервис, стоящий перед Yahont для собственных пользователей. Задайте в `JWT_PUBLIC_KEY_URL` URL, по которому доступен материал открытого ключа вашего издателя токенов. Когда переменная задана, Yahont принимает подписанный JWT в заголовке `Authorization`: ``` Authorization: Bearer ``` > [!NOTE] > > Эта возможность входит в Yahont Community Edition. Для неё не нужна лицензия Enterprise, > и она работает одинаково в обеих редакциях. См. раздел [Поддержка и стабильность](#support-and-stability) ниже. ## Настройка **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. > [!TIP] > > Большинство поставщиков удостоверений указывают URL JWKS в своём документе обнаружения OIDC по адресу > `https:///.well-known/openid-configuration` в поле `jwks_uri`. **2. Настройте Yahont** Задайте переменную в файле `.env`. ```bash .env theme={null} JWT_PUBLIC_KEY_URL=https:///.well-known/jwks.json ``` Перезапустите API-сервер, чтобы применить изменение. **3. Отправьте запрос** Поместите токен в заголовок `Authorization` любого вызова API Yahont. `GET /api/me` возвращает пользователя, которого определил Yahont, поэтому это хорошая первая проверка. ```bash theme={null} curl https:///api/me \ -H "Authorization: Bearer " ``` ## Требования к токену | Требование | Значение | | - | - | | Подпись | RS256 | | Утверждение идентификации | Первый корректный адрес электронной почты из `email`, `preferred_username`, затем `upn` | | Срок действия | `exp` проверяется. Просроченные токены отклоняются | | Аудитория | `aud` и `iss` проверяются, если настроено ожидаемое значение, иначе не проверяются | Адрес из утверждения идентификации нормализуется и приводится к нижнему регистру. Он становится адресом электронной почты пользователя Yahont. > [!WARNING] > > Если ожидаемая аудитория не настроена, принимается любой токен, подписанный вашим настроенным ключом, > даже выпущенный для другого приложения. Если ключ подписи используется несколькими приложениями, > задайте ожидаемую аудиторию, чтобы аутентифицировались только токены, выпущенные для Yahont. ## Проверка аудитории и издателя Yahont может проверять утверждения `aud` и `iss`. Когда ожидаемое значение задано, токен с несовпадающим утверждением отклоняется, и токен без утверждения тоже отклоняется (проверка «закрывается при сбое»). Принимаются и строковая, и массивная формы `aud`, а массив, содержащий ожидаемую аудиторию, совпадает. Задайте значения в **Панель администратора** → **Безопасность и защита** → **Внешняя аутентификация JWT** или с помощью переменных окружения: | Настройка | Переменная окружения | | - | - | | URL открытого ключа | `JWT_PUBLIC_KEY_URL` | | Ожидаемая аудитория | `JWT_EXPECTED_AUDIENCE` | | Ожидаемый издатель | `JWT_EXPECTED_ISSUER` | Настройка, для которой задана переменная окружения, **закреплена**: значение из окружения важнее всего сохранённого в панели администратора, а поле отображается как текст только для чтения. Так конфигурация, определяющая доступ, остаётся проверяемой конфигурацией как кодом, которую нельзя изменить изнутри приложения, даже из аккаунта администратора. Если переменная не задана, действует значение, сохранённое в панели администратора. При запуске 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. Пользователь, созданный таким образом, не получает повышенных прав, за одним исключением: **первый** пользователь на пустом инстансе становится администратором независимо от способа входа, которым он создан. Предоставьте права администратора кому-либо ещё на странице **Панель администратора → Пользователи** или добавьте в группу, которая даёт нужные права. > [!NOTE] > > 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, допустимые форматы ключей и порядок утверждений идентификации входят в документированный интерфейс. * Автоматические тесты покрывают описанное выше поведение — вход существующего пользователя, создание пользователя при первом входе, отклонение токенов, подписанных неизвестным ключом, отклонение просроченных токенов и ротацию ключей без перезапуска. * Если в будущем релизе этот параметр изменится или будет заменён, изменение будет указано в примечаниях к этому релизу вместе с механизмом, который его заменяет. > [!NOTE] > > Если вы планируете строить интеграцию на этом параметре, [свяжитесь с нами](/deployment/miscellaneous/contact_us). > Мы будем рады изучить вашу архитектуру и рассказать обо всём в плане развития, что её касается. ## Устранение неполадок Yahont записывает в журнал API-сервера каждую неудачную проверку. Ищите эти сообщения в журналах `api_server`: | Сообщение журнала | Причина | | - | - | | `JWT_PUBLIC_KEY_URL is not set` | Переменная отсутствует или пуста | | `Failed to fetch JWT public key` | Yahont не может обратиться к URL. Проверьте правила исходящего трафика и TLS | | `JWT public key URL returned invalid JSON` | Ответ похож на JSON, но не разбирается | | `no JWKS 'keys' field was found` | Ответ JSON не является документом JWKS | | `No matching JWK found for token header` | `kid` токена отсутствует в документе JWKS | | `Invalid JWT token` | Неверная подпись, просроченный токен или алгоритм, отличный от RS256 | | `no email claim found` | Ни `email`, `preferred_username`, ни `upn` не содержат корректного адреса электронной почты | Запрос, не прошедший проверку JWT, не отклоняется сразу. Он продолжается как неаутентифицированный, а конечная точка возвращает `401`, если ей нужен пользователь. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.