API-ключи
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_id | UUID записи ключа |
subject_type | SUBJECT_TYPE_USER или SUBJECT_TYPE_MACHINE |
subject_id | UUID пользователя или сервиса |
name | Имя ключа |
permissions | Эффективные права ключа (для pat уже пересечены с актуальными правами владельца) |
expires_at | Срок действия ключа (жёсткий предел) |
cache_ttl_seconds | Разрешённое время кеширования ответа |
ip_unrestricted | true, если у ключа нет ограничений по IP; false, если ответ зависит от remote_ip |
error | Код причины при valid = false (MALFORMED, NOT_FOUND, IP_FORBIDDEN, REVOKED, EXPIRED) |
permissions из ответа напрямую. Для пользовательского ключа сохранённые на нём права выступают потолком, а не выдачей — Julia уже вычисляет пересечение с живыми правами пользователя.Безопасное кеширование результата интроспекции
Чтобы не вызывать Julia на каждый запрос и при этом не создать уязвимость:
- Ключ кеша —
SHA-256от предъявленного ключа, но никогда неtoken_id. Идентификаторtoken_idсодержится в самом ключе в открытом виде; кеширование поtoken_idпозволило бы подделать доступ, зная только ID. - Учитывайте
ip_unrestricted.- Если
ip_unrestricted == true, достаточно ключаsha256(key). - Если
ip_unrestricted == false, добавляйте в ключ кеша нормализованный IP-адрес клиента (sha256(key) + ":" + remoteIp), иначе ограничениеAllowedIpsперестанет работать для кешированных ответов.
- Если
- Соблюдайте TTL. Не храните запись дольше
cache_ttl_secondsи никогда — дольшеexpires_at.
Управление API-ключами (gRPC ApiTokens)
Управление ключами доступно по gRPC в сервисе admin.ApiTokens:
| Метод | Требуемое право | Примечание |
|---|---|---|
GetApiTokens | authservice.apitokens:read:self | Список ключей с курсорной пагинацией. Без глобального :read видны только собственные ключи |
GetApiToken | authservice.apitokens:read:self | Чужой ключ без глобального :read возвращается как не найденный |
CreateApiToken | authservice.apitokens:write:self (+ :write для svc) | Возвращает полный секрет в поле token один раз |
RevokeApiToken | authservice.apitokens:write:self (+ :write для чужих) | Идемпотентная операция |
IntrospectApiKey | authservice.apitokens:introspect | Только для сервисных ключей (machine) |
Правила выпуска ключей:
- Ключ не может получить право, которым не обладает сам вызывающий.
- Пользовательский ключ (
pat) всегда привязывается к текущему пользователю (subject_idиз запроса игнорируется). - Права и
AllowedIpsсуществующего ключа не редактируются — при необходимости выпустите новый ключ и отзовите старый.