JWK Set: структура и назначение

Назначение JWK Set

JWK Set (JSON Web Key Set, JWKS) представляет собой стандартный формат для публикации набора криптографических ключей в виде JSON-документа. В контексте библиотеки Jose в JavaScript он используется как основной механизм распространения публичных ключей, необходимых для проверки подписи JWT (JSON Web Token), JWS (JSON Web Signature) и других объектов семейства JOSE.

Ключевая идея JWKS заключается в разделении ролей:

  • сервер авторизации хранит и управляет приватными ключами;
  • клиент или ресурсный сервер получает публичные ключи через JWKS и выполняет верификацию токенов.

Такой подход обеспечивает масштабируемость, поддержку ротации ключей и минимизацию риска компрометации.

Общая структура JWK Set

JWK Set всегда представляет собой JSON-объект с обязательным полем keys, содержащим массив ключей.

{
  "keys": [
    { ... },
    { ... }
  ]
}

Каждый элемент массива — это отдельный JWK (JSON Web Key), описывающий конкретный криптографический ключ.

Структура отдельного JWK

Каждый ключ внутри JWKS описывается набором параметров, определяющих его тип, назначение и криптографические свойства.

Основные поля

kty (Key Type) Определяет тип криптографического алгоритма:

  • RSA — асимметричные RSA ключи
  • EC — эллиптические кривые
  • oct — симметричные ключи

kid (Key ID) Уникальный идентификатор ключа. Используется для выбора правильного ключа при проверке JWT.

  • критически важен при ротации ключей
  • позволяет сопоставить JWT header с конкретным ключом

use (Public Key Use) Назначение ключа:

  • sig — подпись (signing)
  • enc — шифрование (encryption)

alg (Algorithm) Алгоритм, с которым должен использоваться ключ:

  • RS256, RS384, RS512
  • ES256, ES384, ES512
  • и другие, поддерживаемые JOSE

RSA-ключи в JWKS

Для RSA ключей используются дополнительные параметры:

n (modulus) Модуль RSA ключа, закодированный в Base64URL.

e (exponent) Экспонента RSA, обычно AQAB (65537).

Пример структуры RSA ключа:

{
  "kty": "RSA",
  "kid": "key-1",
  "use": "sig",
  "alg": "RS256",
  "n": "base64url-modulus",
  "e": "AQAB"
}

EC-ключи (Elliptic Curve)

Для эллиптических кривых используются другие параметры:

crv (Curve) Тип кривой:

  • P-256
  • P-384
  • P-521

x (X coordinate) Координата точки на кривой.

y (Y coordinate) Вторая координата точки.

Пример:

{
  "kty": "EC",
  "kid": "ec-key-1",
  "use": "sig",
  "alg": "ES256",
  "crv": "P-256",
  "x": "base64url-x",
  "y": "base64url-y"
}

Симметричные ключи (oct)

Для симметричных алгоритмов используется поле:

k (key value) Секретный ключ в Base64URL.

{
  "kty": "oct",
  "kid": "sym-1",
  "use": "sig",
  "k": "base64url-secret"
}

Роль JWKS в библиотеке Jose

В экосистеме Jose JWKS играет центральную роль при валидации токенов:

  • извлечение ключа по kid
  • автоматический выбор алгоритма
  • проверка подписи JWT без ручного управления ключами

Типичный сценарий:

  1. JWT содержит заголовок:

    {
  "alg": "RS256",
  "kid": "key-1"
}

  2. JWKS содержит набор ключей

  3. библиотека Jose сопоставляет kid с нужным JWK

  4. выполняется проверка подписи

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

JWKS обеспечивает безопасную ротацию ключей без остановки сервиса.

Механизм:

  • добавляется новый ключ в keys
  • старый ключ сохраняется до истечения срока действия всех токенов
  • JWT продолжают валидироваться по kid

Это позволяет:

  • обновлять ключи без разрыва сессий
  • минимизировать риск компрометации
  • поддерживать несколько активных ключей одновременно

Эндпоинт JWKS

В реальных системах JWKS публикуется через HTTP endpoint:

GET /.well-known/jwks.json

Ответ содержит стандартный JSON с массивом ключей.

Библиотека Jose может автоматически загружать и кешировать этот набор.

Особенности обработки JWKS в Jose

При работе с JWKS библиотека Jose учитывает:

  • проверку корректности структуры ключей
  • фильтрацию по kid
  • соответствие алгоритма alg
  • поддержку обновления ключей (refresh)

Дополнительно часто используется кеширование JWKS для снижения нагрузки на сервер авторизации.

Типичные ошибки в структуре JWKS

Некорректная конфигурация часто приводит к сбоям в верификации:

  • отсутствует kid у ключа
  • несовпадение alg и фактического алгоритма JWT
  • повреждённые значения Base64URL (n, e, x, y, k)
  • отсутствие активного ключа для текущего kid

Связь JWKS и безопасности

JWKS напрямую влияет на безопасность всей системы токенов:

  • правильная изоляция приватных ключей
  • минимизация поверхности атаки
  • возможность быстрого отзыва ключей
  • централизованное управление криптографией

Использование JWKS вместо статически заданных ключей в коде снижает риск утечки секретов и упрощает архитектуру распределённых систем аутентификации.

Оглавление