Разграничение доступа к API: сравнение моделей безопасности

API-ключа достаточно, чтобы отличить один сервис от другого, но недостаточно, чтобы безопасно управлять доступом пользователей к десяткам методов. Для внутренних сервисов чаще нужен mTLS или короткоживущий токен, для публичного API — OAuth 2.0 с ограниченными scope, а для простого серверного интеграционного вызова — ключ с ротацией и лимитами. Ошибка в выборе превращает утёкший токен в доступ ко всему API.

Сначала разделите три разные задачи

Разграничение доступа начинается не с выбора формата токена. Сначала нужно ответить на три вопроса.

• Кто обращается к API. Пользователь, мобильное приложение, сервер партнёра или ваш внутренний сервис.
• Что именно разрешено. Только чтение заказов, изменение профиля, запуск платежа или административные операции.
• В каком контексте разрешён вызов. Организация, проект, окружение, IP-сеть, время, устройство или уровень риска.

Аутентификация подтверждает, кто отправил запрос. Авторизация решает, можно ли этому субъекту выполнить конкретное действие. Если после проверки токена API просто отвечает «доступ разрешён», но не проверяет ресурс, владельца и операцию, разграничение получилось формальным.

Scope^[1] — ограниченное разрешение в токене, например orders:read. Scope не заменяет проверку владельца объекта: право читать заказы ещё не означает право читать заказы любого клиента.

Варианты и цена каждого решения

API-ключ: простой вход для сервиса

Ключ подходит для серверных интеграций, где нужно идентифицировать приложение, а не отдельного человека. Его удобно создать в панели, отозвать и связать с лимитом запросов. Но ключ обычно не содержит достоверного набора прав и часто живёт слишком долго.

Минимальная безопасная схема — отдельный ключ на каждое приложение, передача только по HTTPS, хранение в менеджере секретов, ограничение методов и регулярная ротация. Не передавайте его в URL: адреса попадают в журналы прокси, историю браузера и системы аналитики. В проде полезно уметь временно отключать ключ без остановки интеграции.

OAuth 2.0: делегирование доступа пользователю

OAuth 2.0 нужен, когда приложение получает ограниченный доступ к API от имени пользователя или другой системы. Клиент не должен видеть пароль пользователя: он получает access token с конкретными разрешениями. Для входа человека поверх OAuth обычно используют OpenID Connect 1.0, который добавляет слой идентификации.

Для веб-приложения с пользовательским входом выбирайте Authorization Code Flow с PKCE. Не пытайтесь заменить им обычный API-ключ для фоновой задачи: там появляются лишние компоненты — authorization server, регистрация клиента, отзыв и обновление токенов.

Главная опасность OAuth — проверять только факт наличия токена. Ресурсный сервер должен проверять подпись или интроспекцию токена, срок действия, issuer, audience и требуемые scope. Нельзя принимать любой JWT, который технически удалось разобрать.

JWT: формат, а не готовая модель доступа

JWT удобен для передачи утверждений между сервисами: идентификатора субъекта, аудитории, срока действия и разрешений. Он позволяет проверять токен локально и не обращаться к центральному серверу на каждый запрос. За это вы платите сложным отзывом: уже выданный токен может оставаться действительным до истечения срока.

JWT не шифрует данные по умолчанию. Подписанный токен защищает целостность, но его содержимое может быть прочитано тем, у кого есть сам токен. Не кладите туда секреты и персональные данные без отдельной необходимости. Ключи подписи должны ротироваться, а API — отклонять неподдерживаемые алгоритмы, неправильные издателя и аудиторию.

mTLS: удостоверить сервис на сетевом уровне

Взаимная TLS-аутентификация требует сертификат не только от сервера, но и от клиента. Это сильный вариант для связи между внутренними сервисами и партнёрами, особенно когда доступ должен быть возможен только из доверенной инфраструктуры.

