Короткий ответ: OAuth для ИИ‑агентов — это делегированный пользовательский доступ с жёсткой изоляцией, а не прокидывание сырых токенов в промпты. Боевые агенты запрашивают согласие пользователя, получают строго ограниченные токены и выполняют действия через брокер учётных данных, недоступный модели. Мы ротируем и сужаем токены, привязываем их к тенантам и инструментам и логируем каждое использование для аудита. Эти паттерны закрывают разрыв между хайпом и продакшеном, позволяя агентам работать в реальных системах без утечек секретов и чрезмерных прав.

Ключевые выводы

  • OAuth для ИИ‑агентов — это делегированная авторизация плюс изоляция: LLM планирует; брокер хранит токены; инструменты исполняются на сервере.
  • Используйте Authorization Code с PKCE (или Device Authorization) для согласия пользователя, затем сужайте доступ через обмен токенов под каждый инструмент и задачу.
  • Никогда не показывайте токены модели; передавайте непрозрачные дескрипторы и обеспечивайте принцип наименьших привилегий на границе брокера и инструмента.
  • Ротируйте refresh‑токены, привязывайте токены к тенанту и аудитории (audience) и отказывайте по умолчанию (fail closed) с понятной пользователю ремедиацией.
  • Аудитируйте кто, что, когда, с каким scope, к какому ресурсу и с какой целью — так безопасность доверит релиз в прод.

Что такое OAuth для ИИ‑агентов?

OAuth для ИИ‑агентов — это делегированная авторизация, позволяющая агенту действовать от имени пользователя без знания и хранения пароля. Пользователь даёт согласие на конкретные scope, сервер авторизации выдаёт токены, а агент использует их для вызова инструментов, которые работают с данными пользователя.

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

Четыре роли делают это возможным:

  • Пользователь: даёт согласие на определённые scope (например, читать календарь, отправлять почту).
  • Сервер авторизации: выдаёт коды авторизации, access‑ и refresh‑токены.
  • Рантайм агента: планирует и оркестрирует задачи; никогда не читает секреты в явном виде.
  • Брокер учётных данных и инструменты: обменивают или сужают токены и выполняют серверные API‑вызовы.

В демо команды часто вставляют долгоживущие токены в промпты. В продакшене мы прячем учётные данные за брокером, используем короткоживущие access‑токены с refresh и привязываем токены к нужной аудитории и тенанту.

Когда агенту использовать сервисные аккаунты, а когда делегированную авторизацию?

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

Выбирайте сервисные аккаунты, когда

  • Действие направлено на системные данные (например, ночная загрузка в хранилище).
  • Аккаунт можно ограничить узким датасетом и окружением.
  • Не нужно представлять конкретного конечного пользователя в целевой системе.

Выбирайте делегированную авторизацию, когда

  • Действие читает или изменяет пользовательские ресурсы (например, почтовый ящик пользователя или его CRM‑воронку).
  • Целевая система применяет поминутные/пользовательские квоты, политики или утверждения.
  • Аудиторам нужна цепочка, связывающая человека, согласие, scope и действия.

Многие начинают с общего сервисного аккаунта и получают шумные побочные эффекты и кросс‑тенантное раскрытие данных. Когда агент заходит в пользовательское пространство, делегированная авторизация с per‑user scope и аудитом — безопасный дефолт.

Как спроектировать OAuth‑поток, с которым агенты работают безопасно?

Самый безопасный паттерн — дать пользователю понятный экран согласия и не подпускать модель к учётным данным. Используйте Authorization Code с PKCE для веба и мобайла, а Device Authorization — для голоса, CLI или киосков.

  1. Инициация согласия: перенаправьте пользователя на страницу провайдера с явными scope и строкой цели.
  2. Обмен кода на сервере: обменяйте код авторизации на токены в бэкенде; никогда не пропускайте коды через модель.
  3. Хранение в брокере: держите токены в брокере учётных данных; шифруйте на диске, сегментируйте по тенанту и провайдеру, тегируйте аудитории, инструменты и политики.
  4. Выдача непрозрачных дескрипторов: верните рантайму агента дескриптор (например, cred_abc123); модель видит только его.
  5. Сужение под задачу: используйте обмен токенов или тонкие scope, чтобы чеканить короткоживущий токен под конкретный инструмент и действие.
  6. Серверное исполнение: сервис инструмента делает API‑вызов и возвращает агенту редактированный результат.
  7. Логирование решения: запишите пользователя, дескриптор, scope, идентификаторы ресурсов и исход — для аудита.

Безголовые агенты всё равно требуют человеческого шага. Device Authorization даёт URL и код, которые пользователь вводит на доверенном устройстве. После согласия брокер хранит токены; агент продолжает работу с непрозрачным дескриптором, привязанным к этому пользователю и инструменту.

