Аутентификация

JWT и Discovery

Формат JWT-токенов Julia (EdDSA / Ed25519), список claims, эндпоинты /.well-known и проверка подписи.

Julia выпускает JWT-токены для пользователей, подписанные асимметричным алгоритмом EdDSA на кривой Ed25519. Внешние и внутренние сервисы могут проверять подпись локально, используя публичный ключ из Discovery или REST/gRPC API.

Эндпоинты Discovery и получения ключа

ЭндпоинтАвторизацияНазначение
GET /.well-known/openid-configurationПубличный (CORS *)Метаданные эмитента (issuer, jwks_uri, claims_supported, алгоритмы)
GET /.well-known/jwks.jsonПубличный (CORS *)Публичный ключ в формате JWK (kty: OKP, crv: Ed25519, alg: EdDSA)
GET /v1/auth/publickey?type=base64|pemПубличныйСырой публичный ключ (text/plain) в Base64 (32 байта) или PEM
gRPC Keys.GetPublicKeyПубличныйПолучение публичного ключа в BASE64 или PEM по gRPC

Пример /.well-known/openid-configuration

{
  "issuer": "https://auth.mirea.app",
  "jwks_uri": "https://auth.mirea.app/.well-known/jwks.json",
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["EdDSA"],
  "response_types_supported": [],
  "grant_types_supported": [],
  "claims_supported": [
    "iss", "aud", "exp", "nbf", "iat",
    "sub", "subject_type", "token_type", "name", "sid", "jti"
  ]
}

Пример /.well-known/jwks.json

{
  "keys": [
    {
      "kty": "OKP",
      "crv": "Ed25519",
      "x": "<base64url-encoded-32-byte-public-key>",
      "alg": "EdDSA",
      "use": "sig",
      "kid": "<key-id>"
    }
  ]
}

Структура JWT и список claims

Заголовок токена содержит alg: "EdDSA" и kid, совпадающий с kid в JWKS.

ClaimТипОписание
issstringИдентификатор эмитента (совпадает с issuer из openid-configuration)
audstring | string[]Целевая аудитория токена
exp, nbf, iatnumberВременные метки Unix (истечение, начало действия, выпуск)
subUUIDИдентификатор субъекта (UUID пользователя)
subject_typestringТип субъекта: user или machine
token_typestringНазначение токена: access или refresh
namestringИмя пользователя (username)
sidUUIDИдентификатор сессии пользователя (присутствует только в JWT)
jtiUUIDУникальный идентификатор конкретного токена
Права доступа (permissions) не вшиваются в пользовательские JWT. Это сделано намеренно, чтобы изменения ролей и отделов применялись без ожидания истечения токена. Актуальные права пользователя запрашивайте через REST (GET /v1/users/{uuid}/permissions) или gRPC (Permissions.GetPermissions / Users.GetUser).

Правила валидации на стороне потребителя

При проверке входящего Authorization: Bearer <token> рекомендуется соблюдать пять правил:

  1. Ограничьте алгоритм строго EdDSA — не принимайте HS256, RS256 или none.
  2. Проверяйте token_type == "access" — не допускайте использование refresh-токенов для авторизации запросов к API.
  3. Проверяйте iss, aud, exp, nbf и соответствие kid текущему ключу.
  4. Не перечитывайте JWKS на каждый неизвестный kid — обновляйте публичный ключ по расписанию (например, раз в 5–15 минут). Загрузка ключа по требованию на неизвестный kid позволяет внешнему клиенту вызывать шквал запросов в Julia, подставляя случайные заголовки.
  5. Учитывайте ротацию ключа — Julia в каждый момент подписывает токены одним активным ключом; после ротации старый ключ перестаёт приниматься.

Проверка отозванных токенов

Если вашему сервису критична мгновенная проверка досрочно отозванных access-токенов (например, после logout до истечения exp), доступен список отозванных jti:

GET /v1/auth/expired
Authorization: Bearer <jwt>
# или
X-Api-Key: <api-key>

Эндпоинт возвращает массив строк — значений jti отозванных токенов, срок действия которых ещё не истёк:

[
  "019f9bdc-13b5-7e2b-bc68-ccf3446d2cc0",
  "019f9bdd-89a0-7f11-94c2-1189fa320e12"
]