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:

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

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

Passaggi successivi

• Elencare e cercare i messaggi in quarantena