Аутентификация
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 | Тип | Описание |
|---|---|---|
iss | string | Идентификатор эмитента (совпадает с issuer из openid-configuration) |
aud | string | string[] | Целевая аудитория токена |
exp, nbf, iat | number | Временные метки Unix (истечение, начало действия, выпуск) |
sub | UUID | Идентификатор субъекта (UUID пользователя) |
subject_type | string | Тип субъекта: user или machine |
token_type | string | Назначение токена: access или refresh |
name | string | Имя пользователя (username) |
sid | UUID | Идентификатор сессии пользователя (присутствует только в JWT) |
jti | UUID | Уникальный идентификатор конкретного токена |
Права доступа (
permissions) не вшиваются в пользовательские JWT. Это сделано намеренно, чтобы изменения ролей и отделов применялись без ожидания истечения токена. Актуальные права пользователя запрашивайте через REST (GET /v1/users/{uuid}/permissions) или gRPC (Permissions.GetPermissions / Users.GetUser).Правила валидации на стороне потребителя
При проверке входящего Authorization: Bearer <token> рекомендуется соблюдать пять правил:
- Ограничьте алгоритм строго
EdDSA— не принимайтеHS256,RS256илиnone. - Проверяйте
token_type == "access"— не допускайте использованиеrefresh-токенов для авторизации запросов к API. - Проверяйте
iss,aud,exp,nbfи соответствиеkidтекущему ключу. - Не перечитывайте JWKS на каждый неизвестный
kid— обновляйте публичный ключ по расписанию (например, раз в 5–15 минут). Загрузка ключа по требованию на неизвестныйkidпозволяет внешнему клиенту вызывать шквал запросов в Julia, подставляя случайные заголовки. - Учитывайте ротацию ключа — 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"
]