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

API-ключи

Формат API-ключей Julia, передача в заголовке X-Api-Key, интроспекция через gRPC и безопасное кеширование.

API-ключи — это долгоживущие учётные данные, работающие наряду с JWT. Ключ может представлять как сервис (machine), так и пользователя (personal access token).

Передача ключа в запросах

API-ключ передаётся в HTTP-заголовке или gRPC-метаданных X-Api-Key:

X-Api-Key: cza-svc-019f9bdc...25782

При неуспешной аутентификации (неизвестный, отозванный, просроченный ключ или запрещённый IP-адрес) Julia возвращает одинаковый отказ, не раскрывая причину неавторизованному клиенту.

Формат ключа

ХарактеристикаЗначение
Общая длина104 символа (для текущего 3-символьного префикса cza)
Регулярное выражение^[a-z][a-z0-9]{2,15}-[a-z]{3}-[A-Za-z0-9]{96}$
Текущий префикс (namespace)cza
Классы ключейsvc — сервисный (machine), pat — пользовательский (personal access token)
Контрольная суммаПервые 6 hex-символов SHA-256 от первых 90 символов тела ключа
Маскированное представлениеpartial_token, например cza-pat-019f***c349 (безопасно для UI и логов)

Полное значение ключа возвращается один раз при создании и в дальнейшем не восстанавливается.

Рекомендации по локальной валидации

  • Валидируйте по структуре, а не по жёстко зашитому префиксу. Паттерн допускает любой namespace и любой 3-буквенный класс — это позволяет вводить новые классы без срочного обновления всех потребителей.
  • Сегмент класса (svc / pat) — это подсказка, а не источник истины. Реальный тип субъекта (user или machine) и права определяет только Julia при интроспекции.
  • Контрольная сумма отсеивает опечатки, но не заменяет проверку. Успешный локальный парсинг лишь экономит сетевой запрос, но не означает, что ключ действителен.
  • Для локального разбора, хеширования и получения маски используйте класс ApiKey из пакета Cyberzone.Julia.Authorization (.NET) или подпакет apikey из модуля julia-go (Go).

Ограничение по IP-адресам (AllowedIps)

Для ключа может быть задан список разрешённых IP-адресов (allowed_ips). Если список не пуст, запросы с других адресов отклоняются.

  • IPv4-mapped IPv6 адреса (например, ::ffff:203.0.113.7) автоматически нормализуются к IPv4 (203.0.113.7).
  • Поддерживаются точные IP-адреса (CIDR-диапазоны не поддерживаются).

Проверка API-ключа в вашем сервисе (Introspection)

Если ваш сервис сам принимает API-ключи Julia от внешних клиентов, валидируйте формат локально и проверяйте ключ через gRPC-метод ApiTokens.IntrospectApiKey:

rpc IntrospectApiKey (IntrospectApiKeyRequest) returns (IntrospectApiKeyResponse);

Для вызова требуется сервисный ключ с правом authservice.apitokens:introspect. В запросе передайте сам ключ и IP-адрес конечного клиента (remote_ip).

Поля ответа IntrospectApiKeyResponse

ПолеОписание
validДействителен ли ключ с указанного remote_ip
token_idUUID записи ключа
subject_typeSUBJECT_TYPE_USER или SUBJECT_TYPE_MACHINE
subject_idUUID пользователя или сервиса
nameИмя ключа
permissionsЭффективные права ключа (для pat уже пересечены с актуальными правами владельца)
expires_atСрок действия ключа (жёсткий предел)
cache_ttl_secondsРазрешённое время кеширования ответа
ip_unrestrictedtrue, если у ключа нет ограничений по IP; false, если ответ зависит от remote_ip
errorКод причины при valid = false (MALFORMED, NOT_FOUND, IP_FORBIDDEN, REVOKED, EXPIRED)
Используйте permissions из ответа напрямую. Для пользовательского ключа сохранённые на нём права выступают потолком, а не выдачей — Julia уже вычисляет пересечение с живыми правами пользователя.

Безопасное кеширование результата интроспекции

Чтобы не вызывать Julia на каждый запрос и при этом не создать уязвимость:

  1. Ключ кеша — SHA-256 от предъявленного ключа, но никогда не token_id. Идентификатор token_id содержится в самом ключе в открытом виде; кеширование по token_id позволило бы подделать доступ, зная только ID.
  2. Учитывайте ip_unrestricted.
    • Если ip_unrestricted == true, достаточно ключа sha256(key).
    • Если ip_unrestricted == false, добавляйте в ключ кеша нормализованный IP-адрес клиента (sha256(key) + ":" + remoteIp), иначе ограничение AllowedIps перестанет работать для кешированных ответов.
  3. Соблюдайте TTL. Не храните запись дольше cache_ttl_seconds и никогда — дольше expires_at.

Управление API-ключами (gRPC ApiTokens)

Управление ключами доступно по gRPC в сервисе admin.ApiTokens:

МетодТребуемое правоПримечание
GetApiTokensauthservice.apitokens:read:selfСписок ключей с курсорной пагинацией. Без глобального :read видны только собственные ключи
GetApiTokenauthservice.apitokens:read:selfЧужой ключ без глобального :read возвращается как не найденный
CreateApiTokenauthservice.apitokens:write:self (+ :write для svc)Возвращает полный секрет в поле token один раз
RevokeApiTokenauthservice.apitokens:write:self (+ :write для чужих)Идемпотентная операция
IntrospectApiKeyauthservice.apitokens:introspectТолько для сервисных ключей (machine)

Правила выпуска ключей:

  • Ключ не может получить право, которым не обладает сам вызывающий.
  • Пользовательский ключ (pat) всегда привязывается к текущему пользователю (subject_id из запроса игнорируется).
  • Права и AllowedIps существующего ключа не редактируются — при необходимости выпустите новый ключ и отзовите старый.