Autoriser avec la délégation au niveau du domaine

L'API Mail Admin Quarantine est conçue pour les automatisations côté serveur, telles que les pipelines de sécurité et les intégrations SIEM ou SOAR. Ces automatisations s'authentifient à l'aide d'un compte de service Google Cloud qui utilise la délégation au niveau du domaine pour agir au nom d'un administrateur Google Workspace disposant du droit d'administrateur requis.

Cette page explique les champs d'application OAuth 2.0 requis par l'API, et comment configurer un compte de service et obtenir un jeton d'accès.

Champs d'application OAuth 2.0

L'API Admin Quarantine utilise les champs d'application OAuth 2.0 suivants :

Champ d'application Signification
https://www.googleapis.com/auth/gmail.admin.quarantine Affichez et gérez les messages mis en quarantaine. Requis pour libérer ou refuser des messages, individuellement ou par lots.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Afficher les messages mis en quarantaine. Suffisant pour lister, rechercher et obtenir des messages, lister et obtenir des quarantaines, et obtenir l'état des opérations par lot.

Le tableau suivant indique le champ d'application accepté par chaque méthode :

Méthode 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 ✓

Suivez le principe du moindre privilège : demandez le champ d'application en lecture seule pour les intégrations qui ne font que surveiller la quarantaine.

Si une requête utilise un jeton qui n'inclut pas de champ d'application accepté, l'API renvoie une erreur 403 avec le motif ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Créer un compte de service

  1. Dans la console Google Cloud, accédez à IAM et administration > Comptes de service, puis sélectionnez le projet Google Cloud dans lequel vous avez activé l'API.
  2. Cliquez sur Créer un compte de service, saisissez un nom tel que quarantine-api-service-account, puis cliquez sur Créer et continuer. Vous n'avez pas besoin d'attribuer de rôle IAM au compte de service. Cliquez sur OK.
  3. Ouvrez le compte de service et, dans l'onglet Détails, copiez l'ID client OAuth 2. Il s'agit d'un numéro à 21 chiffres, par exemple 109876543210987654321. Vous en aurez besoin dans la section suivante.
  4. Dans l'onglet Clés, cliquez sur Ajouter une clé > Créer une clé, sélectionnez JSON, puis cliquez sur Créer. Stockez le fichier de clé JSON téléchargé de manière sécurisée.

Pour en savoir plus, consultez Créer des identifiants pour un compte de service.

Autoriser la délégation au niveau du domaine

Autorisez le compte de service à accéder aux champs d'application de l'API Admin Quarantine dans votre compte Google Workspace :

  1. Connectez-vous à la console d'administration Google en tant que super-administrateur.
  2. Accédez à Sécurité > Contrôle des accès et des données > Commandes des API.
  3. Sous Délégation au niveau du domaine, cliquez sur Gérer la délégation au niveau du domaine.
  4. Cliquez sur Ajouter.
  5. Dans le champ ID client, saisissez l'ID client OAuth 2.0 du compte de service. Ne saisissez pas l'adresse e-mail du compte de service.

  6. Dans le champ Champs d'application OAuth, saisissez l'un des champs d'application suivants :

    • Pour un accès en lecture et en écriture : https://www.googleapis.com/auth/gmail.admin.quarantine
    • Pour un accès en lecture seule : https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Cliquez sur Autoriser.

Pour en savoir plus, consultez Contrôler l'accès à l'API à l'aide de la délégation au niveau du domaine.

Obtenir un jeton d'accès

Pour appeler l'API, le compte de service emprunte l'identité d'un administrateur en définissant la revendication subject (sub) de la requête de jeton sur l'adresse e-mail de l'administrateur. L'administrateur doit disposer du droit d'administrateur requis.

L'exemple Python suivant utilise la bibliothèque google-auth pour obtenir un jeton d'accès :

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

Envoyez le jeton dans l'en-tête Authorization de chaque requête :

Authorization: Bearer ACCESS_TOKEN

Les jetons d'accès expirent au bout d'une heure. Actualisez les identifiants avant chaque lot de requêtes plutôt que de mettre en cache les jetons pendant de longues périodes.

Résoudre les erreurs d'autorisation

État HTTP Motif Solution
401 UNAUTHENTICATED L'en-tête Authorization est manquant, ou le jeton est incorrect ou a expiré. Obtenez un nouveau jeton d'accès et incluez-le en tant que jeton de support.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Le jeton n'inclut pas de champ d'application accepté par la méthode. Demandez le champ d'application https://www.googleapis.com/auth/gmail.admin.quarantine pour les méthodes de libération et de refus, et assurez-vous que le champ d'application est autorisé dans la console d'administration.
403 PERMISSION_DENIED L'administrateur dont l'identité est empruntée ne dispose pas d'un droit de mise en quarantaine par l'administrateur ou n'a pas accès à la zone de quarantaine contenant le message. Accordez à l'administrateur le droit Accéder à la zone de quarantaine administrative ou Accéder aux zones de quarantaine restreintes.
403 SERVICE_DISABLED ou 404 NOT_FOUND sur chaque méthode L'API n'est pas activée dans le projet Cloud, ou le projet n'est pas inscrit au programme Preview développeur. Activez l'API et confirmez votre inscription au programme Preview développeur Google Workspace.

Étapes suivantes