Как контролировать refresh-токены AI-агентов

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

Рабочий подход не в том, чтобы научить агента лучше защищать bearer-учетные данные. Поместите их в слой действий, которым управляет процесс под контролем человека. Агент запрашивает конкретное внешнее действие, слой решает, можно ли выполнить его в рамках текущего запуска, при необходимости обновляет токен и возвращает результат. Так появляется место для одобрения, отзыва и расследования использования.

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

Refresh-токены AI-агентов меняют границу доверия

Refresh-токены AI-агентов опасны тем, что продлевают полномочия за пределами процесса агента, которому они изначально понадобились. Если агент для программирования может прочитать refresh-токен из переменной окружения, файла конфигурации, профиля браузера или ответа менеджера секретов, он сможет использовать его через любой доступный HTTP-клиент. Токен больше не связан с ограниченной задачей. Он принадлежит всему, кто получит контроль над этим процессом.

OAuth 2.0, RFC 6749, описывает refresh-токены как учетные данные для получения токенов доступа, когда текущий токен истек или стал недействительным. Спецификация делает их необязательными, но это не делает их безвредными. Провайдеры выдают такие токены, потому что повторная интерактивная авторизация при каждом обновлении доступа была бы утомительной. Именно поэтому агент без постоянного участия человека не должен владеть refresh-токеном.

Разделяйте три роли:

• Владелец аккаунта, человек или сервисная идентичность, чей аккаунт предоставил доступ.
• Инициатор действия, процесс агента, который сейчас просит вызвать API.
• Хранитель учетных данных, компонент, который хранит refresh-токен и обращается к token endpoint.

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

Я видел, как команды говорили: «агенту нужен только доступ на чтение», а затем помещали refresh-токен с широкими правами к репозиториям, почте или облаку в локальный файл .env. Токен доступа мог действовать недолго, но refresh-токен делал ошибку постоянной. Для prompt-инъекции не нужно убеждать модель украсть пароль. Достаточно убедить ее использовать еще действующее разрешение для запроса, который выглядит правдоподобно в текущем контексте.

Граница должна проходить до того, как учетные данные попадут в процесс агента. Агент не получает ни значение токена, ни фиктивную замену, которую можно обменять где-то еще. Он получает интерфейс операций: получить эту задачу, создать этот черновик, прочитать статус развертывания, открыть SSH-сеанс к этому одобренному хосту. Детали протокола для каждой операции остаются внутри слоя действий.

Владельцем разрешения должен быть человек, а не только тот, кто одобрил запрос

Человека, который может одобрить обновление токена, нужно назначить до создания OAuth-подключения. Правило «разрешить может любой разработчик» перестает работать, когда владелец аккаунта увольняется, общим почтовым ящиком начинает пользоваться другой человек или агент подключает сервис от имени другого пользователя.

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

Разделяйте четыре решения, которые часто сводятся к одному нажатию в браузере:

1. Кто может создать исходное разрешение.
2. Какой слой действий может хранить полученный refresh-токен.
3. Какие сеансы агентов могут запрашивать действия в рамках этого разрешения.
4. Кто может отозвать разрешение или одобрить новое подключение.

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

Практическая запись о разрешении должна содержать не только email аккаунта у провайдера. Храните локальную запись с непрозрачным ID разрешения, названием провайдера, ссылкой на аккаунт, набором областей доступа, владельцем, резервным сотрудником для отзыва, датой подключения и действиями, которые разрешено запрашивать. Не копируйте refresh-токен в эту запись. Она объясняет, для чего нужен токен, но не должна превращаться во второе хранилище секретов.

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

Не разрешайте агенту самостоятельно запускать новый OAuth-поток через браузер. Он может открыть настоящую страницу провайдера, но также способен направить человека к более широкому аккаунту, набору областей доступа или другому тенанту. Подключение это административное действие. Человек должен начать его из слоя действий и проверить аккаунт и список областей доступа до одобрения.

Слой действий должен обновлять токен только для одобренной операции

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

Путь запроса может оставаться простым:

1. Сеанс агента запрашивает именованную операцию и передает обычные параметры действия.
2. Слой действий находит разрешение, связанное с этой операцией, и проверяет, может ли сеанс его использовать.
3. Если сохраненного токена доступа нет или он скоро истечет, слой отправляет refresh-токен на token endpoint провайдера.
4. Слой вызывает целевой API с токеном доступа и возвращает агенту отфильтрованный результат.
5. Слой записывает действие и событие обновления, но не сохраняет материал учетных данных.

Агент никогда не выбирает token endpoint, идентификатор клиента, callback URL или строку областей доступа. Эти значения принадлежат описанию подключения, которое одобрил человек. Если позволить агенту передавать их самостоятельно, шлюз превратится в открытый ретранслятор токенов.

