Utilizzo di OAuth 2.0 per le applicazioni da server a server

<0x0 Per saperne di più, consulta la panoramica sull'autenticazione nella documentazione di Google Cloud.

Il sistema Google OAuth 2.0 supporta le interazioni server-to-server, ad esempio quelle tra un'applicazione web e un servizio Google. Per questo scenario è necessario un service account, ovvero un account che appartiene alla tua applicazione anziché a un singolo utente finale. La tua applicazione chiama le API di Google per conto del service account, quindi gli utenti non sono direttamente coinvolti. Questo scenario è talvolta chiamato "OAuth a due passaggi" o "2LO". Il termine correlato "OAuth a tre vie" si riferisce a scenari in cui la tua applicazione chiama le API di Google per conto degli utenti finali e in cui a volte è richiesto il consenso dell'utente.

In genere, un'applicazione utilizza un service account quando utilizza le API Google per lavorare con i propri dati anziché con quelli di un utente. Ad esempio, un'applicazione che utilizza Google Cloud Datastore per la persistenza dei dati utilizzerebbe un service account per autenticare le chiamate all'API Google Cloud Datastore.

Gli amministratori di dominio Google Workspace possono anche concedere agli account di servizio l'autorità a livello di dominio per accedere ai dati degli utenti per loro conto nel dominio.

Questo documento descrive come un'applicazione può completare il flusso OAuth 2.0 da server a server utilizzando una libreria client delle API di Google (consigliata) o HTTP.

Con alcune API di Google, puoi effettuare chiamate API autorizzate utilizzando un JWT firmato anziché utilizzare OAuth 2.0, il che può farti risparmiare una richiesta di rete. Consulta Appendice: autorizzazione del service account senza OAuth.

Panoramica

Per supportare le interazioni server-server, crea prima un service account per il tuo progetto in API Console. Se vuoi accedere ai dati utente per gli utenti del tuo account Google Workspace, delega l'accesso a livello di dominio all'account di servizio.

Quindi, la tua applicazione si prepara a effettuare chiamate API autorizzate utilizzando le credenziali del service account per richiedere un token di accesso dal server di autenticazione OAuth 2.0.

Infine, l'applicazione può utilizzare il token di accesso per chiamare le API di Google.

Consiglio:la tua applicazione può completare queste attività utilizzando la libreria client delle API di Google per la tua lingua o interagendo direttamente con il sistema OAuth 2.0 tramite HTTP. Tuttavia, la meccanica delle interazioni di autenticazione server-to-server richiede che le applicazioni creino e firmino crittograficamente i token JWT (JSON Web Token) ed è facile commettere errori gravi che possono avere un impatto significativo sulla sicurezza dell'applicazione.

Per questo motivo, ti consigliamo vivamente di utilizzare librerie, come le librerie client delle API di Google, che astraggono la crittografia dal codice dell'applicazione.

Creazione di un account di servizio

Le credenziali di un service account includono un indirizzo email generato univoco e almeno una coppia di chiavi pubbliche/private. Se la delega sull'intero dominio è abilitata, anche un ID client fa parte delle credenziali del service account.

Se la tua applicazione viene eseguita su Google App Engine, un service account viene configurato automaticamente quando crei il progetto.

Se la tua applicazione viene eseguita su Google Compute Engine, viene configurato automaticamente anche un service account quando crei il progetto, ma devi specificare gli ambiti a cui la tua applicazione deve accedere quando crei un'istanza Google Compute Engine. Per ulteriori informazioni, consulta Preparare un'istanza per l'utilizzo dei service account.

Se la tua applicazione non viene eseguita su Google App Engine o Google Compute Engine, devi ottenere queste credenziali in Google API Console. Per generare le credenziali del service account o per visualizzare le credenziali pubbliche che hai già generato:

Innanzitutto, crea un account di servizio:

1. Apri il Service accounts page.
2. If prompted, select a project, or create a new one.
3. Fai clic su Crea account di servizio .
4. In Dettagli dell'account di servizio , digita un nome, un ID e una descrizione per l'account di servizio, quindi fai clic su Crea e continua .
5. Facoltativo: in Concedi a questo account di servizio l'accesso al progetto , seleziona i ruoli IAM da concedere all'account di servizio.
6. Fare clic su Continua .
7. Facoltativo: in Concedi agli utenti l'accesso a questo account di servizio , aggiungi gli utenti o i gruppi autorizzati a utilizzare e gestire l'account di servizio.
8. Fai clic su Fatto .