OAuth для ИИ‑агентов в мульти‑тенантных системах

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

  • Сегментируйте по тенанту: разносите хранилища и ключи шифрования по тенанту и провайдеру.
  • Привязывайте к аудитории: указывайте audience целевого API в запросах токена и валидируйте на каждом вызове.
  • Используйте обмен токенов: меняйте широкий refresh‑токен на короткоживущий, суженный под конкретный инструмент и задачу.
  • Тегируйте дескрипторы: кодируйте тенант, провайдера и политики в метаданных; никогда не выводите их из свободного текста промптов.
  • Ограничьте разветвление (fan‑out): не переиспользуйте один токен в нескольких инструментах; чеканьте токены на каждый инструмент, снижая риск латерального перемещения.

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

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

Как не допустить попадания токенов в руки модели?

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

  • Непрозрачные дескрипторы: дайте модели дескриптор; токен храните на сервере.
  • Серверные инструменты: реализуйте инструменты в бэкенде; принимайте дескриптор, проверяйте политики и берите токен из брокера.
  • Жёсткие схемы: задавайте схемы инструментов со структурированными полями для ID дескриптора, а не свободные строки.
  • Редакция у источника: вычищайте токены из логов, трейсинга и ошибок; тестируйте редактор на враждебных кейсах.
  • Без путей эхо: блокируйте отражение заголовков, сырых ответов или тел ошибок, где могут быть секреты.

Изоляция — это продовая мера контроля, а не рекомендация. Непрозрачные дескрипторы плюс серверное исполнение резко снижают шансы на prompt‑injection и случайные утечки.

Как агентам обрабатывать refresh, ротацию и отзыв?

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

  • Refresh на лету: перехватывайте 401/invalid_token и делайте обновление только в брокере; повторяйте вызов инструмента с ключами идемпотентности.
  • Плановая ротация: ротируйте refresh‑токены по расписанию и после рисковых событий; привязывайте их к клиенту брокера и тенанту.
  • Fail closed: если refresh не удался, остановите прогон и покажите шаг ремедиации с повторным согласием.
  • Быстрый отзыв: подключите отзыв у провайдера и админский kill‑switch к брокеру; чистите производные access‑токены и инвалидируйте дескрипторы.

Это дополняет устойчивое выполнение. Храните промежуточное состояние, чтобы refresh или повторное согласие не теряли прогресс, и используйте идемпотентность в инструментах, чтобы избежать дублей после ретраев.

Как обеспечить принцип наименьших привилегий для действий инструментов?

Наименьшие привилегии для агентов — это ограничение и токенов, и самих действий. Токены задают, какие API доступны; политики действий определяют, что инструмент сейчас может с ними делать.

  • Наборы scope: сопоставьте задачи с минимально необходимыми scope; предпочитайте read vs write и пообъектные scope, если доступны.
  • Политики действий: определяйте allow‑листы глаголов (например, create_draft_email vs send_email).
  • Контекстные проверки: требуйте одобрение человека для чувствительных/необратимых действий или когда scope шире, чем допускает политика.
  • Повышение прав just‑in‑time: запрашивайте дополнительные scope только при необходимости; фиксируйте причину в аудите.

Оценка политик должна выполняться в брокере или сервисе инструмента, а не в модели. При отказе политики возвращайте структурированный запрет с недостающими scope и путём эскалации, а не общий error.

Шире о политиках — в гайде AI Agent Access Control: RBAC, политики и аудит.

Что и как аудировать без излишней огласки ПДн?

Аудит должен доказывать, что нужный пользователь дал согласие на нужные scope для нужного действия в нужное время — и при этом не раскрывать чувствительное содержимое.

  • Фиксируйте кто и когда: тенант, пользователь, инструмент, дескриптор, метка времени и инициатор (ID прогона агента).
  • Фиксируйте что и зачем: набор scope, глагол действия, идентификаторы ресурсов и строку заявленной цели.
  • Минимизируйте контент: храните ссылки или хэши вместо полных payload; редактируйте тела сообщений.
  • Связывайте утверждения: прикладывайте человеческие аппрувы или оверрайды политик к прогону и действию.
  • Анти‑подмена: подписывайте записи аудита или храните их в журнале только для добавления.

Безопасности нужна трассируемость без утечки данных. Редактируйте содержимое при захвате и по умолчанию держите сырые payload вне логов и трейсинга. Про практики комплаенса — статья data governance ИИ‑агентов, ПДн и аудиторские следы.