Представим, что агенту поручили опубликовать заметку о релизе в системе управления проектами. Он просит слой действий создать одну задачу в названном проекте. Слой видит, что для операции нужно разрешение трекера с доступом к этому проекту, проверяет сеанс, при необходимости обновляет токен и публикует заметку. Агент может получить ID новой задачи и ссылку, которую вернул провайдер, но не bearer-токен, использованный для ее создания.

Теперь изменим запрос. Вредоносная инструкция из репозитория говорит агенту «проверить доступ», перечислив все проекты организации и создав тестовую задачу в каждом. Если у агента есть refresh-токен, инструкция может превратиться в прямую серию вызовов API. Если у него есть только интерфейс именованных операций, слой может отклонить запросы за пределами одобренного проекта или потребовать дополнительное одобрение человека.

Для этого не нужен сложный язык политик. Нужен небольшой и понятный набор решений: какой процесс отправляет запрос, какое разрешение он может использовать и требуется ли одобрение человека. Большее число вариантов само по себе не делает систему безопаснее. Часто оператору становится невозможно понять, какое правило победило.

Sallyport соблюдает это разделение: API-учетные данные хранятся в зашифрованном хранилище, а HTTP- и SSH-действия выполняются через MCP-подключение, без возврата учетных данных агенту.

Тип разрешения определяет, что можно безопасно автоматизировать

Используйте authorization code flow с PKCE для подключения аккаунта человека в настольном или локальном приложении. Человек входит к провайдеру, проверяет запрос согласия и возвращается в локальное приложение через зарегистрированный путь перенаправления. PKCE связывает ответ авторизации с клиентом, который начал поток, и снижает ценность перехваченного кода авторизации.

RFC 9700, OAuth 2.0 Security Best Current Practice, требует от публичных клиентов использовать PKCE. В документе также сказано, что refresh-токены публичных клиентов должны использовать привязку к отправителю или ротацию refresh-токенов. Это особенно важно для интеграций с агентами, потому что локальное приложение часто является публичным клиентом. Секрет клиента внутри настольного приложения не превращает его в конфиденциальный клиент. Любой, у кого есть приложение, может извлечь этот секрет.

Выбирайте поток в соответствии с подключаемой идентичностью:

• Используйте authorization code flow с PKCE для аккаунта человека у провайдера.
• Используйте client credentials для сервисной идентичности, если провайдер поддерживает этот режим и делегирование аккаунта человека не нужно.
• Используйте модель установки или приложения самого провайдера, если она дает более узкий доступ к проекту или организации.
• Используйте device authorization только тогда, когда этого требуют провайдер и рабочая среда, и показывайте человеку, какую именно идентичность и набор областей доступа он одобряет.

Client credentials обычно не создают refresh-токены, потому что клиент может снова запросить токен доступа, заново аутентифицировав себя. Для автономной задачи это может быть безопаснее, если сервисная идентичность имеет узкие права, а материал аутентификации клиента остается внутри слоя действий. Не используйте client credentials как оправдание для передачи агенту с широкими правами секрета клиента.

Особого внимания требует автономный доступ. Некоторым провайдерам OpenID Connect нужна область offline_access, прежде чем они выдадут refresh-токен. Запрашивайте ее только тогда, когда действие действительно должно выполняться после завершения интерактивного сеанса. Если человек присутствует при каждой операции, может лучше подойти короткоживущий токен доступа с новой авторизацией. Команды часто запрашивают автономный доступ по умолчанию, чтобы не заниматься истечением токенов. Так неудобство заменяется постоянной учетной записью.

Полностью избегайте resource owner password credentials. RFC 9700 объявляет этот тип разрешения устаревшим, потому что он передает пароль пользователя клиенту. Слой действий не делает такой подход приемлемым. Он лишь добавляет еще одно место, где можно потерять пароль.

Ротация полезна только при правильной обработке замены

Ротация refresh-токенов уменьшает ущерб от скопированного токена: после успешного обновления каждый токен заменяет предыдущий. Провайдер может обнаружить повторное использование старого токена и аннулировать все семейство разрешений. Это помогает выявлять кражу, но из-за неаккуратной логики обновления можно заблокировать и собственную легитимную интеграцию.

Самая распространенная проблема, это гонка. Два сеанса агента почти одновременно получают запрос на токен доступа. Оба читают один и тот же старый refresh-токен. Первый успешно обновляет его и получает новое значение. Второй через мгновение отправляет старое. В зависимости от провайдера запрос завершится ошибкой или запустит обнаружение повторного использования, которое отзовет все семейство, включая новый токен.

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

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

1. Отправьте старый refresh-токен на token endpoint по TLS.
2. Проверьте ответ и свяжите его с ожидаемыми провайдером и разрешением.
3. Одним надежным обновлением запишите новый refresh-токен и метаданные в зашифрованное хранилище.
4. Пометьте старый токен как непригодный в локальном состоянии.
5. Передайте ожидающим вызовам новый токен доступа или новый путь запроса.

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

