Utilizzare OAuth 2.0 per le applicazioni server-server

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.
175 Per scoprire di più, consulta la panoramica sull'autenticazione nella documentazione di Google Cloud Platform.

Il sistema Google OAuth 2.0 supporta interazioni server-server come quelle tra un'applicazione web e un servizio Google. Per questo scenario, hai bisogno di un account di servizio, ovvero un account che appartiene alla tua applicazione anziché a un singolo utente finale. La tua applicazione chiama le API di Google per conto dell'account di servizio, quindi gli utenti non sono direttamente coinvolti. Tale scenario è detto a volte "OAuth a due vie", "2LO." Il termine correlato "&gt OAuth a tre vie" si riferisce agli scenari in cui la tua applicazione chiama le API di Google per conto degli utenti finali e in cui il consenso degli utenti è talvolta richiesto.

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

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

In questo documento viene spiegato in che modo un'applicazione può completare il flusso OAuth 2.0 server-server utilizzando una libreria client delle API di Google (opzione consigliata) o HTTP.

Panoramica

Per supportare le interazioni server-server, devi prima creare un account di servizio per il tuo progetto nella . 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.

Successivamente, l'applicazione si prepara a effettuare chiamate API autorizzate utilizzando le credenziali dell'account di servizio per richiedere un token di accesso al server di autenticazione OAuth 2.0.

Infine, la tua applicazione può utilizzare il token di accesso per le chiamate alle API di Google.

Creazione di un account di servizio

Le credenziali di un account di servizio includono un indirizzo email generato, univoco, e almeno una coppia di chiavi pubblica/privata. Se la delega a livello di dominio è abilitata, anche un ID client fa parte delle credenziali dell'account di servizio.

Se la tua applicazione viene eseguita su Google App Engine, viene creato automaticamente un account di servizio quando crei il tuo progetto.

Se la tua applicazione viene eseguita su Google Compute Engine, anche un account di servizio viene configurato automaticamente quando crei il tuo progetto, ma devi specificare gli ambiti a cui deve accedere la tua applicazione quando crei un'istanza di Google Compute Engine. Per ulteriori informazioni, consulta Preparazione di un'istanza a utilizzare gli account di servizio.

Se la tua applicazione non viene eseguita su Google App Engine o Google Compute Engine, devi ottenere queste credenziali nel . Per generare le credenziali dell'account di servizio o per visualizzare le credenziali pubbliche che hai già generato, procedi nel seguente modo:

First, create a service account:

  1. Open the Service accounts page.
  2. If prompted, select a project, or create a new one.
  3. Click  Create service account.
  4. Under Service account details, type a name, ID, and description for the service account, then click Create and continue.
  5. Optional: Under Grant this service account access to project, select the IAM roles to grant to the service account.
  6. Click Continue.
  7. Optional: Under Grant users access to this service account, add the users or groups that are allowed to use and manage the service account.
  8. Click Done.
  9. Click  Create key, then click Create.

Next, create a service account key:

  1. Click the email address for the service account you created.
  2. Click the Keys tab.
  3. In the Add key drop-down list, select Create new key.
  4. Click Create.

Your new public/private key pair is generated and downloaded to your machine; it serves as the only copy of the private key. You are responsible for storing it securely. If you lose this key pair, you will need to generate a new one.

Puoi tornare al API Console in qualsiasi momento per visualizzare l'indirizzo email, le impronte con chiave pubblica e altre informazioni oppure per generare altre coppie di chiavi pubblica/privata. Per ulteriori informazioni sulle credenziali dell'account di servizio in API Console, consulta la sezione Account di servizio nel API Console file della guida.

Prendi nota dell'indirizzo email dell'account di servizio e memorizza il file della chiave privata dell'account di servizio in una posizione accessibile alla tua applicazione. La tua applicazione li richiede per effettuare chiamate API autorizzate.

Delega dell'autorità a livello di dominio all'account di servizio