Successivamente, crea una chiave dell'account di servizio:

1. Fai clic sull'indirizzo email dell'account di servizio che hai creato.
2. Fare clic sulla scheda Chiavi .
3. Nell'elenco a discesa Aggiungi chiave , seleziona Crea nuova chiave .
4. Fai clic su Crea .

La tua nuova coppia di chiavi pubblica/privata viene generata e scaricata sulla tua macchina; funge da unica copia della chiave privata. Sei responsabile di conservarlo in modo sicuro. Se perdi questa coppia di chiavi, dovrai generarne una nuova.

Puoi tornare alla API Console in qualsiasi momento per visualizzare l'indirizzo email, le impronte delle chiavi pubbliche e altre informazioni o per generare coppie di chiavi pubblica/privata aggiuntive. Per maggiori dettagli sulle credenziali del service account in API Console, vedi Service account nel file di guida di API Console.

Prendi nota dell'indirizzo email del service account e memorizza il file della chiave privata del service account in una posizione accessibile alla tua applicazione. La tua applicazione ne ha bisogno per effettuare chiamate API autorizzate.

Nota:devi archiviare e gestire le chiavi private in modo sicuro sia negli ambienti di sviluppo che in quelli di produzione. Google non conserva una copia delle tue chiavi private, ma solo delle tue chiavi pubbliche. Per ulteriori informazioni, consulta la sezione Gestire le credenziali client in modo sicuro dei criteri OAuth 2.0.

Delega dell'autorità a livello di dominio al service account

Utilizzando un account Google Workspace, un amministratore Workspace dell'organizzazione può autorizzare un'applicazione ad accedere ai dati degli utenti Workspace per conto degli utenti nel dominio Google Workspace. Ad esempio, un'applicazione che utilizza l'API Google Calendar per aggiungere eventi ai calendari di tutti gli utenti di un dominio Google Workspace utilizzerebbe un service account per accedere all'API Google Calendar per conto degli utenti. L'autorizzazione di un service account ad accedere ai dati per conto degli utenti di un dominio viene a volte definita "delega dell'autorità a livello di dominio" a un service account.

Nota:quando utilizzi Google Workspace Marketplace per installare un'applicazione per il tuo dominio, le autorizzazioni richieste vengono concesse automaticamente all'applicazione durante l'installazione. Non è necessario autorizzare manualmente i service account utilizzati dall'applicazione.

Nota:anche se puoi utilizzare i service account nelle applicazioni eseguite da un dominio Google Workspace, i service account non sono membri del tuo account Google Workspace e non sono soggetti alle norme del dominio impostate dagli amministratori Google Workspace. Ad esempio, un insieme di norme impostato nella Console di amministrazione Google Workspace per limitare la possibilità degli utenti finali di Google Workspace di condividere documenti al di fuori del dominio non si applicherebbe ai service account.

Per delegare l'autorizzazione a livello di dominio a un service account, un super amministratore del dominio Google Workspace deve completare i seguenti passaggi:

1. Dalla Console di amministrazione del dominio Google Workspace, vai a Menu principale > Sicurezza > Accesso e controllo dei dati > Controlli API.
2. Nel riquadro Delega a livello di dominio, seleziona Gestisci delega a livello di dominio.
3. Fai clic su Aggiungi nuova.
4. Nel campo ID client, inserisci l'ID client dell'account di servizio. Puoi trovare l'ID client del tuo service account in Service accounts page.
5. Nel campo Ambiti OAuth (delimitati da virgole), inserisci l'elenco degli ambiti a cui deve essere concesso l'accesso alla tua applicazione. Ad esempio, se la tua applicazione richiede l'accesso completo a livello di dominio all'API di Google Drive e all'API di Google Calendar, inserisci: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
6. Fai clic su Autorizza.

La tua applicazione ora ha l'autorità di effettuare chiamate API come utenti del tuo dominio Workspace (per "simulare" gli utenti). Quando ti prepari a effettuare queste chiamate API delegate, devi specificare esplicitamente l'utente da rappresentare.

