API-ключи, OAuth и токены: как безопасно подключать внешние сервисы

Интеграция почти всегда требует авторизации: API-ключа, токена, пары client ID и secret или OAuth-доступа. Эти данные дают внешней системе право выполнять действия от имени сайта или компании, поэтому обращаться с ними как с обычными настройками опасно.

Утечка токена может открыть доступ к клиентской базе, заказам, платежным данным или административным операциям. Безопасность интеграции начинается ещё до первого API-запроса — с того, где и как хранится секрет.

Не размещайте секреты в публичном коде

API-ключи не должны попадать в JavaScript, HTML, репозиторий с открытым доступом или шаблон сайта. Если запрос к внешнему API требует секретного токена, выполнять его нужно на серверной стороне.

Для проекта полезно отделять конфигурацию окружения от исходного кода. Тогда ключи рабочей и тестовой систем не смешиваются, а смена токена не требует правки бизнес-логики.

Чем API-ключ отличается от OAuth

Простой API-ключ обычно идентифицирует приложение или аккаунт и передаётся в каждом запросе. OAuth позволяет выдавать ограниченный доступ от имени пользователя или организации и работать с access token и refresh token.

OAuth сложнее в реализации, зато лучше подходит для сервисов, где пользователь должен явно предоставить доступ и где разрешения можно ограничить по scope.

Давайте интеграции только необходимые права

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

Токены имеют срок жизни

Access token часто действует ограниченное время. Интеграция должна уметь корректно обновлять его через refresh token и повторять исходный запрос только после успешного обновления авторизации.

Нельзя превращать ошибку авторизации в бесконечный цикл запросов. Если refresh token отозван или учётная запись заблокирована, задача должна остановиться и сообщить администратору.

Что логировать, а что нельзя

• можно сохранять тип ошибки и HTTP-код;
• можно фиксировать идентификатор интеграции;
• нельзя писать полный access token в лог;
• нельзя сохранять пароли и секреты в текстах исключений;
• при необходимости показывайте только несколько последних символов ключа для идентификации.

Регулярная ротация ключей

У критичных интеграций полезно иметь процедуру замены токена: кто создаёт новый ключ, где он обновляется, как проверяется работа и когда старый ключ отзывается. Без такой процедуры даже плановая смена доступа превращается в риск остановить обмен.

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

Чек-лист безопасного подключения

1. Храните секреты вне публичной части сайта.
2. Разделяйте рабочие и тестовые ключи.
3. Выдавайте минимально необходимые права.
4. Проверяйте срок действия и механизм обновления токенов.
5. Не записывайте секреты в логи.
6. Продумайте ротацию и отзыв доступа.

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