Well Known — Versola Docs
VersolaVersola/docs
До 1.00.7.1versola.kzGitHub
RUEN

Well Known

Справочник по экрану Well Known консоли администратора — JWKS, который публикует Versola, генерация, добавление и удаление ключей подписи, метаданные сервера

Экран Well Known управляет публичной конфигурацией, которую Versola отдаёт наружу: набором ключей JSON Web Key Set (JWKS), по которому клиенты и API проверяют ваши токены, и документом метаданных сервера. Здесь можно сгенерировать ключ подписи, опубликовать ключ, который вы храните в другом месте, или вывести старый ключ из обращения. Ключ начинает подписывать токены тенанта только после того, как вы выберете его в Token Signing Key на экране Challenges & Security.

Перед началом

Что нужноРазрешение
Видеть ключи и метаданныеjwks:read
Генерировать, добавлять, менять и удалять ключи, менять метаданныеjwks:manage

Экран общий, он не зависит от выбранного в боковой панели тенанта. Без jwks:manage кнопок + Add Key, Generate Key, ✎ и ✕ нет.

Well Known: JWKS и Server Metadata
Страница Well Known: список JWKS с ключами PS256 и ES256 «только для проверки» и ключом ES256 с пометкой Can sign, выбор алгоритма с кнопкой Generate Key и ниже JSON Server Metadata.

JWKS

Каждый ключ — это карточка с его kid, типом и алгоритмом (например, EC · ES256), значком и опубликованным JWK. Значок говорит, что Versola умеет делать с ключом:

ЗначокЗначение
Can signCentral хранит закрытую часть, у ключа известный alg. Тенант может выбрать его как Token Signing Key.
Verify onlyУ Central только открытый JWK. Ключ опубликован, чтобы проверяющие его принимали, но подписывать им ничего не будут.

Развёртывание, засеянное из bootstrap.jwks, начинает с ключей «только для проверки»: закрытые части этих ключей Central не получал. Чтобы получить ключ, которым можно подписывать, сгенерируйте его.

Algorithms

Список рядом с Generate Key предлагает три алгоритма:

АлгоритмКакой ключ создаётсяПримечания
PS256RSA-2048Выбирается по умолчанию для нового тенанта, у которого нет выбранного ключа.
ES256EC, кривая P-256Тоже допустим в FAPI 2.0.
RS256RSA-2048Сгенерировать можно для любого тенанта, а выбрать для подписи — только у тенанта с профилем безопасности Standard. На тенанте FAPI 2.0 Central его отклоняет.

PS256 и ES256 разрешены в обоих профилях. HS256 не предлагается: общему секрету нечего публиковать в JWKS. kid сгенерированного ключа — это метка времени и алгоритм, например 2026-10-14_07-29-17-es256.

Generate Key

Generate Key создаёт пару ключей для выбранного алгоритма, сразу публикует открытую часть, а закрытую хранит в Central в зашифрованном виде. Закрытый ключ в консоли не показывается и не скачивается.

Подсказка под кнопками описывает следствие: сгенерированный ключ публикуется для проверки сразу, но ничего не подписывает, пока тенант не выберет его в Challenges & Security, так что все проверяющие узнают ключ раньше, чем кто-либо начнёт выпускать токены с ним.

+ Add Key

+ Add Key открывает Add JWK с полем JWK JSON, куда вставляется открытый JWK. Так публикуют ключ, закрытую часть которого вы храните в другом месте. Консоль требует kid и kty; Central требует kid и иначе отвечает JWK must contain a 'kid' field или Invalid JWK JSON. Добавленный так ключ всегда Verify only.

Add JWK
Форма Add JWK под выбором алгоритма: текстовое поле JWK JSON и кнопки Add Key и Cancel.

Изменение и удаление

Значок ✎ открывает JWK существующего ключа для редактирования; kid менять нельзя (удалите ключ и добавьте новый). Значок ✕ запрашивает подтверждение в диалоге Delete JWK и затем убирает ключ из JWKS.

Central не удаляет ключ, которым ещё подписывает какой-либо тенант, и отвечает Key '<kid>' is the signing key of <tenants>. Select another key for them before deleting it. Сначала переведите эти тенанты на другой ключ. После удаления ключ больше не публикуется, и токены, подписанные им, проверить уже нечем.

Где используются ключи

ПотребительЧто использует
auth, подписьКлюч, выбранный для тенанта как Token Signing Key, подписывает access-токены, ID-токены и logout-токены. Алгоритм берётся из ключа. Тенант без выбора подписывает закрытым ключом из конфигурации jwt.private-key сервиса auth.
auth, публикацияGET /.well-known/jwks.json возвращает открытые части всех ключей с заголовком Cache-Control: public, max-age=86400. Аутентификация не нужна. Resource server при незнакомом kid должен запросить набор заново, а не ждать истечения кэша.
edgeПроверяет токены по открытым частям, которые синхронизирует из Central. Закрытый ключ он не получает никогда.
CentralПроверяет токены консоли администратора этими же ключами.

Формат набора описан в RFC 7517. Endpoint Central за этим экраном (/configuration/jwks) описаны в справочнике OpenAPI.

Ротация ключа подписи

Экран поддерживает ротацию в три шага:

  1. Generate Key для нужного алгоритма. Новый ключ публикуется, но им пока никто не подписывает.
  2. Откройте Challenges & Security каждого тенанта и выберите новый ключ в Token Signing Key. auth переключится на него после синхронизации ключа; до этого он продолжает подписывать прежним.
  3. Удалите старый ключ, когда не осталось токенов, которые вам ещё нужно проверять и которые подписаны им. Подождите не меньше, чем живёт самый долгоживущий токен с этой подписью, и не меньше, чем проверяющие кэшируют JWKS (24 часа для ответов auth).

Versola не ротирует ключи по расписанию и сама их не выводит из обращения.

Server Metadata

Под ключами Server Metadata показывает документ метаданных сервера авторизации в виде JSON. Значок ✎ открывает его на редактирование. Консоль требует issuer, authorization_endpoint, token_endpoint, jwks_uri и response_types_supported и без них не сохраняет. auth отдаёт документ по адресам /.well-known/openid-configuration и /.well-known/oauth-authorization-server. Член authorization_details_types_supported автоматически согласуется с типами, которые вы регистрируете в Challenges & Security. См. RFC 8414.

Что дальше