Autorizza con la delega a livello di dominio

L'API Mail Admin Quarantine è progettata per le automazioni lato server, come le pipeline di sicurezza e le integrazioni SIEM o SOAR. Queste automazioni si autenticano con un service account Google Cloud che utilizza la delega a livello di dominio per agire per conto di un amministratore di Google Workspace che dispone del privilegio amministrativo richiesto.

Questa pagina spiega quali ambiti OAuth 2.0 sono richiesti dall'API e come configurare un service account e ottenere un token di accesso.

Ambiti OAuth 2.0

L'API Admin Quarantine utilizza i seguenti ambiti OAuth 2.0:

Ambito Significato
https://www.googleapis.com/auth/gmail.admin.quarantine Visualizzare e gestire i messaggi in quarantena. Necessario per rilasciare o rifiutare i messaggi, singolarmente o in batch.
https://www.googleapis.com/auth/gmail.admin.quarantine.readonly Visualizzare i messaggi in quarantena. Sufficiente per elencare, cercare e recuperare i messaggi, elencare e recuperare le quarantene e ottenere lo stato delle operazioni batch.

La tabella seguente mostra l'ambito accettato da ciascun metodo:

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

Segui il principio del privilegio minimo: richiedi l'ambito di sola lettura per le integrazioni che monitorano solo la quarantena.

Se una richiesta utilizza un token che non include un ambito accettato, l'API restituisce un errore 403 con il motivo ACCESS_TOKEN_SCOPE_INSUFFICIENT.

Crea un account di servizio

  1. Nella console Google Cloud, vai a IAM e amministrazione > Account di servizio e seleziona il progetto cloud Google Cloud in cui hai abilitato l'API.
  2. Fai clic su Crea service account, inserisci un nome come quarantine-api-service-account e fai clic su Crea e continua. Non è necessario concedere alcun ruolo IAM al service account. Fai clic su Fine.
  3. Apri l'account di servizio e, nella scheda Dettagli, copia l'ID client OAuth 2. Si tratta di un numero di 21 cifre, ad esempio 109876543210987654321. Questo ID ti servirà nella sezione successiva.
  4. Nella scheda Chiavi, fai clic su Aggiungi chiave > Crea nuova chiave, seleziona JSON e fai clic su Crea. Archivia in modo sicuro il file della chiave JSON scaricato.

Per saperne di più, consulta Crea credenziali per un service account.

Autorizza la delega a livello di dominio

Autorizza l'account di servizio ad accedere agli ambiti dell'API Admin Quarantine nel tuo account Google Workspace:

  1. Accedi alla Console di amministrazione Google come super amministratore.
  2. Vai a Sicurezza > Accesso e controllo dei dati > Controlli API.
  3. In Delega a livello di dominio, fai clic su Gestisci delega a livello di dominio.
  4. Fai clic su Aggiungi nuovo.
  5. Nel campo ID client, inserisci l'ID client OAuth 2.0 del service account. Non inserire l'indirizzo email del service account.

  6. Nel campo Ambiti OAuth, inserisci uno dei seguenti ambiti:

    • Per l'accesso in lettura e scrittura: https://www.googleapis.com/auth/gmail.admin.quarantine
    • Per l'accesso di sola lettura: https://www.googleapis.com/auth/gmail.admin.quarantine.readonly

  7. Fai clic su Autorizza.

Per maggiori dettagli, consulta Controlla l'accesso all'API con la delega a livello di dominio.

Ottieni un token di accesso

Per chiamare l'API, il service account simula l'identità di un amministratore impostando la rivendicazione subject (sub) della richiesta del token sull'indirizzo email dell'amministratore. L'amministratore deve disporre del privilegio amministrativo richiesto.

Il seguente esempio di Python utilizza la libreria google-auth per ottenere un token di accesso:

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

Invia il token nell'intestazione Authorization di ogni richiesta:

Authorization: Bearer ACCESS_TOKEN

I token di accesso scadono dopo un'ora. Aggiorna le credenziali prima di ogni batch di richieste anziché memorizzare nella cache i token per lunghi periodi.

Risolvere i problemi di autorizzazione

Stato HTTP Motivo Risoluzione
401 UNAUTHENTICATED L'intestazione Authorization non è presente oppure il token non è valido o è scaduto. Ottieni un nuovo token di accesso e includilo come token di connessione.
403 ACCESS_TOKEN_SCOPE_INSUFFICIENT Il token non include un ambito accettato dal metodo. Richiedi l'ambito https://www.googleapis.com/auth/gmail.admin.quarantine per i metodi di rilascio e rifiuto e assicurati che l'ambito sia autorizzato nella Console di amministrazione.
403 PERMISSION_DENIED L'amministratore di cui è stata eseguita la simulazione non dispone di un privilegio di quarantena amministrativa o non ha accesso alla quarantena che contiene il messaggio. Concedi all'amministratore l'Accesso alla quarantena amministrativa o l'Accesso a quarantene limitate.
403 SERVICE_DISABLED o 404 NOT_FOUND su ogni metodo L'API non è abilitata nel progetto cloud o il progetto non è registrato nel programma Anteprima per gli sviluppatori. Attiva l'API e conferma la tua registrazione al programma Anteprima per gli sviluppatori di Google Workspace.

Passaggi successivi