Типичные ловушки OAuth в стеке агентов (и как их исправить)

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

  • Утечки токенов через промпты или логи: не показывайте токены модели; используйте непрозрачные дескрипторы и агрессивную редакцию.
  • Широкие, долгоживущие токены: предпочитайте короткоживущие access‑токены; ротируйте refresh; сужайте через обмен токенов.
  • Один сервисный аккаунт на все тенанты: делайте учётные данные и секции хранения per‑тенант; привязывайте токены к audience и тенанту.
  • Пропуск PKCE или device flow: используйте Authorization Code с PKCE для браузера/мобайла; Device Authorization — для headless‑поверхностей.
  • Нет идемпотентности при ретраях инструментов: добавляйте ключи идемпотентности, чтобы refresh и ретраи не дублировали сайд‑эффекты.
  • Возврат сырых ошибок провайдера модели: переводите ошибки в структурированные, осознанные политиками отказы; не позволяйте эхо заголовков.
  • Нет пути обновления согласия: дайте понятный re‑consent‑флоу при смене scope или отзыве токенов.
  • Логирование полных тел запросов/ответов: логируйте структурные метаданные и ссылки; по умолчанию не пишите чувствительные payload.
  • Нет kill‑switch: добавьте тенант‑ и глобальные рубильники, мгновенно инвалидирующие дескрипторы и производные токены.
  • Неограниченный fan‑out одним токеном: чеканьте токены per‑инструмент и per‑действие, ограничивая латеральное движение и упрощая аудит.

Как Moai Team подходит к этому

Мы строим стеки агентов, где планирование отделено от разрешений. Модель решает; брокер авторизует; инструменты действуют; аудит это доказывает. Такая изоляция сужает радиус поражения и делает авторизацию проверяемой.

  • Брокер учётных данных: храним токены по тенантам и провайдерам с конвертным шифрованием, ротируем refresh‑токены и выдаём рантайму только непрозрачные дескрипторы.
  • Сужённое исполнение: предпочитаем обмен токенов и короткоживущие per‑инструмент токены, привязанные к audience и политикам действий.
  • Наименьшие привилегии по умолчанию: маппим задачи на scope и глаголы, требуем одобрение человека для рисковых действий и логируем строки цели.
  • Устойчивые, идемпотентные прогоны: сохраняем состояние агента между шагами согласия и защищаем сайд‑эффекты ключами идемпотентности.
  • Доказуемые контроли: фиксируем кто, что, когда, scope, ресурс и approvals в журнале только для добавления, доступном для ревью безопасниками.

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

Частые вопросы

Нужен ли ИИ‑агентам OAuth или достаточно API‑ключей?

Используйте OAuth для действий и данных, привязанных к пользователю: он даёт согласие, scope и отзыв на уровне пользователя. API‑ключи подходят для апп‑уровня и не пользовательских данных при жёстком скоупинге и изоляции. Часто применяют смесь: OAuth для пользовательского пространства, ключи — для внутренних сервисов. Если сомневаетесь, выбирайте делегированную авторизацию для всего, что трогает пользовательские ресурсы.

Какой OAuth‑поток лучше всего для ИИ‑агентов?

Authorization Code с PKCE — дефолт для браузера и мобайла: он снижает риск перехвата и держит секреты на сервере. Device Authorization подходит голосовым, CLI‑ и киоск‑агентам без редиректов. Оба потока заканчиваются в брокере учётных данных, недоступном модели. Избегайте implicit‑потоков и никогда не кладите коды/токены в промпты.

Как предотвратить утечки токенов через модель?

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

Можем ли мы сужать доступ под инструмент через обмен токенов?

Да. Используйте обмен токенов, чтобы менять широкий долгоживущий credential на короткоживущий access‑токен только с теми scope, что нужны конкретному инструменту. Привязывайте обмененный токен к нужной аудитории и тенанту. Это сокращает радиус поражения и улучшает аудит — каждый вызов опирается на минимальный набор scope.

Что нужно аудитировать для безопасности и комплаенса?

Аудитируйте пользователя, тенанта, инструмент, дескриптор, scope, глагол действия, идентификаторы ресурсов, метку времени и заявленную цель. Привязывайте человеческие одобрения и оверрайды политик к прогону агента. По умолчанию не логируйте payload и храните ссылки или хэши. Подписанные или append‑only записи дают доказательства отсутствия подмен.

Как обрабатывать изменения согласия и отзыв, не ломая прогоны?

Отказывайте по умолчанию при отзыве токенов или сужении scope и покажите структурированный шаг ремедиации с повторным согласием. Сохраняйте состояние агента, чтобы он продолжил после согласия, и используйте идемпотентность на сайд‑эффектных вызовах, чтобы избежать дублей. Предусмотрите тенант‑ и глобальные kill‑switch, мгновенно инвалидирующие дескрипторы. Чёткие ранбуки ускоряют восстановление при инцидентах.

Нужна команда, которая с первого дня делает делегированный доступ правильно? Поговорите с Moai Team о запуске агентов, которые безопасно работают с OAuth и доходят до продакшена. Свяжитесь с нами.