Успешная проверка API key отвечает только на вопрос «какой credential прислал клиент». Она не разрешает автоматически каждый метод. После lookup ключа endpoint должен проверить конкретное действие и объект: invoices:read не даёт POST /invoices, а project:write не должен менять соседний tenant.
Начните с deny-by-default. Пока route не сопоставлен permission, ключ получает 403 и audit reason. Временное правило «старым ключам разрешить всё» допустимо только как измеряемая миграция с владельцем и датой завершения, иначе оно станет постоянным обходом новой модели.
Scope называет действие, а не URL-строку
| Scope | Разрешает | Не разрешает |
|---|---|---|
| orders:read | GET списка и одного заказа | Создание и изменение |
| orders:write | POST/PATCH по политике | Удаление без отдельного права |
| orders:cancel | Команду отмены | Произвольный PATCH статуса |
| reports:export | Создание export job | Чтение чужого файла |
| admin:* | Только специально выданный набор | Автоматический доступ будущим routes |
Названия — локальный контракт, а не стандарт OAuth. RFC 6749 определяет scope как набор регистрозависимых строк, смысл которых задаёт authorization server. Для собственного API key применим тот же принцип наименьших полномочий, но не называйте opaque key OAuth access token, если у системы нет соответствующего protocol flow.
Policy проверяет нормализованный route
required = policy.permissionFor(
method = request.method,
route = request.routeTemplate // /projects/{id}/deploy
)
principal = apiKeys.authenticate(rawKey)
resource = projects.load(request.path.id)
authorize(principal, required, resource.tenantId)
audit(keyId, required, resource.id, decision)Псевдокод показывает порядок, а не готовую библиотеку. Используйте route template после router match, а не сырой path: иначе /projects/42 и /projects/43 станут разными permissions. Но одного route недостаточно — object-level проверка подтверждает tenant, ownership, состояние и допустимость действия.
Key ID живёт отдельно от секрета
- Показывать secret только при создании и хранить проверяемый hash, если формат позволяет.
- Передавать ключ только по HTTPS и никогда через query string.
- Хранить key ID, owner, scopes, tenant constraints, created/expires/revoked и last used.
- Не писать raw key в access log, trace, error body и audit event.
- Ограничивать rate и network ranges как дополнительные условия, а не замену authorization.
- Поддерживать немедленный revoke и контролируемый overlap при ротации.
OWASP указывает, что non-public REST service выполняет access control на каждом endpoint. Gateway может отсеять очевидно запрещённый route, но сервис повторяет решение локально: внутренний обход gateway, новая версия route или ошибочный proxy mapping не должны расширять права.
OpenAPI описывает передачу ключа, не всю политику
Security Scheme типа apiKey фиксирует имя header/cookie/query и требования operation, но сама спецификация не реализует проверку scopes для произвольного API key. Документируйте permissions отдельным расширением или каталогом policy и генерируйте route inventory в CI. Не помещайте рабочий ключ в OpenAPI example или Swagger UI default.
Существующие ключи мигрируем по наблюдаемому использованию
- Собрать route usage по key ID без хранения secret и payload.
- Сопоставить observed calls с владельцем интеграции.
- Предложить минимальный scope set и срок подтверждения.
- Включить shadow decision: логировать будущие deny без блокировки.
- Выдать новый scoped key и провести overlap.
- Переключить enforcement, затем отозвать all-access credential.
- Оставить alert на denied calls и попытки неизвестного route.
Observed usage не доказывает, что все вызовы легитимны, поэтому владелец подтверждает назначение. Не добавляйте scope автоматически при первом 403: это превращает атаку или ошибку клиента в расширение прав.
Матрица негативных тестов закрывает обходы
orders:read + GET /orders/42 -> allow
orders:read + PATCH /orders/42 -> deny
orders:write + PATCH /tenants/other/... -> deny
unknown scope + GET /new-admin-route -> deny
revoked key + GET /orders/42 -> deny
valid key + method override header -> deny/normalize onceДобавьте encoded paths, trailing slash, HEAD/OPTIONS policy, batch endpoints и resource, сменивший tenant. Успех — любое новое действие закрыто до явного mapping, audit содержит key ID и reason без секрета, а отозванный key перестаёт работать на всех replicas. Для ревью подготовьте route inventory, scope registry, policy code, migration report и обезличенные audit decisions.