Nota:in genere, l'accesso con rappresentazione viene concesso pochi minuti dopo l'aggiunta dell'ID client, ma in alcuni casi la propagazione a tutti gli utenti del tuo Account Google potrebbe richiedere fino a 24 ore.

Preparazione per effettuare una chiamata API delegata

Java

Dopo aver ottenuto l'indirizzo email client e la chiave privata da API Console, utilizza la libreria di autenticazione Google per Java per creare un oggetto GoogleCredentials dalle credenziali dell'account di servizio e gli ambiti a cui la tua applicazione deve accedere. Ad esempio:

import com.google.auth.oauth2.GoogleCredentials;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Se stai sviluppando un'app su Google Cloud, puoi utilizzare le credenziali predefinite dell'applicazione, che possono semplificare la procedura.

Delegare l'autorità a livello di dominio

Se hai delegato l'accesso a livello di dominio all'account di servizio e vuoi rappresentare un account utente, specifica l'indirizzo email dell'account utente con il metodo createDelegated dell'oggetto GoogleCredentials. Ad esempio:

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("[e-mail]");

Il codice riportato sopra utilizza l'oggetto GoogleCredentials per chiamare il metodo createDelegated(). L'argomento per il metodo createDelegated() deve essere un utente che appartiene al tuo account Workspace. Il codice che effettua la richiesta utilizzerà queste credenziali per chiamare le API Google utilizzando il tuo service account.

Python

Dopo aver ottenuto l'indirizzo email del client e la chiave privata da API Console, utilizza la libreria client delle API di Google per Python per completare i seguenti passaggi:

1. Crea un oggetto Credentials dalle credenziali del service account e dagli ambiti a cui la tua applicazione deve accedere. Ad esempio:

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   Se stai sviluppando un'app su Google Cloud, puoi utilizzare le credenziali predefinite dell'applicazione, che possono semplificare la procedura.

2. Delegare l'autorità a livello di dominio

   Se hai delegato l'accesso a livello di dominio al service account e vuoi assumere l'identità di un account utente, utilizza il metodo with_subject di un oggetto ServiceAccountCredentials esistente. Ad esempio:

   delegated_credentials = credentials.with_subject('[e-mail]')

Utilizza l'oggetto Credentials per chiamare le API di Google nella tua applicazione.

HTTP/REST

Consiglio:anche se la tua applicazione può completare queste attività interagendo direttamente con il sistema OAuth 2.0 tramite HTTP, la meccanica delle interazioni di autenticazione server-to-server richiede alle applicazioni di creare e firmare crittograficamente i token web JSON (JWT) ed è facile commettere errori gravi che possono avere un impatto significativo sulla sicurezza della tua applicazione.

Per questo motivo, ti consigliamo vivamente di utilizzare librerie, come le librerie client delle API di Google, che astraggono la crittografia dal codice dell'applicazione.

Dopo aver ottenuto l'ID client e la chiave privata da API Console, la tua applicazione deve completare i seguenti passaggi:

1. Crea un token web JSON (JWT, pronunciato "jot") che includa un'intestazione, un insieme di attestazioni e una firma.
2. Richiedi un token di accesso dal server di autorizzazione Google OAuth 2.0.
3. Gestisci la risposta JSON restituita dal server di autorizzazione.

Le sezioni seguenti descrivono come completare questi passaggi.

Se la risposta include un token di accesso, puoi utilizzarlo per chiamare un'API di Google. (Se la risposta non include un token di accesso, la richiesta di JWT e token potrebbe non essere formata correttamente oppure l'account di servizio potrebbe non disporre dell'autorizzazione per accedere agli ambiti richiesti.)

Quando il token di accesso scade, la tua applicazione genera un altro JWT, lo firma e richiede un altro token di accesso.

Il resto di questa sezione descrive i dettagli della creazione di un JWT, della firma del JWT, della formazione della richiesta di token di accesso e della gestione della risposta.

Creazione di un JWT

Un JWT è composto da tre parti: un'intestazione, un insieme di rivendicazioni e una firma. L'intestazione e l'insieme di attestazioni sono oggetti JSON. Questi oggetti JSON vengono serializzati in byte UTF-8, quindi codificati utilizzando la codifica Base64url. Questa codifica offre resilienza alle modifiche alla codifica dovute a operazioni di codifica ripetute. L'intestazione, il set di rivendicazioni e la firma vengono concatenati con un punto (.).