Se hai un account Google Workspace, un amministratore dell'organizzazione può autorizzare un'applicazione ad accedere ai dati degli utenti per conto degli utenti del 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 utilizza un account di servizio per accedere all'API Google Calendar per conto degli utenti. L'autorizzazione di un account di servizio ad accedere ai dati per conto degli utenti di un dominio è talvolta definita "autorità di delega a livello di dominio" in account di servizio.

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

  1. Nella 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 nuovo.
  4. Nel campo ID client, inserisci l'ID client dell'account di servizio. Puoi trovare l'ID client del tuo account di servizio in Service accounts page.
  5. Nel campo Ambiti OAuth (delimitati da virgole), inserisci l'elenco di ambiti a cui deve essere concessa l'accesso alla tua applicazione. Ad esempio, se l'applicazione richiede l'accesso completo a livello di dominio all'API Google Drive e a Google Calendar, inserisci: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
  6. Fai clic su Autorizza.

Ora la tua applicazione ha l'autorità per effettuare chiamate API come utenti nel tuo dominio (per "impersonare" Quando ti prepari a effettuare chiamate API autorizzate, specifichi l'utente che deve impersonare.

Preparazione per una chiamata API autorizzata

Java

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

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

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

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

Delegare l'autorità a livello di dominio

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

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("user@example.com");

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

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 dell'account di servizio e dagli ambiti a cui l'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 Platform, puoi utilizzare le credenziali predefinite dell'applicazione, che possono semplificare il processo.

  2. Delegare l'autorità a livello di dominio

    Se hai delegato l'accesso a livello di dominio all'account di servizio e vuoi impersonare un account utente, utilizza il metodo with_subject di un oggetto ServiceAccountCredentials esistente. Ad esempio:

    delegated_credentials = credentials.with_subject('user@example.org')

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

HTTP/REST

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

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

Le seguenti sezioni descrivono come completare questi passaggi.

Se la risposta include un token di accesso, puoi utilizzarlo per chiamare un'API Google. Se la risposta non include un token di accesso, la tua richiesta di token e il token JWT potrebbero non essere formattati correttamente oppure l'account di servizio potrebbe non disporre delle autorizzazioni per accedere agli ambiti richiesti.

Quando viene scaduto il token di accesso, l'applicazione genera un altro JWT, lo firma e richiede un altro token di accesso.

L'applicazione server utilizza un JWT per richiedere un token al server di autorizzazione di Google, quindi utilizza il token per chiamare un endpoint dell'API di Google. Non sono coinvolti utenti finali.

Il resto di questa sezione descrive le specifiche relative alla creazione di un JWT, alla firma del JWT, alla creazione della richiesta del token di accesso e alla gestione della risposta.

Creazione di un JWT

Un JWT è composto da tre parti: un'intestazione, un set di attestazioni e una firma. L'intestazione e il set di attestazioni sono oggetti JSON. Questi oggetti JSON sono serializzati su byte UTF-8, quindi codificati utilizzando la codifica Base64url. Questa codifica fornisce resilienza rispetto alle modifiche alla codifica a causa di operazioni di codifica ripetute. L'intestazione, il set di attestazioni e la firma sono concatenati tra loro con un punto (.).

Un JWT viene 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 due campi che indicano l'algoritmo di firma e il formato dell'asserzione. Entrambi i campi sono obbligatori e ogni campo ha un solo valore. Man mano che vengono introdotti altri algoritmi e formati, questa intestazione cambierà di conseguenza.

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

{"alg":"RS256","typ":"JWT"}

La rappresentazione Base64url è la seguente:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
Formare l'insieme di rivendicazioni JWT

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

Rivendicazioni obbligatorie

Le rivendicazioni obbligatorie nel set di rivendicazioni JWT sono mostrate di seguito. Possono essere visualizzate in qualsiasi ordine nella rivendicazione.

Nome Description
iss Indirizzo email dell'account di servizio.
scope Un elenco di autorizzazioni delimitati da spazi richieste dall'applicazione.
aud Un descrittore del target previsto dell'asserzione. Quando crei una richiesta del token di accesso, questo valore è sempre https://oauth2.googleapis.com/token.
exp La data di scadenza dell'asserzione, specificata in secondi dalle ore 00:00:00 UTC, del 1° gennaio 1970. Questo valore ha un massimo di 1 ora dopo la data di emissione.
iat L'ora in cui l'asserzione è stata emessa, specificata in secondi dalle 00:00:00 UTC, del 1° gennaio 1970.

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

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Ulteriori rivendicazioni

