通过全网域授权进行授权

Mail Admin Quarantine API 专为服务器端自动化而设计，例如安全流水线以及 SIEM 或 SOAR 集成。这些自动化操作会使用 Google Cloud 服务账号进行身份验证，该服务账号使用全网域授权代表拥有所需管理员权限的 Google Workspace 管理员执行操作。

本页面介绍了该 API 需要哪些 OAuth 2.0 范围，以及如何配置服务账号和获取访问令牌。

OAuth 2.0 范围

Admin Quarantine API 使用以下 OAuth 2.0 范围：

下表显示了每个方法接受的范围：

遵循最小权限原则：对于仅监控隔离区的集成，请求只读范围。

如果请求使用的令牌不包含接受的范围，则 API 会返回 403 错误，原因为 ACCESS_TOKEN_SCOPE_INSUFFICIENT。

创建服务账号

1. 在 Google Cloud 控制台中，前往 IAM 和管理 > 服务账号，然后选择您启用了 API 的 Google Cloud 云项目。
2. 点击创建服务账号，输入名称（例如 quarantine-api-service-account），然后点击创建并继续。您无需向服务账号授予任何 IAM 角色。点击完成。
3. 打开服务账号，然后在详细信息标签页中复制 OAuth 2 客户端 ID。这是一个 21 位数字，例如 109876543210987654321。在下一部分中，您将需要此 ID。
4. 在密钥标签页中，依次点击添加密钥 > 创建新密钥，选择 JSON，然后点击创建。妥善存储下载的 JSON 密钥文件。

如需了解详情，请参阅为服务账号创建凭证。

授权全网域委托

授权服务账号访问 Google Workspace 账号中的 Admin Quarantine API 范围：

1. 以超级用户身份登录 Google 管理控制台。
2. 依次前往安全性 > 访问权限和数据控件 > API 控件。
3. 在全网域授权下，点击管理全网域授权。
4. 点击新增。
5. 在客户端 ID 字段中，输入服务账号的 OAuth 2.0 客户端 ID。请勿输入服务账号的邮箱。

6. 在 OAuth 范围字段中，输入以下范围之一：

   • 对于读写权限：https://www.googleapis.com/auth/gmail.admin.quarantine
   • 对于只读访问权限：https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

7. 点击授权。

如需了解详情，请参阅使用全网域委托功能控制 API 访问权限。

获取访问令牌

为了调用 API，服务账号会通过将令牌请求的 subject (sub) 声明设置为管理员的邮箱来模拟管理员。管理员必须拥有所需的管理员权限。

以下 Python 示例使用 google-auth 库获取访问令牌：

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

访问令牌会在 1 小时后过期。在每批请求之前刷新凭据，而不是长时间缓存令牌。

排查授权错误

后续步骤

• 列出和搜索被隔离的邮件