Un JWT è composto come segue:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

La stringa di base per la firma è la seguente:

{Base64url encoded header}.{Base64url encoded claim set}

Formare l'intestazione JWT

L'intestazione è composta da tre campi che indicano l'algoritmo di firma, il formato dell'asserzione e l'ID chiave dell'account di servizio utilizzato per firmare il JWT. L'algoritmo e il formato sono obbligatori e ogni campo ha un solo valore. Man mano che verranno introdotti altri algoritmi e formati, questa intestazione cambierà di conseguenza. L'ID chiave è facoltativo e, se viene specificato un ID chiave errato, GCP tenterà di utilizzare tutte le chiavi associate al service account per verificare il token e lo rifiuterà se non viene trovata alcuna chiave valida. Google si riserva il diritto di rifiutare i token con ID chiave non corretti in futuro.

I service account si basano sull'algoritmo RSA SHA-256 e sul formato del token JWT. Di conseguenza, la rappresentazione JSON dell'intestazione è la seguente:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

La rappresentazione Base64url è la seguente:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

Formazione del set di attestazioni JWT

Il set di rivendicazioni JWT contiene informazioni sul JWT, incluse le autorizzazioni richieste (ambiti), la destinazione del token, l'emittente, l'ora di emissione del token e la durata del token. La maggior parte dei campi è obbligatoria. Come l'intestazione JWT, il set di attestazioni JWT è un oggetto JSON e viene utilizzato nel calcolo della firma.

Rivendicazioni obbligatorie

Di seguito sono riportate le rivendicazioni richieste nel set di rivendicazioni JWT. Possono essere visualizzati in qualsiasi ordine nel set di rivendicazioni.

Nome	Descrizione
iss	L'indirizzo email del service account.
scope	Un elenco delimitato da spazi delle autorizzazioni richieste dall'applicazione.
aud	Un descrittore del target previsto dell'asserzione. Quando si effettua una richiesta di token di accesso, questo valore è sempre https://oauth2.googleapis.com/token.
exp	L'ora di scadenza dell'asserzione, specificata in secondi dal giorno 1° gennaio 1970 alle ore 00:00:00 UTC. Questo valore ha un massimo di 1 ora dopo l'ora di emissione.
iat	L'ora di emissione dell'asserzione, specificata in secondi a partire dalle ore 00:00:00 UTC del 1° gennaio 1970.

Di seguito è riportata la rappresentazione JSON dei campi obbligatori in un insieme di attestazioni JWT:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Rivendicazioni aggiuntive

In alcuni casi aziendali, un'applicazione può utilizzare la delega a livello di dominio per agire per conto di un determinato utente di un'organizzazione. L'autorizzazione a eseguire questo tipo di rappresentazione deve essere concessa prima che un'applicazione possa rappresentare un utente ed è in genere gestita da un super amministratore. Per saperne di più, vedi Controllare l'accesso all'API con la delega a livello di dominio.

Per ottenere un token di accesso che concede a un'applicazione l'accesso delegato a una risorsa, includi l'indirizzo email dell'utente nel set di attestazioni JWT impostato come valore del campo sub.

Nome	Descrizione
sub	L'indirizzo email dell'utente per cui l'applicazione richiede l'accesso delegato.

Se un'applicazione non dispone dell'autorizzazione per impersonare un utente, la risposta a una richiesta di token di accesso che include il campo sub sarà un errore.

Di seguito è riportato un esempio di insieme di rivendicazioni JWT che include il campo sub:

{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Codifica del set di attestazioni JWT

Come l'intestazione JWT, il set di attestazioni JWT deve essere serializzato in UTF-8 e codificato in Base64url-safe. Di seguito è riportato un esempio di rappresentazione JSON di un insieme di rivendicazioni JWT:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Calcolo della firma

JSON Web Signature (JWS) è la specifica che guida la meccanica di generazione della firma per il JWT. L'input per la firma è l'array di byte dei seguenti contenuti:

{Base64url encoded header}.{Base64url encoded claim set}

L'algoritmo di firma nell'intestazione JWT deve essere utilizzato per calcolare la firma. L'unico algoritmo di firma supportato dal server di autorizzazione Google OAuth 2.0 è RSA che utilizza l'algoritmo di hashing SHA-256. Questo valore è espresso come RS256 nel campo alg dell'intestazione JWT.

Firma la rappresentazione UTF-8 dell'input utilizzando SHA256withRSA (nota anche come RSASSA-PKCS1-V1_5-SIGN con la funzione hash SHA-256) con la chiave privata ottenuta da Google API Console. L'output sarà un array di byte.

La firma deve poi essere codificata in Base64url. L'intestazione, il set di rivendicazioni e la firma vengono concatenati con un punto (.). Il risultato è il JWT. Deve essere il seguente (interruzioni di riga aggiunte per chiarezza):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Di seguito è riportato un esempio di JWT prima della codifica Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"[e-mail]",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Di seguito è riportato un esempio di JWT firmato e pronto per la trasmissione:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Presentazione della richiesta di token di accesso

Dopo aver generato il JWT firmato, un'applicazione può utilizzarlo per richiedere un token di accesso. Questa richiesta di token di accesso è una richiesta HTTPS POST e il corpo è codificato tramite URL. L'URL è riportato di seguito:

https://oauth2.googleapis.com/token

I seguenti parametri sono obbligatori nella richiesta HTTPS POST:

Nome	Descrizione
grant_type	Utilizza la seguente stringa, codificata come URL se necessario: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	Il JWT, inclusa la firma.

Di seguito è riportato un dump non elaborato della richiesta HTTPS POST utilizzata in una richiesta di token di accesso:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Di seguito è riportata la stessa richiesta, utilizzando curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Gestione della risposta

Se la richiesta di JWT e token di accesso è formattata correttamente e il service account dispone dell'autorizzazione per eseguire l'operazione, la risposta JSON del server di autorizzazione include un token di accesso. Di seguito è riportato un esempio di risposta:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

I token di accesso possono essere riutilizzati durante la finestra di durata specificata dal valore expires_in.

Chiamata alle API di Google

Java

Utilizza l'oggetto GoogleCredentials per chiamare le API di Google completando i seguenti passaggi:

1. Crea un oggetto di servizio per l'API che vuoi chiamare utilizzando l'oggetto GoogleCredentials. Ad esempio:

   SQLAdmin sqladmin =
       new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credentials).build();

2. Invia richieste al servizio API utilizzando l'interfaccia fornita dall'oggetto servizio. Ad esempio, per elencare le istanze dei database Cloud SQL nel progetto exciting-example-123:

   SQLAdmin.Instances.List instances =
       sqladmin.instances().list("exciting-example-123").execute();

Python

Utilizza l'oggetto Credentials autorizzato per chiamare le API di Google completando i seguenti passaggi:

1. Crea un oggetto di servizio per l'API che vuoi chiamare. Crea un oggetto di servizio chiamando la funzione build con il nome e la versione dell'API e l'oggetto Credentials autorizzato. Ad esempio, per chiamare la versione 1beta3 dell'API Cloud SQL Administration:

   import googleapiclient.discovery
   
   sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

2. Invia richieste al servizio API utilizzando l'interfaccia fornita dall'oggetto servizio. Ad esempio, per elencare le istanze dei database Cloud SQL nel progetto exciting-example-123:

   response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Dopo che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un'API Google per conto di un determinato service account o account utente se sono stati concessi gli ambiti di accesso richiesti dall'API. Per farlo, includi il token di accesso in una richiesta all'API includendo un parametro di query access_token o un valore Bearer dell'intestazione HTTP Authorization. Se possibile, è preferibile l'intestazione HTTP, perché le stringhe di query tendono a essere visibili nei log del server. Nella maggior parte dei casi puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, quando chiami l'API Drive Files).

Puoi provare tutte le API di Google e visualizzare i relativi ambiti in OAuth 2.0 Playground.

Esempi di HTTP GET

Una chiamata all'endpoint drive.files (l'API Drive Files) utilizzando l'intestazione HTTP Authorization: Bearer potrebbe essere simile alla seguente. Tieni presente che devi specificare il tuo token di accesso:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Ecco una chiamata alla stessa API per l'utente autenticato utilizzando il parametro della stringa di query access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl esempi