mTLS не отвечает на вопрос, какие именно заказы можно изменить. Сертификат подтверждает сервис или его экземпляр, а не бизнес-права каждой операции. Поэтому поверх mTLS всё равно нужны роли, политики или scope. Цена решения — выпуск, хранение, ротация и отзыв сертификатов, а также настройка балансировщиков и сервисной сетки.

Сравнение подходов

Хорошая схема доступа ограничивает не только вход в API, но и последствия компрометации одного токена.

Как выбрать схему без универсального рецепта

Начинайте с типа клиента и цены ошибки, а не с популярности технологии.

1. Для одного внутреннего сервиса используйте mTLS, если у команды уже есть управление сертификатами. Добавьте сервисные роли и проверку действий на уровне API.
2. Для фоновой интеграции партнёра начните с отдельного API-ключа или client credentials в OAuth 2.0. Разделите разрешения по операциям и выдайте партнёру только нужный scope.
3. Для пользовательского веб-приложения применяйте Authorization Code Flow с PKCE. Access token делайте короткоживущим, а refresh token храните по правилам выбранной платформы и не отправляйте в обычные логи.
4. Для мобильного клиента не встраивайте общий секрет приложения: его можно извлечь из дистрибутива. Нужна пользовательская авторизация, PKCE, минимальные scope и серверная проверка каждой операции.
5. Для особо дорогих операций добавьте отдельную политику: повторную аутентификацию, подтверждение операции, идемпотентность и аудит. Один валидный токен не должен автоматически разрешать перевод денег или удаление данных.

Роли и политики: где токены заканчиваются

Scope удобно проверять на входе в маршрут, но бизнес-правила обычно глубже. Пользователь может иметь scope orders:read, однако видеть только заказы своей организации. Это проверка владельца ресурса, а не просто роль.

RBAC^[2] связывает права с ролями: например, «оператор» и «администратор». Он прост для небольшого продукта, но количество ролей быстро растёт, если появляются организации, проекты и исключения. Политики с атрибутами учитывают свойства субъекта, ресурса и запроса: организацию, регион, окружение и тип операции. Они гибче, но требуют отдельного тестирования и понятного журнала решений.

Проверяйте разрешение на каждом чувствительном объекте. Нельзя полагаться только на скрытие кнопки в интерфейсе или на маршрут вида /users/123: идентификатор в запросе не доказывает право на этот ресурс.

Что ломается в проде

• Токены попадают в логи. Фильтруйте заголовок авторизации, параметры запросов и тела ошибок до записи в систему наблюдаемости.
• Права меняются, а JWT остаётся валидным. Сокращайте TTL, используйте отзыв или интроспекцию там, где задержка отзыва критична.
• Проверяется подпись, но не аудитория. Токен для одного сервиса нельзя принимать в другом только потому, что его подписал тот же издатель.
• Один секрет используется везде. Разделяйте ключи по окружениям, сервисам и партнёрам. Иначе одна утечка расширяет радиус инцидента.
• Ошибки доступа раскрывают лишнее. Различие между «ресурс существует, но запрещён» и «ресурса нет» иногда позволяет перечислять идентификаторы. Выберите поведение осознанно и проверьте его в threat model.

Меряйте не только процент успешных запросов. Нужны доля отказов по причине авторизации, возраст токенов, количество активных ключей, время отзыва, обращения к административным методам и события ротации сертификатов. Без этих метрик невозможно понять, работает ли ограничение после изменения конфигурации.

Что настроить следующим шагом

Составьте матрицу «клиент — ресурс — операция — разрешение» для пяти самых дорогих действий API. Затем выпустите отдельные учётные данные для каждого клиента, добавьте негативные тесты на чужую организацию и проверьте, что токены и ключи не попадают в логи. После этого настройте ротацию и дашборд отказов по коду причины. Инвалидация refresh token и детальный threat model — отдельные темы, здесь важны именно границы доступа.

[1] Scope — строковое разрешение, которое клиент запрашивает, а сервер авторизации выдаёт в пределах своей политики.

[2] RBAC, role-based access control, — управление доступом на основе ролей. Роль объединяет набор разрешений и назначается субъекту.