ドメイン全体の委任で承認する

Mail Admin Quarantine API は、セキュリティ パイプラインや SIEM または SOAR の統合などのサーバーサイドの自動化向けに設計されています。これらの自動化は、ドメイン全体の委任を使用して、必要な管理者権限を持つ Google Workspace 管理者の代理として機能する Google Cloud サービス アカウントで認証します。

このページでは、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 と管理] > [サービス アカウント] に移動し、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 時間後に期限切れになります。トークンを長期間キャッシュに保存するのではなく、リクエストのバッチごとに認証情報を更新します。

承認エラーのトラブルシューティング

HTTP ステータス 理由 解決策
401 UNAUTHENTICATED Authorization ヘッダーがないか、トークンの形式が正しくないか、期限切れです。 新しいアクセス トークンを取得し、署名なしトークンとして含めます。
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT トークンに、メソッドが受け入れるスコープが含まれていません。 release メソッドと deny メソッドに https://www.googleapis.com/auth/gmail.admin.quarantine スコープをリクエストし、管理コンソールでスコープが承認されていることを確認します。
403 PERMISSION_DENIED なりすましの対象となった管理者が、管理者検疫権限を持っていないか、メッセージが格納されている検疫にアクセスできない。 管理者に [管理者検疫にアクセス] または [一部の検疫対象メールにアクセス] の権限を付与します。
すべてのメソッドで 403 SERVICE_DISABLED または 404 NOT_FOUND Cloud プロジェクトで API が有効になっていないか、プロジェクトがデベロッパー プレビュー プログラムに登録されていません。 API を有効にして、Google Workspace デベロッパー プレビュー プログラムに登録されていることを確認します。

次のステップ