Puoi testare questi comandi con l'applicazione a riga di comando curl. Ecco un esempio che utilizza l'opzione dell'intestazione HTTP (preferita):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

In alternativa, l'opzione del parametro stringa di query:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Quando scadono i token di accesso

I token di accesso emessi dal server di autorizzazione Google OAuth 2.0 scadono dopo la durata fornita dal valore expires_in. Quando un token di accesso scade, l'applicazione deve generare un altro JWT, firmarlo e richiedere un altro token di accesso.

Codici di errore JWT

Campo error	Campo error_description	Significato	Come risolvere il problema
unauthorized_client	Unauthorized client or scope in request.	Se stai tentando di utilizzare la delega sull'intero dominio, il service account non è autorizzato nella Console di amministrazione del dominio dell'utente.	Assicurati che il service account sia autorizzato nella pagina Delega sull'intero dominio della Console di amministrazione per l'utente nell'attestazione (campo) sub. Anche se in genere ci vogliono pochi minuti, l'autorizzazione potrebbe richiedere fino a 24 ore per essere propagata a tutti gli utenti del tuo Account Google.
unauthorized_client	Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.	Un service account è stato autorizzato utilizzando l'indirizzo email client anziché l'ID client (numerico) nella Console di amministrazione.	Nella pagina Delega a livello di dominio della Console di amministrazione, rimuovi il client e aggiungilo di nuovo con l'ID numerico.
access_denied	(qualsiasi valore)	Se utilizzi la delega sull'intero dominio, uno o più ambiti richiesti non sono autorizzati nella Console di amministrazione.	Assicurati che l'account di servizio sia autorizzato nella pagina Delega a livello di dominio della Console di amministrazione per l'utente nell'attestazione sub (campo) e che includa tutti gli ambiti che stai richiedendo nell'attestazione scope del JWT. Anche se in genere ci vogliono pochi minuti, l'autorizzazione potrebbe richiedere fino a 24 ore per essere propagata a tutti gli utenti del tuo Account Google.
admin_policy_enforced	(qualsiasi valore)	L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa delle norme del suo amministratore di Google Workspace.	Per ulteriori informazioni su come un amministratore può limitare l'accesso a tutti gli ambiti o agli ambiti sensibili e con restrizioni finché l'accesso non viene concesso esplicitamente all'ID client OAuth, consulta l'articolo del Centro assistenza Google Workspace Admin Specificare quali app di terze parti e interne possono accedere ai dati di Google Workspace.
invalid_client	(qualsiasi valore)	Il client OAuth o il token JWT non è valido o non è configurato correttamente. Per i dettagli, consulta la descrizione dell'errore.	Assicurati che il token JWT sia valido e contenga le rivendicazioni corrette. Verifica che l'account di servizio e il client OAuth siano configurati correttamente e che tu stia utilizzando l'indirizzo email corretto. Verifica che il token JWT sia corretto e sia stato emesso per il client ID nella richiesta.
deleted_client	(qualsiasi valore)	Il client OAuth utilizzato per effettuare la richiesta è stato eliminato. L'eliminazione può avvenire manualmente o automaticamente nel caso di client non utilizzati . I clienti eliminati possono essere ripristinati entro 30 giorni dall'eliminazione. Scopri di più.	Utilizza un ID client ancora attivo.
invalid_grant	Not a valid email.	L'utente non esiste.	Verifica che l'indirizzo email nella rivendicazione (campo) sub sia corretto.
invalid_grant	Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.	Solitamente, significa che l'ora del sistema locale non è corretta. Potrebbe verificarsi anche se il valore di exp è superiore a 65 minuti nel futuro rispetto al valore di iat, o se il valore di exp è inferiore al valore di iat.	Assicurati che l'orologio del sistema in cui viene generato il JWT sia corretto. Se necessario, sincronizza l'ora con Google NTP.
invalid_grant	Invalid JWT Signature.	L'asserzione JWT è firmata con una chiave privata non associata al service account identificato dall'email client o la chiave utilizzata è stata eliminata, disattivata o è scaduta. In alternativa, l'asserzione JWT potrebbe essere codificata in modo errato. Deve essere codificata in base64, senza nuove righe o segni di uguale di padding.	Decodifica il set di rivendicazioni JWT e verifica che la chiave che ha firmato l'asserzione sia associata al service account. Prova a utilizzare una libreria OAuth fornita da Google per assicurarti che il JWT venga generato correttamente.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Non sono stati richiesti ambiti (elenco degli ambiti vuoto) o uno degli ambiti richiesti non esiste (ovvero non è valido).	Assicurati che l'attestazione (campo) scope del JWT sia compilata e confronta gli ambiti che contiene con gli ambiti documentati per le API che vuoi utilizzare, per assicurarti che non ci siano errori o refusi. Tieni presente che l'elenco degli ambiti nell'attestazione scope deve essere separato da spazi, non da virgole.
disabled_client	The OAuth client was disabled.	La chiave utilizzata per firmare l'asserzione JWT è disattivata.	Vai a Google API Consolee, in IAM e amministrazione > Service account, attiva l'account di servizio che contiene l'ID chiave utilizzato per firmare l'asserzione.
org_internal	This client is restricted to users within its organization.	L'ID client OAuth nella richiesta fa parte di un progetto che limita l'accesso agli Account Google in un' organizzazione Google Cloud specifica.	Utilizza un service account dell'organizzazione per l'autenticazione. Conferma la configurazione del tipo di utente per la tua applicazione OAuth.

