Google si impegna a promuovere l'equità razziale per le comunità nere. Vedi come.

Utilizzo di OAuth 2.0 per applicazioni da server a server

Il sistema Google OAuth 2.0 supporta le interazioni da server a server come quelle tra un'applicazione web e un servizio Google. Per questo scenario è necessario un account di servizio , che è 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. Questo scenario è talvolta chiamato "OAuth a due vie" o "2LO". (Il termine correlato "OAuth a tre vie" si riferisce a scenari in cui l'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 account di servizio quando l'applicazione utilizza le API di Google per lavorare con i propri dati anziché con i dati di un utente. Ad esempio, un'applicazione che utilizza Google Cloud Datastore per la persistenza dei dati utilizzerebbe un account di servizio per autenticare le sue chiamate all'API di Google Cloud Datastore.

Gli amministratori di dominio di Google Workspace possono anche concedere agli account di servizio l'autorità a livello di dominio di accedere ai dati degli utenti per conto degli utenti 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.

Panoramica

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

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

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

Creazione di un account di servizio

Le credenziali di un account di servizio includono un indirizzo e-mail generato che è 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, un account di servizio viene impostato automaticamente quando crei il tuo progetto.

Se la tua applicazione viene eseguita su Google Compute Engine, anche un account di servizio viene impostato automaticamente quando crei il tuo progetto, ma devi specificare gli ambiti a cui l'applicazione deve accedere quando crei un'istanza di Google Compute Engine. Per ulteriori informazioni, vedere Preparazione di un'istanza per 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 Google API Console. Per generare le credenziali dell'account di servizio o per visualizzare le credenziali pubbliche che hai già generato, procedi come segue:

  1. Aprire Service accounts page .
  2. If prompted, select a project, or create a new one.
  3. Fai clic su account di servizio .
  4. In Dettagli account servizio , digitare un nome, ID e descrizione per l'account del servizio, quindi fare clic su Crea .
  5. Facoltativo: in Autorizzazioni account servizio , selezionare i ruoli IAM da concedere all'account del servizio, quindi fare clic su Continua .
  6. Facoltativo: in Concedi agli utenti l'accesso a questo account di servizio , aggiungere gli utenti o i gruppi autorizzati a utilizzare e gestire l'account di servizio.
  7. Fai clic su chiave di creazione , quindi fai clic su Crea .

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

Se devi concedere l' autorizzazione a livello di dominio G Suite all'account del servizio, fai clic sull'indirizzo email dell'account del servizio che hai creato, quindi copia il valore dalla casella ID univoco .

Per delegare l'autorizzazione all'account del servizio, utilizzare il valore copiato come ID client.

È possibile tornare a API Console in qualsiasi momento per visualizzare l'indirizzo e-mail, le impronte digitali della chiave pubblica e altre informazioni o per generare ulteriori coppie di chiavi pubbliche / private. Per ulteriori dettagli sulle credenziali dell'account di servizio in API Console, vedere Account di servizio nel file della guida API Console.

Prendi nota dell'indirizzo e-mail dell'account di servizio e archivia il file della chiave privata dell'account di servizio in una posizione accessibile alla tua applicazione. La tua applicazione ne ha bisogno per effettuare chiamate API autorizzate.

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

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

Per delegare l'autorità a livello di dominio a un account di servizio, abilitare prima la delega a livello di dominio per un account di servizio esistente in Service accounts page o creare un nuovo account di servizio con la delega a livello di dominio abilitata.

Quindi, un super amministratore del dominio Google Workspace deve completare i seguenti passaggi:

  1. Da del dominio Google area di lavoro della Console di amministrazione , andare al menu principale > Sicurezza> Controlli API.
  2. Nel riquadro Delega a livello di dominio , seleziona Gestisci delega a livello di dominio .
  3. Fare clic su Aggiungi nuovo .
  4. Nel campo ID cliente , inserisci l' ID cliente dell'account di servizio. Puoi trovare l'ID client del tuo account di servizio nel Service accounts page.
  5. Nel campo Ambiti OAuth (delimitati da virgole) , inserisci l'elenco degli ambiti a cui deve essere concesso l'accesso all'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 / calendario .
  6. Fare clic su Autorizza .

La tua applicazione ora ha l'autorità per effettuare chiamate API come utenti nel tuo dominio (per "impersonare" utenti). Quando ti prepari a effettuare chiamate API autorizzate, specifichi l'utente da impersonare.

Preparazione per effettuare una chiamata API autorizzata

Giava

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 la tua applicazione deve accedere. Per 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 invece utilizzare le credenziali predefinite dell'applicazione , il che può semplificare il processo.

