← Назад к блогу

Токены API аналитики — это учётные данные, а не идентификаторы

Токен API открывает доступ к данным. Относитесь к нему как к секрету с жизненным циклом: показывайте один раз, храните проверочное значение, ограничивайте права и поддерживайте отзыв.

Токен API — не метка пользователя или сайта. Это учётные данные: получив действующий токен, можно действовать от имени его владельца. Если считать его обычным идентификатором, он попадёт в журналы, URL, снимки экрана поддержки и постоянные конфигурации, которые никто не решается отозвать.

Рекомендации IETF по безопасности OAuth 2.0, опубликованные в январе 2025 года, обновляют модель угроз и руководства для развёртываний OAuth. Персональный API-токен не обязательно является токеном доступа OAuth, но основной инженерный принцип тот же: учётные данные, действующие в силу владения ими, нужно защищать при передаче, ограничивать целевым сервисом и необходимыми полномочиями.

Показывайте секрет только один раз

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

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

Передавайте учётные данные правильным способом

Для HTTP API принимайте токены в заголовке Authorization по TLS. RFC 6750 определяет bearer-токен как средство, которым может воспользоваться любой обладатель, и предупреждает, что раскрытие при хранении или передаче ведёт к злоупотреблениям. Стандарт также не рекомендует помещать bearer-учётные данные в URI-параметры, поскольку URL часто записываются в журналы. Отклоняйте токены в строках запроса и телах запросов, если только протокол не требует другого способа передачи и для него не задокументирована модель угроз.

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

Ограничивайте права, задавайте срок действия и отзыв

Токен должен предоставлять минимальный полезный набор полномочий. Если продукт это поддерживает, разрешите ограничить его выбранными сайтами и чтением либо отдельными операциями. Скрипту, которому нужно получить один отчёт, не следует молча выдавать права на запись для всей учётной записи. Рекомендации OAuth по безопасности рассматривают ограничение полномочий и аудитории токенов; это полезный ориентир и для API со своим непрозрачным форматом.

Сделайте срок действия и отзыв основными средствами управления. Короткий срок сокращает период полезности украденных данных; отзыв нужен при инцидентах и изменениях команды или интеграции. Если для ротации требуется перекрытие сроков, задайте его предел и покажите, какой токен активен. Отзыв должен применяться на границе API, а не только скрывать токен в dashboard.

В программном API Monoid пользовательские токены mnd_live_… непрозрачны, выдаются в открытом виде один раз и хранятся как SHA-256-хеши с необязательным сроком действия и логическим отзывом. Это защищает исходное значение при чтении базы, но не обезвреживает действующий раскрытый токен. Не помещайте его в систему контроля версий, вывод CI, браузерные bundle или общую историю терминала; при подозрении на утечку выпустите замену и отзовите старый токен.

Сделайте жизненный цикл проверяемым

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

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

Источники

Comments

Loading comments…