Keys & metadata — Versola Docs

Страница Keys & metadata управляет публичной конфигурацией, которую Versola отдает наружу: набором ключей JSON Web Key Set (JWKS), по которому клиенты и API проверяют ваши токены, и переопределениями документа метаданных сервера. Здесь можно сгенерировать ключ подписи, опубликовать ключ, который вы храните в другом месте, или вывести из обращения старый. Ключ подписывает токены тенанта только после того, как вы выберете его как Signing key в Tokens & keys на странице Security.

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

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

Страница глобальная и не зависит от выбора тенанта. Без jwks:manage кнопок Generate key и Add key (paste JWK), кнопок Edit и действий удаления нет. Без tenants:read колонку Used by и карточку Used by tenants заполнить нельзя, вместо них показана заметка.

Keys

В таблице одна строка на ключ, колонки Key ID (kid), Type (например, EC · P-256), Algorithm, Usage и Used by (сколько тенантов подписывают этим ключом). Фильтры All, Can sign и Verify only сужают таблицу. В меню строки есть Open, Copy key ID и Delete key. Баннер над таблицей описывает следствие генерации ключа: он публикуется для проверки сразу, но ничего не подписывает, пока тенант не выберет его.

Бейдж Usage показывает, что Versola может делать с ключом:

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

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

Панель ключа

Выбор строки открывает панель:

Used by tenants — тенанты, у которых этот ключ выбран ключом подписи, каждый ссылкой на тенант. Ключ тенанта меняется в Security › Tokens & keys.
Public key — JWK в том виде, в каком он опубликован, с кнопкой Copy JWK. Edit открывает JWK для редактирования.
Fixed — ID ключа и алгоритм (берется из JWK). kid изменить нельзя: удалите ключ и добавьте новый.
Delete key после подтверждения: проверяющие перестают доверять ключу при следующей синхронизации, а токены, подписанные им, перестают проходить проверку.

Central отказывается удалять ключ, которым еще подписывает тенант, с текстом Key '<kid>' is the signing key of <tenants>. Select another key for them before deleting it. Консоль заранее делает действия удаления неактивными и пишет Still selected by N tenants. Move them to another key first. После удаления ключ больше не публикуется, поэтому токены, подписанные им, проверить уже нельзя.

Generate key

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

Алгоритм	Какой ключ создается	Примечания
`ES256` (recommended)	EC, кривая P-256	Допустим в любом профиле безопасности.
`PS256`	RSA-2048	Допустим в любом профиле безопасности. Новый тенант выбирает ключ `PS256` раньше `ES256`, если есть оба.
`RS256`	RSA-2048	Можно сгенерировать в любом развертывании, но выбрать для подписи — только у тенанта с профилем безопасности Standard. На тенанте FAPI 2.0 Central его отклоняет.

HS256 не предлагается: у общего секрета нет публичной части для JWKS. kid сгенерированного ключа — метка времени и алгоритм, например 2026-10-14_07-29-17-es256.

Add key (paste JWK)

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

Панель добавления ключа с полем JWK JSON и подсказкой, что нужны как минимум kty и kid. — Add key (paste JWK)

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

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

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

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

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

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

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

Перевод существующего развертывания на ES256

Развертывание, сгенерированное versola-cli, с самого начала подписывает ES256. Развертывание, где уже лежит RSA-ключ jwt.private-key, после обновления продолжает подписывать им; само ничего не переезжает. Чтобы перевести его:

Нажмите Generate key и выберите ES256 (или вызовите POST /configuration/jwks/generate?alg=ES256). Ключ публикуется, но пока никто им не подписывает.
Откройте Security каждого тенанта и выберите новый ключ как Signing key в Tokens & keys.
Держите старый ключ опубликованным, пока не истекут токены, выпущенные им, затем удалите его, как в ротации выше.

Тенант, которому нужен PS256 или RS256, выбирает такой ключ так же. RS256 никогда не используется по умолчанию и допускается только на тенанте с профилем Standard.

Server metadata overrides

Под ключами Server metadata overrides показывает в виде JSON члены, которые накладываются на документ метаданных сервера, вычисляемый auth (RFC 8414). Edit открывает Edit server metadata overrides, Save server metadata сохраняет их. Заданный здесь член заменяет вычисленный. Консоль требует issuer, authorization_endpoint, token_endpoint, jwks_uri и response_types_supported и без них не сохраняет. auth отдает документ по /.well-known/openid-configuration и /.well-known/oauth-authorization-server. Член authorization_details_types_supported согласуется с типами, которые вы регистрируете на странице Authorization details. Если переопределений нет, карточка пишет No overrides set.

Что дальше

Security — выбор ключа подписи для тенанта
Профили безопасности — правило про RS256
RFC 7517 и справочник OpenAPI