Некоторые провайдеры выдают новый refresh-токен только иногда. Другие возвращают тот же токен. Код должен поддерживать оба варианта и не исходить из того, что всегда будет только один из них. Храните предыдущее значение лишь до подтверждения ответа провайдера и успешной надежной записи. Никогда не записывайте ни одно из этих значений в журналы при отладке. Удивительно много утечек начинается с временной отладочной строки, которая пережила релиз.

Токены, привязанные к отправителю, могут снизить риск повторного использования, связывая токен с криптографическим ключом, который хранится у клиента. Один из подходов, DPoP, описан в RFC 9449. Он не отменяет необходимость контроля хранения. Если агент может использовать и refresh-токен, и закрытый ключ подписи, у него все равно остаются постоянные полномочия. Храните оба материала за слоем действий и проверьте поведение провайдера, прежде чем полагаться на такую привязку.

Для отзыва нужны назначенный оператор и проверенный путь

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

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

RFC 7009 определяет запрос на отзыв OAuth-токена. Провайдер публикует собственный endpoint, но форма запроса обычно выглядит так:

POST /revoke HTTP/1.1
Host: authorization.example
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <client authentication>

token=<refresh-token>&token_type_hint=refresh_token

RFC 7009 требует от серверов возвращать успешный ответ, даже если переданный токен уже недействителен или неизвестен. Это не позволяет злоумышленнику использовать endpoint как способ проверить действительность токена. Поэтому оператор не может считать один HTTP-успех доказательством того, что разрешение действительно давало доступ. Зафиксируйте отправку запроса, удалите локальные учетные данные, а затем проверьте результат безвредным вызовом провайдера или его аудитом, если такая возможность есть.

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

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

Разделяйте отзыв у провайдера и локальное отключение. Локальное отключение не дает вашему слою действий использовать разрешение. Отзыв у провайдера сообщает ему, что разрешение тоже нужно отклонять. Во время инцидента выполняйте оба шага именно в таком порядке: сначала перекройте собственный путь выполнения, затем отправьте запрос провайдеру. Первый шаг находится под вашим контролем и не должен зависеть от внешнего сетевого вызова.

Аудит должен объяснять намерение, а не только трафик

Список HTTP-вызовов не показывает, было ли обновление правомерным. Нужна запись, связывающая решение человека, сеанс запрашивающего агента, ссылку на разрешение и итоговое внешнее действие.

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

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

Важно различать запись действия и запись учетных данных. Запись действия говорит, что конкретный сеанс агента запросил статус развертывания в названной среде и слой действий разрешил операцию. Запись учетных данных показывает, какое разрешение поддержало этот запрос и кто им владеет. Свяжите записи непрозрачным ID разрешения, но не давайте каждому оператору, который видит историю действий, возможность просматривать детали подключения аккаунтов.

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

Sallyport формирует журналы Sessions и Activity из зашифрованного аудита с цепочкой хешей, а команда sp audit verify проверяет эту цепочку без подключения к хранилищу и без ключа хранилища.

Проводите проверку с периодичностью, соответствующей силе разрешения. Разрешение личного трекера задач можно пересматривать время от времени. Разрешение, позволяющее менять рабочую инфраструктуру, нужно проверять после каждого нового подключения, изменения областей доступа и любого неожиданного поведения агента. Слой действий должен формировать записи, понятные владельцу: «Какой агент использовал мой аккаунт, для чего и с чьего одобрения?»

Профили браузеров и универсальные брокеры токенов создают незаметные обходы

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

Универсальный брокер токенов создает ту же проблему, если принимает от вызывающей стороны произвольные параметры token endpoint. Команды часто строят один API getToken(scope) и чувствуют себя безопаснее, потому что токен больше не лежит в процессе агента. Но брокер все равно становится автоматом выдачи токенов, если любой сеанс может запросить любой подключенный аккаунт или произвольную область доступа.

Пусть вызывающая сторона запрашивает операцию, а не токен. «Создать заметку о релизе в проекте A» имеет владельца, назначение и требование к области доступа, которые можно проверить. «Дай мне токен для tracker.write» оставляет вызывающей стороне слишком много полномочий.

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

Не привыкайте также использовать один refresh-токен для разработки, тестовой и рабочей среды. Раздельные разрешения упрощают отзыв и делают аудит понятнее. Агент тестовой среды не должен сохранять путь в рабочую среду только потому, что обе используют одного провайдера идентичности.

Начните с таблицы владельцев и одной тренировки отзыва

Первым полезным результатом должна стать инвентаризация разрешений, а не код. Создайте отдельную строку для каждого refresh-токена, который агенты могут использовать. Укажите провайдера, ссылку на аккаунт, ID разрешения, области доступа, расположение слоя действий, владельца аккаунта, резервного сотрудника для отзыва, способ создания, последнее подтвержденное использование и локальную процедуру отключения. Если какой-то столбец заполнить нельзя, вы пока не контролируете это разрешение.

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

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

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