Авторизация в интеграционных сценариях
Базовые термины HTTP и API — в основах интеграционного взаимодействия. Практика настройки на продакшене — Интеграции — Basic, Bearer и mTLS на практике.
Авторизация в интеграционных сценариях
Что такое интеграционная авторизация?
Интеграционная авторизация — это механизм, посредством которого одна система получает право выполнять определённые действия в другой системе в рамках интеграционного взаимодействия.
В отличие от пользовательской авторизации, где субъект — человек с ролью или правами, в интеграционном контексте субъектом выступает система (или её компонент: микросервис, функция, шлюз). Поэтому применяются специфические модели доверия.
Общая картина для пользовательского входа (сессия, JWT, SSO, grant flows OAuth 2.0) — в аутентификации и авторизации. Ниже — то, что чаще всего встречается именно в машинных интеграциях.
Basic Auth, Bearer и mTLS
В интеграциях эти три механизма встречаются чаще всего. Basic и Bearer — схемы заголовка Authorization на уровне HTTP (RFC 7617 и RFC 6750). mTLS — взаимная проверка сертификатов на этапе TLS-рукопожатия, до разбора тела запроса. Справочник по синтаксису и рискам — в аутентификации HTTP.
| Basic Auth | Bearer | mTLS | |
|---|---|---|---|
| Уровень | HTTP-заголовок | HTTP-заголовок | TLS (транспорт) |
| Что передаётся | Authorization: Basic base64(user:password) | Authorization: Bearer <token> | Клиентский и серверный X.509-сертификаты |
| Кто проверяет | Прикладной сервер (логин/пароль или их хеш в БД) | Прикладной сервер или gateway (JWT, opaque token, API-ключ в том же синтаксисе) | TLS-стек + политика CA / CN / SAN |
| Срок жизни | Пока не сменили пароль | Задаётся токеном (exp, rotation) | До истечения или отзыва сертификата |
| Типичный сценарий | Внутренние API, dev, legacy B2B, curl -u | OAuth 2.0, JWT access token, публичные API | Банки, госсектор, service mesh, Kafka SSL |
| Главный риск | Пароль в каждом запросе; base64 — не шифрование | Утечка долгоживущего токена в логах/репозитории | Сложность PKI, ротация cert на всех клиентах |
Basic Auth
Сервер отвечает 401 с WWW-Authenticate: Basic realm="…", клиент добавляет учётные данные к каждому запросу. Работает только с HTTPS; в production предпочтительны токены с ограниченным сроком, чтобы не гонять пароль по сети и иметь централизованный отзыв. Подробнее про эволюцию от Basic к сессиям и OAuth — WWW-Authenticate и HTTP Basic. В проектировании интеграций — авторизация в API. Примеры в терминале: утилита curl.
Authorization: Basic dXNlcjpwYXNzd29yZA==
Bearer
Схема не задаёт формат токена — только способ передачи: Bearer <token>. Внутри может быть JWT от OAuth, opaque access token или даже API-ключ (синтаксис тот же, проверка другая). Разбор на примере сложного HTTP-запроса — в интеграционном HTTP; сравнение JWT и API-ключа в одном заголовке — ниже. OAuth Client Credentials для M2M — раздел OAuth 2.0 в этой статье.
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9…
mTLS
Клиент и сервер предъявляют сертификаты при TLS handshake; прикладной код может дополнительно сопоставить Subject CN / SAN с записью партнёра. Не заменяет Bearer: часто mTLS на входе (кто подключился) плюс Bearer или JWS внутри (какие операции разрешены). Сквозной B2B-пример — mTLS, JWS и AsyncAPI с outbox. Диаграмма и контекст M2M — раздел mTLS ниже.
Basic — быстрый старт и узкие внутренние контуры. Bearer — стандарт для REST/OpenAPI и OAuth. mTLS — когда договор или регулятор требуют криптографическую идентичность стороны на транспорте, а не только секрет в заголовке. Конфигурация на продакшене (Nginx, gateway, ротация) — 8.05.134.
Токены (JWT) и API-ключи
В документации и на схемах архитектуры оба механизма часто попадают в один заголовок Authorization. На практике это разные классы учётных данных с разной моделью жизненного цикла и проверки.
| Токен (JWT) | API-ключ | |
|---|---|---|
| Суть | Временные, самодостаточные учётные данные: внутри — claims о субъекте, снаружи — подпись и срок exp | Долгоживущая простая строка-идентификатор приложения или интеграции |
| Аналогия | Билет в кино с номером места и временем сеанса — данные напечатаны на билете, касса сверяет подпись | Ключ от подъезда — один секрет, пока его не сменили |
| Кто идентифицируется | Пользователь (через OAuth) или сервис (Client Credentials) — claims в payload | Приложение, проект разработчика, внутренний скрипт |
| Срок действия | Автоматически истекает (exp, refresh-ротация) | Действует до ручного отзыва в портале или БД |
| Проверка на API | Подпись и claims локально (stateless), без обязательного запроса в БД на каждый вызов | Поиск ключа в хранилище (БД, Redis) — stateful lookup |
| Масштабирование | Удобно горизонтально масштабировать resource server | Каждый запрос может требовать обращения к реестру ключей |
| Сложность внедрения | Выше — нужен auth-сервер, подпись, refresh, JWKS | Ниже — сгенерировать строку и проверить в middleware |
| Типичный контекст | Пользовательские сессии, OAuth 2.0, микросервисы с единым IdP | Публичные API для разработчиков, webhooks, внутренние cron-задачи |
JWT уместен, когда нужны данные о субъекте в самом токене (роли, tenant_id, scopes) и предсказуемый автоматический отзыв по времени. API-ключ уместен, когда интеграторов немного, права задаются на уровне «этому ключу — доступ к API v2», а полноценный OAuth пока избыточен.
Структура JWT, cookie/session и безопасный login → refresh — в аутентификации и авторизации. Типичные ошибки jwt.verify — в JWT — семь строк, которые обходят авторизацию.
Поток с JWT (пользователь или OAuth)
Шаги в общем виде:
- Субъект проходит аутентификацию (пароль, соцсеть, Client Credentials для M2M).
- Auth-сервер создаёт и подписывает JWT.
- Клиент сохраняет токен и прикладывает его к каждому запросу.
- API проверяет подпись и срок без обязательного чтения сессии из БД (stateless).
Поток с API-ключом (сервис или разработчик)
Шаги в общем виде:
- Интегратор регистрирует приложение у провайдера API.
- Система генерирует ключ и сохраняет его (часто только хеш) в БД.
- Ключ передаётся разработчику один раз — в портале или по защищённому каналу.
- Приложение подставляет ключ в заголовок или query-параметр.
- API на каждый запрос сверяет ключ с реестром и проверяет квоты.
Ключ, попавший в репозиторий или лог, действует до отзыва. Храните его в секрет-хранилище или переменных окружения, ограничивайте IP и scope, ведите аудит вызовов. Утечку JWT с коротким exp проще пережить, чем компрометацию бессрочного ключа.
| Критерий | JWT | API-ключ |
|---|---|---|
| Безопасность при утечке | Выше при коротком exp и rotation refresh | Средняя — ключ живёт до отзыва |
| Контекст пользователя | Есть (sub, роли, scopes) | Только уровень приложения |
| Масштабирование API | Stateless-проверка подписи | Lookup в БД на запрос |
| Внедрение | Сложнее (auth flow, JWKS) | Проще |
Для production между сервисами чаще выбирают OAuth 2.0 Client Credentials (JWT access token) или mTLS — см. разделы ниже. API-ключи остаются на старте продукта и в B2B-интеграциях с малым числом партнёров.
API-ключи
API-ключи — простой, но ограниченный метод. Ключ передаётся в заголовке запроса (X-API-Key, Authorization: Bearer … или query-параметр — последний хуже из‑за логов и Referer) и идентифицирует вызывающую систему, а не конкретного человека. Подробное сравнение с JWT — выше.
OAuth 2.0
OAuth 2.0 Client Credentials Flow — стандартный способ авторизации машина-машина (M2M): на выходе тот же класс Bearer-токена, что и у пользовательского JWT, но выдача идёт без участия человека. Сравнение с «голым» API-ключом — в разделе про токены и ключи. Система (клиент) аутентифицируется в авторизационном сервере с помощью client_id и client_secret, получает JWT-токен и использует его для доступа к API. Токен может содержать права (scopes), ограничивающие доступ.
mTLS
mTLS (mutual TLS) — двусторонняя аутентификация на уровне транспорта. Каждая сторона предоставляет сертификат, подтверждающий её подлинность. Применяется в высокозащищённых средах (финансы, государственные системы).
Service Accounts
Service Accounts — в облачных платформах (Google Cloud, AWS IAM Roles) компоненты могут получать временные учётные данные с точно определёнными привилегиями. Это соответствует принципу наименьших привилегий и автоматическому ротированию ключей.
Интеграционная авторизация должна быть строго привязана к контексту: какая система, зачем, какие действия, на какие ресурсы. Отсутствие такой привязки приводит к избыточным правам и росту поверхности атаки.
См. также 12 советов по безопасности API и уязвимости и атаки на API.