使用全網域委派功能進行授權

Mail Admin Quarantine API 適用於伺服器端自動化作業，例如安全性管道和 SIEM 或 SOAR 整合。這些自動化作業會透過 Google Cloud 服務帳戶進行驗證，該帳戶會使用全網域委派功能，代表具備必要管理員權限的 Google Workspace 管理員執行操作。

本頁說明 API 需要哪些 OAuth 2.0 範圍，以及如何設定服務帳戶和取得存取權杖。

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」(服務帳戶) ，然後選取 已啟用 API 的 Google Cloud 專案。
  2. 按一下「Create service account」(建立服務帳戶)，輸入名稱 (例如 quarantine-api-service-account)，然後按一下「Create and continue」(建立並繼續)。您不需要為服務帳戶授予任何 IAM 角色。接著，點選「Done」(完成)。
  3. 開啟服務帳戶，然後在「Details」(詳細資料) 分頁中複製「OAuth 2 Client ID」(OAuth 2 用戶端 ID)。這組號碼共有 21 位數，例如 109876543210987654321。下一節會用到這個 ID。
  4. 在「Keys」(金鑰) 分頁中，依序點選「Add key」(新增金鑰) >「Create new key」(建立新的金鑰)，選取「JSON」，然後點選「Create」(建立)。妥善保存下載的 JSON 金鑰檔案。

詳情請參閱「建立服務帳戶憑證」。

授權全網域委派

授權服務帳戶存取 Google Workspace 帳戶中的 Admin Quarantine API 範圍：

  1. 以超級管理員身分登入 Google 管理控制台。
  2. 依序前往「安全性」>「存取權與資料控管」>「API 控制項」。
  3. 在「全網域委派」下方，按一下「管理全網域委派設定」。
  4. 點選「新增」。
  5. 在「Client ID」(用戶端 ID) 欄位中，輸入服務帳戶的 OAuth 2.0 用戶端 ID。請勿輸入服務帳戶的電子郵件地址。

  6. 在「OAuth scopes」(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 小時後失效。請在每批要求前重新整理憑證，而不是長時間快取權杖。

排解授權錯誤

HTTP 狀態 原因 解析度
401 UNAUTHENTICATED 缺少 Authorization 標頭，或是權杖格式錯誤或已過期。 取得新的存取權杖，並將其納入為不記名權杖。
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT 權杖不含方法接受的範圍。 要求釋出和拒絕方法的 https://www.googleapis.com/auth/gmail.admin.quarantine 範圍，並確認該範圍已在管理控制台中獲得授權。
403 PERMISSION_DENIED 模擬的管理員不具備管理員隔離區權限，或無法存取保留郵件的隔離區。 將「存取管理員隔離區」或「存取受限的隔離區」權限授予管理員。
每個方法都有 403 SERVICE_DISABLED 或 404 NOT_FOUND 雲端專案未啟用 API，或專案未加入開發人員預覽版計畫。 啟用 API，並確認您已加入 Google Workspace 開發人員預覽版計畫。

後續步驟