Addendum: autorizzazione tramite service account senza OAuth

Con alcune API di Google, puoi effettuare chiamate API autorizzate utilizzando un JWT firmato direttamente come token di autenticazione, anziché un token di accesso OAuth 2.0. Quando è possibile, puoi evitare di dover effettuare una richiesta di rete al server di autorizzazione di Google prima di effettuare una chiamata API.

Se l'API che vuoi chiamare ha una definizione di servizio pubblicata nel repository GitHub delle API di Google, puoi effettuare chiamate API autorizzate utilizzando un JWT anziché un token di accesso. Per farlo:

1. Crea un service account come descritto sopra. Assicurati di conservare il file JSON che ricevi quando crei l'account.
2. Utilizzando una libreria JWT standard, ad esempio quella disponibile su jwt.io, crea un JWT con un'intestazione e un payload come nell'esempio seguente:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "[e-mail]",
     "sub": "[e-mail]",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• Per il campo kid nell'intestazione, specifica l'ID della chiave privata del tuo account di servizio. Puoi trovare questo valore nel campo private_key_id del file JSON dell'account di servizio.
• Per i campi iss e sub, specifica l'indirizzo email del tuo service account. Puoi trovare questo valore nel campo client_email del file JSON del service account.
• Per il campo aud, specifica l'endpoint API. Ad esempio: https://SERVICE.googleapis.com/.
• Per il campo iat, specifica l'ora Unix corrente e per il campo exp, specifica l'ora esattamente 3600 secondi dopo, quando il JWT scadrà.

Firma il JWT con RSA-256 utilizzando la chiave privata presente nel file JSON del service account.

Ad esempio:

Java

Utilizzo di google-auth-library-java e java-jwt:

import com.google.auth.oauth2.ServiceAccountCredentials;
...
GoogleCredentials credentials =
        GoogleCredentials.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = ((ServiceAccountCredentials) credentials).getPrivateKey();
String privateKeyId = ((ServiceAccountCredentials) credentials).getPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("[e-mail]")
        .withSubject("[e-mail]")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Utilizzo di PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '[e-mail]',
           'sub': '[e-mail]',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. Chiama l'API utilizzando il JWT firmato come token di autenticazione:

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com

Implementare la Protezione su più account

Un ulteriore passaggio da intraprendere per proteggere gli account dei tuoi utenti è l'implementazione della protezione cross-account utilizzando il servizio di protezione cross-account di Google. Questo servizio ti consente di abbonarti alle notifiche degli eventi di sicurezza, che forniscono alla tua applicazione informazioni sulle modifiche principali all'account utente. Puoi quindi utilizzare le informazioni per intervenire a seconda di come decidi di rispondere agli eventi.

Ecco alcuni esempi dei tipi di eventi inviati alla tua app dal servizio di protezione cross-account di Google:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Per ulteriori informazioni su come implementare la protezione su più account e per l'elenco completo degli eventi disponibili, consulta la pagina Proteggere gli account utente con la protezione su più account .