Delegare l'autorità a livello di dominio

Se è stato delegato l'accesso a livello di dominio per l'account del servizio e si desidera impersonare un account utente, specificare l'indirizzo e-mail dell'account utente con il createDelegated metodo GoogleCredential dell'oggetto. Per 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.

Pitone

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 invece utilizzare le credenziali predefinite dell'applicazione , il che può 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 desideri impersonare un account utente, utilizza il metodo with_subject di un oggetto ServiceAccountCredentials esistente. Per esempio:

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

Utilizza l'oggetto Credentials 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, "jot") che includa un'intestazione, un set di attestazioni e una firma.
  2. Richiedi un token di accesso dal server di autorizzazione di Google OAuth 2.0.
  3. Gestisci la risposta JSON restituita dal server di autorizzazione.

Le sezioni che seguono descrivono come completare questi passaggi.

Se la risposta include un token di accesso, puoi utilizzare il token di accesso per chiamare un'API di Google . (Se la risposta non include un token di accesso, la tua richiesta JWT e token potrebbe non essere formata correttamente o l'account del 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.

La tua applicazione server utilizza un JWT per richiedere un token dal server di autorizzazione di Google, quindi utilizza il token per chiamare un endpoint dell'API di Google. Nessun utente finale è coinvolto.

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

Creazione di un JWT

Un JWT è composto da tre parti: un'intestazione, una serie di attestazioni e una firma. L'intestazione e il set di attestazioni sono oggetti JSON. Questi oggetti JSON vengono serializzati in byte UTF-8, quindi codificati utilizzando la codifica Base64url. Questa codifica fornisce resilienza contro le modifiche alla codifica dovute a operazioni di codifica ripetute. L'intestazione, il set di attestazioni e la firma vengono concatenati insieme a un carattere 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 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 algoritmi e formati aggiuntivi, questa intestazione cambierà di conseguenza.

Gli account di servizio 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"}

La rappresentazione Base64url di questo è la seguente:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
Formazione del set di attestazioni JWT

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

Richieste richieste

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

Nome Descrizione
iss L'indirizzo e-mail dell'account di servizio.
scope Un elenco delimitato da spazi delle autorizzazioni richieste dall'applicazione.
aud Un descrittore dell'obiettivo 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 dalle 00:00:00 UTC, 1 gennaio 1970. Questo valore ha un massimo di 1 ora dopo l'ora emessa.
iat L'ora in cui è stata emessa l'asserzione, specificata in secondi dalle 00:00:00 UTC, 1 gennaio 1970.

La rappresentazione JSON dei campi obbligatori in un set di attestazioni JWT è mostrata di seguito:

{
  "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
}
Reclami aggiuntivi

In alcuni casi aziendali, un'applicazione può utilizzare la delega a livello di dominio per agire per conto di un particolare utente in un'organizzazione. L'autorizzazione per eseguire questo tipo di rappresentazione deve essere concessa prima che un'applicazione possa impersonare un utente e in genere viene gestita da un super amministratore. Per ulteriori informazioni, consulta Controllare l'accesso API con delega a livello di dominio .

Per ottenere un token di accesso che concede a un'applicazione l'accesso delegato a una risorsa, includere l'indirizzo di posta elettronica dell'utente nell'attestazione JWT impostata come valore del sub .

Nome Descrizione
sub L'indirizzo di posta elettronica dell'utente per il quale l'applicazione richiede l'accesso delegato.

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

Di seguito è mostrato un esempio di un insieme di attestazioni JWT che include il 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 attestazioni JWT

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

