Проще говоря, scope отвечает на вопрос: что именно этому приложению разрешено делать. Для AI-агентов это критично, потому что агент может вызывать инструменты автоматически. Если агенту нужен только статус встречи, ему не нужны права удалять события. Если он готовит черновик письма, ему не обязательно давать право отправлять письмо без approval.
Хорошая практика - минимальные scopes. Сначала выдать только read-only доступ, проверить качество сценария, добавить запись только для узкого действия и отдельно защитить опасные операции: отправку писем, изменение CRM, удаление файлов, публикацию сообщений, изменение календаря и финансовые действия.
OAuth scopes не заменяют бизнес-правила. Даже если у токена есть право `Mail.Send`, агент не должен отправлять письмо сам, если процесс требует подтверждение человека. Scopes ограничивают технические возможности приложения, а policy gate и approval ограничивают поведение агента внутри продукта.
Важно хранить не только сам токен, но и список выданных scopes, владельца подключения, дату выдачи, срок действия, refresh token status, источник согласия и audit log. Тогда команда понимает, почему агент имел доступ к данным и как быстро отозвать лишнее разрешение.
Главный риск - слишком широкие scopes. Например, вместо доступа к одной папке Drive приложение получает весь диск, вместо чтения календаря получает право менять события, вместо создания черновиков Gmail получает право отправлять письма. Для AI-агента это резко увеличивает ущерб от ошибки, prompt injection или украденного токена.
Примеры
- Почтовый агент получает `gmail.readonly` для чтения входящих и `gmail.compose` для черновиков, но не получает `gmail.send` до отдельного approval.
- Агент для Google Drive индексирует только выбранную папку и работает с read-only доступом, а не со всем диском пользователя.
- Slack-бот получает scopes для чтения упоминаний и ответа в треде, но не получает доступ ко всем приватным каналам workspace.
- CRM-агент может читать сделки и создавать заметки, но изменение стадии сделки проходит через отдельный tool и подтверждение менеджера.
- Календарный агент сначала получает free/busy доступ, а право создавать встречи добавляется только после тестов и логирования.
Где используется
- безопасное подключение AI-агента к Gmail и Outlook
- ограничение доступа к Google Drive и Docs
- подключение Slack или Teams бота
- интеграция агента с CRM через OAuth
- разделение read-only и write-действий
- защита отправки писем и сообщений через approval
- снижение ущерба от prompt injection
- аудит выданных доступов и токенов
- отзыв лишних прав после MVP
- проверка least privilege перед production-запуском
Связанные термины
Частые вопросы
OAuth scopes - это то же самое, что роли пользователя?
Нет. Роль пользователя описывает права внутри сервиса, а OAuth scope описывает, какие действия разрешены подключенному приложению. Обычно нужны оба слоя: роль в системе и минимальные scopes у приложения.
Почему AI-агенту нельзя сразу давать широкие scopes?
Потому что агент может ошибиться, неправильно понять запрос, попасть под prompt injection или вызвать не тот tool. Широкие scopes увеличивают ущерб: письмо может уйти клиенту, файл удалиться, сделка измениться или данные утечь.
Какие scopes выбирать для MVP?
Начинайте с read-only и самого узкого сценария. Например, читать только календарную занятость, создавать только черновики писем, индексировать только одну папку Drive, читать только нужные CRM-объекты.
Нужен ли approval, если scope уже ограничен?
Да, для рискованных действий. Scope ограничивает техническое право, но не понимает бизнес-контекст. Отправка письма, изменение сделки, удаление файла и финансовое действие должны проходить через policy gate или человека.
Что хранить в журнале OAuth-доступов?
Полезно хранить service, account_id, granted_scopes, owner, consent timestamp, token status, refresh status, last used, purpose, approved_by и audit log событий. Секреты и refresh tokens в открытые логи писать нельзя.
