Mit domainweiter Delegierung autorisieren

Die Mail Admin Quarantine API ist für serverseitige Automatisierungen wie Sicherheitspipelines und SIEM- oder SOAR-Integrationen konzipiert. Diese Automatisierungen werden mit einem Google Cloud-Dienstkonto authentifiziert, das die domainweite Delegation verwendet, um im Namen eines Google Workspace-Administrators zu agieren, der die erforderliche Administratorberechtigung hat.

Auf dieser Seite wird erläutert, welche OAuth 2.0-Bereiche die API benötigt, wie Sie ein Dienstkonto konfigurieren und wie Sie ein Zugriffstoken abrufen.

OAuth-2.0-Bereiche

Die Admin Quarantine API verwendet die folgenden OAuth 2.0-Bereiche:

Bereich Bedeutung
https://www.googleapis.com/auth/gmail.admin.quarantine Unter Quarantäne gestellte Nachrichten ansehen und verwalten Erforderlich, um Nachrichten einzeln oder im Batch freizugeben oder abzulehnen.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Nachrichten in Quarantäne ansehen Ausreichend, um Nachrichten aufzulisten, zu suchen und abzurufen, Quarantänen aufzulisten und abzurufen sowie den Status von Batchvorgängen abzurufen.

In der folgenden Tabelle sehen Sie, welche Bereiche von den einzelnen Methoden akzeptiert werden:

Methode 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 ✓

Folgen Sie dem Prinzip der geringsten Berechtigung: Fordern Sie den schreibgeschützten Bereich für Integrationen an, die nur die Quarantäne überwachen.

Wenn in einer Anfrage ein Token verwendet wird, das keinen akzeptierten Bereich enthält, gibt die API den Fehler 403 mit dem Grund ACCESS_TOKEN_SCOPE_INSUFFICIENT zurück.

Dienstkonto erstellen

  1. Rufen Sie in der Google Cloud Console IAM und Verwaltung > Dienstkonten auf und wählen Sie das Google Cloud-Projekt aus, in dem Sie die API aktiviert haben.
  2. Klicken Sie auf Dienstkonto erstellen, geben Sie einen Namen wie quarantine-api-service-account ein und klicken Sie auf Erstellen und fortfahren. Sie müssen dem Dienstkonto keine IAM-Rollen zuweisen. Klicken Sie auf Fertig.
  3. Öffnen Sie das Dienstkonto und kopieren Sie auf dem Tab Details die OAuth 2-Client-ID. Es handelt sich um eine 21-stellige Zahl, z. B. 109876543210987654321. Sie benötigen diese ID im nächsten Abschnitt.
  4. Klicken Sie auf dem Tab Schlüssel auf Schlüssel hinzufügen > Neuen Schlüssel erstellen, wählen Sie JSON aus und klicken Sie auf Erstellen. Speichern Sie die heruntergeladene JSON-Schlüsseldatei an einem sicheren Ort.

Weitere Informationen finden Sie unter Anmeldedaten für ein Dienstkonto erstellen.

Domainweite Delegierung autorisieren

Autorisieren Sie das Dienstkonto für den Zugriff auf die Admin Quarantine API-Bereiche in Ihrem Google Workspace-Konto:

  1. Melden Sie sich als Super Admin in der Admin-Konsole an.
  2. Gehen Sie zu Sicherheit > Zugriffs- und Datenkontrolle > API-Steuerung.
  3. Klicken Sie unter Domainweite Delegierung auf Domainweite Delegierung verwalten.
  4. Klicken Sie auf Neu hinzufügen.
  5. Geben Sie im Feld Client-ID die OAuth 2.0-Client-ID des Dienstkontos ein. Geben Sie nicht die E-Mail-Adresse des Dienstkontos ein.

  6. Geben Sie im Feld OAuth-Bereiche einen der folgenden Bereiche ein:

    • Für Lese- und Schreibzugriff: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Für Lesezugriff: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Klicken Sie auf Autorisieren.

Weitere Informationen finden Sie im Hilfeartikel Zugriff auf die API mit domainweiter Delegierung verwalten.

Zugriffstoken abrufen

Zum Aufrufen der API übernimmt das Dienstkonto die Identität eines Administrators. Dazu wird die subject-Anforderung (sub) der Tokenanfrage auf die E-Mail-Adresse des Administrators festgelegt. Der Administrator muss die erforderliche Administratorberechtigung haben.

Im folgenden Python-Beispiel wird die Bibliothek google-auth verwendet, um ein Zugriffstoken abzurufen:

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

Senden Sie das Token im Header Authorization jeder Anfrage:

Authorization: Bearer ACCESS_TOKEN

Zugriffstokens laufen nach einer Stunde ab. Aktualisieren Sie die Anmeldedaten vor jedem Batch von Anfragen, anstatt Tokens über einen längeren Zeitraum im Cache zu speichern.

Fehler bei der Autorisierung beheben

HTTP-Status Grund Auflösung
401 UNAUTHENTICATED Der Header Authorization fehlt oder das Token ist fehlerhaft oder abgelaufen. Fordern Sie ein neues Zugriffstoken an und fügen Sie es als Inhabertoken ein.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Das Token enthält keinen Bereich, der von der Methode akzeptiert wird. Fordern Sie den Bereich https://www.googleapis.com/auth/gmail.admin.quarantine für die Methoden „release“ und „deny“ an und achten Sie darauf, dass der Bereich in der Admin-Konsole autorisiert ist.
403 PERMISSION_DENIED Der Administrator, dessen Identität angenommen wurde, hat keine Berechtigung für die Administratorquarantäne oder keinen Zugriff auf die Quarantäne, in der sich die Nachricht befindet. Gewähren Sie dem Administrator die Berechtigung Administratorquarantäne aufrufen oder Zugriff auf eingeschränkte Quarantänen.
403 SERVICE_DISABLED oder 404 NOT_FOUND für jede Methode Die API ist im Cloud-Projekt nicht aktiviert oder das Projekt ist nicht für das Entwicklervorschauprogramm registriert. Aktivieren Sie die API und bestätigen Sie Ihre Anmeldung für das Google Workspace Entwicklervorschauprogramm.

Nächste Schritte