{
  "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com",
  "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 i meccanismi di generazione della firma per JWT. L'input per la firma è l'array di byte del seguente contenuto:

{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 di Google OAuth 2.0 è RSA che utilizza l'algoritmo di hashing SHA-256. Questo è espressa come RS256 nel alg campo nell'intestazione JWT.

Firmare 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 quindi essere codificata Base64url. L'intestazione, il set di attestazioni e la firma vengono concatenati insieme a un carattere punto ( . ). Il risultato è il JWT. Dovrebbe 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 un 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

Effettuare la richiesta del 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 in URL. L'URL è mostrato 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 come necessario: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion Il JWT, inclusa la firma.

Di seguito è riportato un dump grezzo della richiesta POST HTTPS 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 è 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

Gestire la risposta

Se il JWT e la richiesta del token di accesso sono formati correttamente e l'account del servizio dispone dell'autorizzazione per eseguire l'operazione, la risposta JSON dal server di autorizzazione include un token di accesso. Quello che segue è 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 .

Chiamare le API di Google

Giava

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

  1. Crea un oggetto servizio per l'API che desideri chiamare utilizzando l'oggetto GoogleCredential . Ad esempio:
    SQLAdmin sqladmin =
        new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();
  2. Effettuare richieste al servizio API utilizzando l' interfaccia fornita dall'oggetto servizio . Ad esempio, per elencare le istanze dei database Cloud SQL nel progetto emozionante-esempio-123:
    SQLAdmin.Instances.List instances =
        sqladmin.instances().list("exciting-example-123").execute();

Pitone

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

  1. Crea un oggetto servizio per l'API che desideri chiamare. Si crea un oggetto 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 di amministrazione di Cloud SQL:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Effettuare richieste al servizio API utilizzando l' interfaccia fornita dall'oggetto servizio . Ad esempio, per elencare le istanze dei database Cloud SQL nel progetto emozionante-esempio-123:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP / REST

Dopo che la tua applicazione ha ottenuto un token di accesso, puoi utilizzare il token per effettuare chiamate a un'API di Google per conto di un determinato account di servizio o account utente se sono stati concessi gli ambiti di accesso richiesti dall'API. A tale scopo, includere il token di accesso in una richiesta all'API includendo un parametro di query access_token o un valore Bearer dell'intestazione HTTP di Authorization . Quando possibile, è preferibile l'intestazione HTTP, perché le stringhe di query tendono ad 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 di Drive Files ).

Puoi provare tutte le API di Google e visualizzarne gli ambiti in OAuth 2.0 Playground .

Esempi di HTTP GET

Una chiamata all'endpoint drive.files (l'API di 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

esempi di curl

È possibile testare questi comandi con l'applicazione della 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

Oppure, in alternativa, 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 di 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 di error campo error_description Senso 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 rivendicazione sub (campo).

Sebbene in genere siano necessari alcuni minuti, potrebbero essere necessarie fino a 24 ore prima che l'autorizzazione si propaghi a tutti gli utenti nel 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 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 stai richiedendo nella dichiarazione di scope del tuo JWT.

Sebbene in genere siano necessari alcuni minuti, potrebbero essere necessarie fino a 24 ore prima che l'autorizzazione si propaghi a tutti gli utenti nel tuo account Google.

invalid_grant Not a valid email. L'utente non esiste. Verifica che l'indirizzo e-mail 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.

Di solito, significa che l'ora del sistema locale non è corretta. Potrebbe anche accadere se il valore exp è più di 65 minuti in futuro dal valore iat , o il valore exp è inferiore al valore 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'e-mail del client.

In alternativa, l'asserzione JWT potrebbe essere codificata in modo errato: deve essere codificata in Base64, senza newline o caratteri di uguale riempimento.

Decodificare il set di attestazioni JWT e verificare che la chiave che ha firmato l'asserzione sia 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 sono stati richiesti ambiti (elenco vuoto di ambiti) o uno degli ambiti richiesti non esiste (ovvero non è valido).

Assicurati che l' scope (campo) del JWT sia popolata e confronta gli ambiti che contiene con gli ambiti documentati per le API che desideri utilizzare, per assicurarti che non ci siano errori o refusi.

Si noti che l'elenco di ambiti nella dichiarazione di 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 a Google API Console e in IAM e amministrazione> Account di servizio , abilita l'account di servizio che contiene l '"ID chiave" utilizzato per firmare l'asserzione.

Addendum: autorizzazione dell'account di servizio senza OAuth

Con alcune API di Google, puoi effettuare chiamate API autorizzate utilizzando un JWT firmato direttamente come token di connessione, anziché un token di accesso OAuth 2.0. Quando ciò è 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 desideri chiamare ha una definizione del servizio pubblicata nel repository GitHub delle API di Google , puoi effettuare chiamate API autorizzate utilizzando un JWT invece di un token di accesso. Fare così:

  1. Crea un account di servizio come descritto sopra. Assicurati di conservare il file JSON che ottieni quando crei l'account.
  2. Utilizzando qualsiasi libreria JWT standard, come quella trovata su 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 della chiave privata del tuo account di servizio. Puoi trovare questo valore nel campo private_key_id del tuo file JSON dell'account di servizio.
    • Per i campi iss e sub , specifica l'indirizzo email del tuo account di servizio. È possibile 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 , specificare l'ora Unix corrente e per il campo exp , specificare l'ora esattamente 3600 secondi dopo, quando scadrà il JWT.

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

Per esempio:

Giava

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 ...

Pitone

Utilizzando 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 portatore:
    GET /v1/projects/abc/databases/123/indexes HTTP/1.1
    Authorization: Bearer SIGNED_JWT
    Host: firestore.googleapis.com