RFC 7517 — JSON Web Key

Спецификация: RFC 7517

JSON Web Key (JWK) задает JSON-формат криптографических ключей. Versola публикует endpoint JWKS, чтобы resource server и relying party проверяли подписи токенов, не обращаясь к authorization server для каждого токена.

Статус

Реализован частично. Отмечено пунктов: 16 из 21.

Endpoint JWKS

Endpoint GET /.well-known/jwks.json (раздел 5)
Ответ с Content-Type: application/json
Cache-Control: public, max-age=86400 — ключи публично кешируются
Все действующие публичные ключи входят в набор, поэтому ротация идет без простоя
Приватный ключевой материал не публикуется (DiscoveryAndJwksSpec)

Поля RSA-ключа (раздел 6.3)

kty — RSA
use — sig
alg — RS256 или PS256, как опубликовал ключ оператор
kid — идентификатор ключа, сопоставляется с заголовком kid JWT
n и e — модуль и публичная экспонента в Base64URL

Поля EC-ключа (раздел 6.2)

kty — EC, с crv P-256, alg ES256, use sig, kid, x и y

Типы ключей

RSA-ключи (kty: "RSA")
EC-ключи (kty: "EC", только P-256)
EC-ключи P-384 или P-521 — не поддерживаются
Ключи OKP (kty: "OKP", Ed25519) — не поддерживаются

Необязательные поля

x5c — цепочка сертификатов X.509 — не включается
x5t — SHA-1 отпечаток сертификата X.509 — не включается
x5u — URL сертификата X.509 — не включается

Ротация ключей

Ключи создаются в консоли администратора (Keys & metadata) как RS256, PS256 или ES256 и выбираются для подписи на уровне тенанта (SigningKeySelectionSpec)
Проверка выбирает ключ по kid, поэтому токены, подписанные старым ключом, остаются действительными, пока ключ есть в наборе
Клиенты регистрируют собственный JWK Set для private_key_jwt, объектов запроса и self_signed_tls_client_auth; см. RFC 7523

Примечания

Тенант fapi2 не может выбрать ключ RS256 для подписи, хотя сам ключ в наборе может быть; см. FAPI 2.0.
Ключ, опубликованный без пригодного alg, пропускается при подписи и игнорируется в публикуемых наборах алгоритмов.

Куда смотреть

Справочник OpenAPI содержит спецификацию JWKS.