In alcuni casi aziendali, un'applicazione può utilizzare la delega a livello di dominio per agire per conto di un utente specifico in un'organizzazione. L'autorizzazione per eseguire questo tipo di furto d'identità deve essere concessa prima che un'applicazione possa impersonare un utente ed è generalmente gestita da un super amministratore. Per ulteriori informazioni, vedi Controllare l'accesso 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 nella rivendicazione JWT impostata come valore del campo sub.

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

Se un'applicazione non è autorizzata a impersonare un utente, la risposta a una richiesta del token di accesso che include il campo sub sarà un errore.

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

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "sub": "some.user@example.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Codifica del set di rivendicazioni JWT

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

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}
Elaborazione della firma

JSON Web Signature (JWS) è la specifica che guida i meccanismi di generazione della firma per 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 durante il calcolo della firma. L'unico algoritmo di firma supportato dal server di autorizzazione OAuth 2.0 di Google è RSA utilizzando l'algoritmo di hashing SHA-256. È indicato come RS256 nel campo alg nell'intestazione JWT.

Firma la rappresentazione UTF-8 dell'input utilizzando SHA256withRSA (noto 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 essere codificata in Base64url. L'intestazione, il set di attestazioni e la firma sono concatenati tra loro con un punto (.). Il risultato è il JWT. Il valore deve essere il seguente (aggiunta di interruzioni di riga per maggiore 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":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
"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 un JWT che è stato firmato ed è pronto per la trasmissione:

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

Invio della richiesta del token di accesso

Dopo aver generato il JWT firmato, un'applicazione può utilizzarlo per richiedere un token di accesso. Questa richiesta del token di accesso è una richiesta POST di HTTPS e il corpo ha una codifica URL. L'URL è il seguente:

https://oauth2.googleapis.com/token

Nella richiesta HTTPS di POST sono obbligatori i seguenti parametri:

Nome Description
grant_type Utilizza la seguente stringa, con codifica URL come necessario: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion JWT, inclusa la firma.

Di seguito è riportato un dump non elaborato della richiesta HTTPS POST utilizzato 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 viene riportata la stessa richiesta, che utilizza 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 token di accesso e JWT è formattata correttamente e l'account di servizio è autorizzato a eseguire l'operazione, la risposta JSON dal 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 il periodo di tempo specificato dal valore expires_in.

Chiamata delle API di Google

Java

Utilizza l'oggetto GoogleCredential 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 GoogleCredential. Ad esempio:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Invia richieste al servizio API utilizzando l'interfaccia fornita dall'oggetto servizio. Ad esempio, per elencare le istanze dei database Cloud SQL nell'interessante progetto 123-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. Per creare un oggetto di servizio devi richiamare 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 nell'interessante progetto 123-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 account di servizio o di un account utente se sono stati concessi gli ambiti di accesso richiesti dall'API. A tale scopo, includi il token di accesso in una richiesta all'API includendo un parametro di ricerca 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 visualizzarne gli ambiti in OAuth 2.0 Playground.

Esempi GET HTTP

Una chiamata all'endpoint drive.files (l'API Drive File) che utilizza l'intestazione HTTP Authorization: Bearer potrebbe avere il seguente aspetto. 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

Esempi di curl

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

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

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

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

Quando i token di accesso scadono

I token di accesso emessi dal server di autorizzazione Google OAuth 2.0 scadono dopo la durata specificata dal valore expires_in. Quando scade un token di accesso, 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
unauthorized_client Unauthorized client or scope in request. Se stai tentando di utilizzare la delega a livello di dominio, l'account di servizio non è autorizzato nella Console di amministrazione del dominio dell'utente.

Assicurati che l'account di servizio sia autorizzato nella pagina Delega a livello di dominio della Console di amministrazione per l'utente nella richiesta sub.

