Жизненный цикл API-токена: выпуск, хранение, использование и отзыв
API-токен нередко воспринимают как техническую деталь: пользователь проходит аутентификацию, сервер выдает строку, браузер сохраняет ее и добавляет к защищенным запросам. Однако безопасность такой схемы определяется не только криптографией. Важно учитывать весь путь токена - от момента создания до истечения срока действия, принудительного отзыва и удаления.
Даже корректно подписанный JWT можно украсть. Сильная подпись защищает содержимое от подделки, но не препятствует копированию оригинального токена. Если злоумышленник получил действующий access token, сервер часто не способен отличить его от запроса настоящего пользователя: в обоих случаях предъявляется одна и та же валидная учетная информация.
Поэтому необходимо контролировать не только алгоритм подписи, но и способ выпуска, место хранения, передачу, обновление, отзыв и мониторинг токенов.
Стадия 1. Выпуск токена
Ошибки на этапе выдачи сложно компенсировать последующими мерами защиты. Даже безопасное хранилище и шифрование канала не спасут систему, если выбран неподходящий OAuth-поток, слишком большой срок действия или слабая проверка клиента.
Для одностраничных приложений и мобильных программ используется поток Authorization Code с PKCE. Такие приложения считаются публичными: их код запускается в среде пользователя, поэтому постоянный секрет клиента нельзя считать конфиденциальным.
PKCE связывает запрос авторизации с временным секретом. Клиент создает случайный `code_verifier`, вычисляет на его основе `code_challenge` и отправляет challenge на сервер авторизации. Сам verifier остается у клиента. При обмене кода авторизации на токены приложение передает исходный verifier. Сервер проверяет, совпадает ли он с ранее зарегистрированным значением. Украденный код без verifier становится бесполезным.
Для серверных приложений допустимы более защищенные сценарии, поскольку секрет клиента хранится на сервере. При этом endpoint авторизации и endpoint выдачи токенов должны быть защищены от перебора, подмены параметров, повторного использования кодов и автоматизированных атак.
Access token рекомендуется делать короткоживущим. Чем меньше его срок действия, тем меньше окно возможностей злоумышленника при краже. Длительные сессии следует поддерживать за счет refresh token, а не путем выдачи access token на недели или месяцы.
Стадия 2. Хранение на стороне клиента
Наиболее опасное решение для чувствительных токенов - размещение их в `localStorage` или других хранилищах, доступных JavaScript. При XSS-атаке внедренный скрипт сможет прочитать значение и отправить его злоумышленнику.
Более надежный вариант для браузерных приложений - сессионная cookie с атрибутами:
- `HttpOnly` - запрещает чтение cookie из JavaScript;
- `Secure` - разрешает передачу только по HTTPS;
- `SameSite` - снижает риск межсайтовой отправки учетных данных;
- ограниченный `Path` и корректный домен - уменьшают область действия cookie.
HttpOnly не устраняет все угрозы. Cookie автоматически прикрепляется браузером к запросам, поэтому необходимо учитывать CSRF. Для защиты применяют подходящий режим `SameSite`, CSRF-токены, проверку заголовка `Origin` и дополнительные серверные ограничения.
Практичная архитектура для браузера - BFF, или backend for frontend. В этом случае браузер работает с собственным сервером приложения, а access и refresh token остаются на серверной стороне. Клиент получает только защищенную сессию в HttpOnly-cookie, а BFF выполняет запросы к API от имени пользователя.
Стадия 3. Передача и использование
Токен в заголовке `Authorization: Bearer` удобен для API, но предъявитель такого токена получает доступ без дополнительной проверки личности. Поэтому bearer-токены нужно рассматривать как временные пропуска: их нельзя передавать посторонним, сохранять в открытом виде или включать в URL.
Никогда не помещайте access token в параметры адреса. URL попадает в историю браузера, журналы прокси, аналитические системы и заголовок `Referer`. Для передачи используйте HTTPS и заголовок авторизации либо защищенную cookie.
Отдельное внимание следует уделить логированию. Токены могут случайно оказаться в логах reverse proxy, трассировках, сообщениях об ошибках, системах мониторинга и дампах запросов. Перед записью данные нужно фильтровать и маскировать. Логи должны содержать идентификатор запроса, клиента и сессии, но не исходное секретное значение.
Важно ограничивать права токена. Применяйте принцип минимальных привилегий: задавайте узкие scopes, аудиторию, срок действия и список допустимых операций. Компрометация токена с правом чтения отдельных ресурсов менее опасна, чем утечка универсального административного ключа.
Стадия 4. Ротация refresh token
Старые схемы иногда позволяли использовать один refresh token многократно. Если он утекал, злоумышленник мог поддерживать доступ до его ручного отзыва или окончания срока действия.
При ротации после каждого успешного обновления старый refresh token заменяется новым. Сервер хранит связь между токенами и помечает использованный экземпляр как недействительный. Повторное предъявление уже использованного токена считается подозрительным событием и может означать кражу.
В таком случае целесообразно отозвать всю цепочку токенов или соответствующую сессию, а пользователя попросить пройти повторную аутентификацию. Одного удаления последнего refresh token недостаточно: ранее выпущенные элементы цепочки также должны быть заблокированы.
Операция ротации должна быть атомарной. Проверка старого токена, его блокировка и выпуск нового выполняются как единая транзакция. Иначе параллельные запросы могут оба пройти проверку и получить действительные новые токены.
На клиенте следует предотвращать несколько одновременных запросов на обновление. Обычно используется единая очередь: первый запрос запускает refresh, остальные ждут его результата. После завершения все они получают новое состояние сессии. Это снижает вероятность гонок и ошибочного выхода пользователя из системы.
Стадия 5. Истечение срока действия и отзыв
Истечение срока действия - не то же самое, что отзыв. Expiration заранее определен в токене, а revocation позволяет немедленно запретить дальнейшее использование учетных данных.
Для отзыва применяют несколько моделей:
1. Серверные записи сессий. У каждого refresh token или набора токенов есть запись сессии. Удаление или блокировка записи прекращает возможность обновления.
2. Списки заблокированных токенов. Подход подходит для особо чувствительных токенов, но требует хранения и очистки большого количества значений.
3. Версия сессии. Сервер хранит счетчик или версию учетных данных. При отзыве версия увеличивается, и старые токены перестают соответствовать текущему состоянию.
4. Короткий срок access token. Даже если мгновенный отзыв невозможен, небольшое время жизни ограничивает последствия компрометации.
Фильтр Блума может использоваться как быстрый предварительный механизм проверки отозванных идентификаторов. Однако он допускает ложные срабатывания и не заменяет точное хранилище. Его разумно применять для оптимизации, а окончательное решение принимать по базе данных.
При выходе пользователя из системы необходимо отозвать серверную сессию, удалить refresh token, очистить cookie и завершить связанные устройства или сеансы, если пользователь выбрал полный выход.
Стадия 6. Мониторинг и обнаружение атак
Без мониторинга невозможно понять, используется ли украденный токен. Система должна фиксировать:
- повторное применение отозванного refresh token;
- необычные страны, сети и устройства;
- резкую смену географии;
- большое количество запросов обновления;
- всплески отказов авторизации;
- попытки обращения к недоступным scopes;
- подозрительно частую смену user-agent;
- токены необычного размера или формата.
При этом нельзя слепо доверять IP-адресу. Пользователь может сменить сеть, использовать мобильный интернет или корпоративный VPN. Географические и сетевые признаки должны участвовать в оценке риска вместе с другими сигналами.
Полезным инструментом могут стать honeytoken - специально созданные учетные данные, которые не должны использоваться в обычной работе. Любое обращение к ним является сильным индикатором утечки или разведывательной активности.
Практичная архитектура
Для современного браузерного приложения базовая схема может выглядеть так:
1. Authorization Code Flow с PKCE.
2. Короткоживущий access token.
3. Ротация refresh token после каждого обновления.
4. Хранение сессии в HttpOnly, Secure и SameSite-cookie.
5. BFF для скрытия OAuth-токенов от браузера.
6. Серверная таблица сессий и устройств.
7. Атомарная блокировка использованного refresh token.
8. Возможность отозвать отдельную сессию, все устройства или всю учетную запись.
9. HTTPS для каждого этапа передачи.
10. Централизованный аудит без записи секретных значений.
Чек-лист безопасности
Выпуск:
- выбран поток OAuth, соответствующий типу клиента;
- для публичных клиентов включен PKCE;
- access token имеет короткий срок действия;
- scopes ограничены необходимыми правами;
- endpoint выдачи защищен от перебора.
Хранение:
- токены не находятся в `localStorage`;
- cookie имеют `HttpOnly`, `Secure` и подходящий `SameSite`;
- refresh token недоступен клиентскому JavaScript;
- предусмотрена защита от CSRF.
Передача:
- используется только HTTPS;
- токены не попадают в URL;
- логи и трассировки очищаются от секретов;
- проверяются issuer, audience, срок действия и подпись.
Ротация и отзыв:
- refresh token меняется после использования;
- повторное использование вызывает блокировку;
- операции выполняются атомарно;
- доступна блокировка отдельной сессии;
- выход завершает серверную сессию.
Мониторинг:
- регистрируются события выдачи, обновления и отзыва;
- выявляются аномальные устройства и местоположения;
- контролируются размеры и формат токенов;
- настроены уведомления о подозрительных действиях.
Токен API нельзя рассматривать как обычную строку, которую достаточно подписать и передать клиенту. Это временное удостоверение доступа, для которого требуется полноценная модель управления: безопасный выпуск, ограниченное хранение, защищенная передача, ротация, отзыв и наблюдение за использованием. Чем раньше эти процессы проектируются как единая система, тем меньше ущерб от утечки и тем быстрее команда сможет обнаружить компрометацию.