Авторизация с делегированием доступа к данным в домене

Mail Admin Quarantine API предназначен для автоматизации на стороне сервера, например для конвейеров безопасности и интеграции с SIEM или SOAR. Эти автоматизации проходят аутентификацию с помощью сервисного аккаунта Google Cloud, который использует делегирование доступа к данным в домене, чтобы действовать от имени администратора Google Workspace, у которого есть необходимые права администратора.

На этой странице рассказывается, какие области действия OAuth 2.0 требуются для API, как настроить сервисный аккаунт и как получить токен доступа.

Области действия OAuth 2.0

Admin Quarantine API использует следующие области действия OAuth 2.0:

Область действия Значение
https://www.googleapis.com/auth/gmail.admin.quarantine Просмотр сообщений, помещенных в карантин, и управление ими. Требуется для разрешения или запрета доставки сообщений по отдельности или пакетами.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Просмотр сообщений в карантине. Достаточно для просмотра, поиска и получения сообщений, просмотра и получения карантинов, а также получения статуса пакетных операций.

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

Метод gmail.admin.quarantine gmail.admin.quarantine.readonly
customers.quarantinedMessages.list ✓ ✓
customers.quarantinedMessages.search ✓ ✓
customers.quarantinedMessages.get ✓ ✓
customers.quarantines.list ✓ ✓
customers.quarantines.get ✓ ✓
customers.operations.get ✓ ✓
customers.quarantinedMessages.release ✓
customers.quarantinedMessages.deny ✓
customers.quarantinedMessages.batchRelease ✓
customers.quarantinedMessages.batchDeny ✓

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

Если в запросе используется токен, который не включает принятую область действия, API возвращает ошибку 403 с причиной ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Как создать сервисный аккаунт

  1. В консоли Google Cloud выберите IAM & Admin (IAM и администрирование) > Service Accounts (Сервисные аккаунты) и выберите облачный проект Google Cloud, в котором вы включили API.
  2. Нажмите Создать сервисный аккаунт, введите название, например quarantine-api-service-account, и нажмите Создать и продолжить. Предоставлять сервисному аккаунту роли IAM не нужно. Нажмите Готово.
  3. Откройте сервисный аккаунт и на вкладке Details (Сведения) скопируйте OAuth 2 Client ID (Идентификатор клиента OAuth 2). Это 21-значное число, например 109876543210987654321. Он понадобится вам в следующем разделе.
  4. На вкладке Keys (Ключи) нажмите Add key (Добавить ключ) > Create new key (Создать ключ), выберите JSON и нажмите Create (Создать). Храните скачанный файл ключа JSON в безопасном месте.

Подробнее о том, как создать учетные данные для сервисного аккаунта…

Как разрешить делегирование доступа к данным в домене

Авторизуйте сервисный аккаунт для доступа к областям Admin Quarantine API в аккаунте Google Workspace:

  1. Войдите в консоль администратора Google как суперадминистратор.
  2. Выберите Безопасность > Управление доступом и данными > Управление API.
  3. В разделе Делегирование доступа к данным в домене нажмите Настроить делегирование доступа к данным в домене.
  4. Нажмите Добавить.
  5. В поле Идентификатор клиента введите идентификатор клиента OAuth 2.0 сервисного аккаунта. Не указывайте адрес электронной почты сервисного аккаунта.

  6. В поле Области действия OAuth введите одну из следующих областей действия:

    • Для доступа на чтение и запись: https://www.googleapis.com/auth/gmail.admin.quarantine.
    • Для доступа только для чтения: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly.

  7. Нажмите Подтвердить.

Подробнее о том, как управлять доступом к API, используя делегирование доступа к данным в домене…

Получите токен доступа

Чтобы вызвать API, сервисный аккаунт выдает себя за администратора, устанавливая утверждение subject (sub) запроса токена на адрес электронной почты администратора. У администратора должны быть необходимые права администратора.

В примере ниже показано, как получить токен доступа с помощью библиотеки google-auth на Python.

from google.oauth2 import service_account
import google.auth.transport.requests

SERVICE_ACCOUNT_FILE = 'service_account.json'
# An administrator with the Access Admin Quarantine privilege.
ADMIN_EMAIL = 'admin@example.com'
SCOPES = ['https://www.googleapis.com/auth/gmail.admin.quarantine']

credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE,
    scopes=SCOPES,
    subject=ADMIN_EMAIL,
)
credentials.refresh(google.auth.transport.requests.Request())
access_token = credentials.token

Отправьте токен в заголовке Authorization каждого запроса:

Authorization: Bearer ACCESS_TOKEN

Срок действия токенов доступа истекает через час. Обновляйте учетные данные перед каждым пакетом запросов, а не кешируйте токены на длительное время.

Устранение ошибок авторизации

Статус HTTP Причина Разрешение
401 UNAUTHENTICATED Заголовок Authorization отсутствует, или токен имеет неправильный формат или срок его действия истек. Получите новый токен доступа и включите его в качестве токена на предъявителя.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Токен не включает область действия, которую принимает метод. Запросите область действия https://www.googleapis.com/auth/gmail.admin.quarantine для методов release и deny и убедитесь, что она авторизована в консоли администратора.
403 PERMISSION_DENIED У администратора, от имени которого выполняется действие, нет прав на доступ к карантину, в котором находится письмо. Предоставьте администратору право Доступ к административному карантину или Доступ к специальным карантинам.
403 SERVICE_DISABLED или 404 NOT_FOUND для каждого метода API не включен в облачном проекте, или проект не зарегистрирован в программе предварительной версии для разработчиков. Включите API и подтвердите участие в программе предварительной версии для разработчиков Google Workspace.

Дальнейшие действия