L'operazione di propagazione di tutti gli utenti al tuo Account Google richiede in genere pochi minuti, ma potrebbe essere necessario attendere fino a 24 ore.

unauthorized_client Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested. Un account di servizio è stato autorizzato utilizzando l'indirizzo email del 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 a livello di 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 nella rivendicazione sub (campo) e che includa tutti gli ambiti che richiedi nella richiesta scope del tuo JWT.

L'operazione di propagazione di tutti gli utenti al tuo Account Google richiede in genere pochi minuti, ma potrebbe essere necessario attendere fino a 24 ore.

invalid_grant Not a valid email. L'utente non esiste. Verifica che l'indirizzo email nella rivendicazione sub (campo) 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.

In genere, ciò significa che l'ora locale del sistema non è corretta. Può verificarsi anche se il valore exp è superiore a 65 minuti in futuro rispetto al valore iat o se il valore di exp è inferiore a quello di iat.

Assicurati che l'orologio del sistema in cui viene generato il JWT sia corretto. Se necessario, sincronizza il tuo tempo con Google NTP.

invalid_grant Invalid JWT Signature.

L'asserzione JWT è firmata con una chiave privata non associata all'account di servizio identificato dall'email del client oppure la chiave utilizzata è stata eliminata, disabilitata o è scaduta.

In alternativa, l'asserzione JWT potrebbe essere codificata in modo errato. Deve essere codificata in Base64, senza nuove righe o spaziature uguali.

Decodifica il set di attestazioni JWT e verifica la chiave che ha firmato l'asserzione è associata all'account di servizio.

Prova a utilizzare una libreria OAuth fornita da Google per assicurarti che il JWT sia generato correttamente.

invalid_scope Invalid OAuth scope or ID token audience provided. Non è stato richiesto alcun ambito (elenco vuoto di ambiti) oppure non esiste uno degli ambiti richiesti (ovvero non valido).

Verifica che la dichiarazione scope (campo) di JWT sia completata e confronta gli ambiti che contiene con gli ambiti documentati per le API che vuoi utilizzare, per assicurarti che non ci siano errori o errori di battitura.

Tieni presente che l'elenco degli ambiti della dichiarazione scope deve essere separato da spazi, non da virgole.

disabled_client The OAuth client was disabled. La chiave utilizzata per firmare l'asserzione JWT è disabilitata.

Vai alla sezione Google API Consolee in IAM e AMP Amministratore > Account di servizio, attiva l'account di servizio che contiene "&ID; chiave ID" utilizzato per firmare l'asserzione.

Addendum: autorizzazione dell'account di servizio senza OAuth

Con alcune API di Google, puoi effettuare chiamate autorizzate alle API utilizzando un token JWT firmato direttamente come token di connessione, anziché un token di accesso OAuth 2.0. Quando è possibile, puoi evitare di 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 account di servizio come descritto sopra. Assicurati di conservare il file JSON che ricevi quando crei l'account.
  2. Utilizzando una qualsiasi libreria JWT standard, ad esempio quella trovata in jwt.io, crea un JWT con un'intestazione e un payload come il seguente esempio:
    {
      "alg": "RS256",
      "typ": "JWT",
      "kid": "abcdef1234567890"
    }
    .
    {
      "iss": "123456-compute@developer.gserviceaccount.com",
      "sub": "123456-compute@developer.gserviceaccount.com",
      "aud": "https://firestore.googleapis.com/",
      "iat": 1511900000,
      "exp": 1511903600
    }
    • Per il campo kid nell'intestazione, specifica l'ID 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 dell'account di servizio. Puoi trovare questo valore nel campo client_email del file JSON dell'account di servizio.
    • 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, l'ora esattamente 3600 secondi dopo, quando scadrà il JWT.

Firma il JWT con RSA-256 utilizzando la chiave privata presente nel file JSON dell'account di servizio.

Ad esempio:

Java

Utilizzando google-api-java-client e java-jwt:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

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

Python

Se utilizzi PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '123456-compute@developer.gserviceaccount.com',
           'sub': '123456-compute@developer.gserviceaccount.com',
           '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 connessione:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com