Utilizzo di OAuth 2.0 per le applicazioni da server a server

Il sistema Google OAuth 2.0 supporta le interazioni server-to-server, come quelle tra un server web un'applicazione e un servizio Google. Per questo scenario, ti serve un account di servizio, che è un account che appartiene alla tua applicazione anziché a un singolo utente finale. Il tuo l'applicazione chiama le API di Google per conto dell'account di servizio, quindi gli utenti non vengono coinvolti. Questo scenario è talvolta chiamato "OAuth a due vie" o "2LO". (Il termine correlato "OAuth a tre vie" si riferisce agli scenari in cui la tua applicazione chiama le API di Google per conto degli utenti finali e per i quali talvolta è richiesto il consenso dell'utente.

In genere, un'applicazione utilizza un account di servizio quando utilizza le API di Google per funzionare con i propri dati, anziché con quelli di un utente. Ad esempio, un'applicazione che utilizza Google Cloud Datastore per la persistenza dei dati utilizzerà un account di servizio per autenticare le sue chiamate al API Google Cloud Datastore.

Gli amministratori di dominio di Google Workspace possono inoltre concedere agli account di servizio l'autorità a livello di dominio di accedere all'utente per conto degli utenti del dominio.

Questo documento descrive come 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-to-server, crea prima un account di servizio per il progetto in il API Console. Se vuoi accedere ai dati degli utenti in il tuo account Google Workspace, poi delega l'accesso a livello di dominio all'account di servizio.

Quindi, l'applicazione si prepara a effettuare chiamate API autorizzate utilizzando il metodo le credenziali per richiedere un token di accesso al server di autenticazione OAuth 2.0.

Infine, l'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 email generato, univoco e di 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 configurato automaticamente un account di servizio per creare il tuo progetto.

Se la tua applicazione viene eseguita su Google Compute Engine, viene configurato anche un account di servizio automaticamente quando crei il progetto, ma devi specificare gli ambiti applicazione richiede l'accesso quando crei un'istanza di Google Compute Engine. Per maggiori informazioni le informazioni, vedi Preparazione di un'istanza per l'utilizzo degli 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. Generare un account di servizio o per visualizzare le credenziali pubbliche che hai già generato:

首先,创建一个服务帐户:

  1. 打开 Service accounts page
  2. If prompted, select a project, or create a new one.
  3. 单击创建服务帐户
  4. Service account details下,键入服务帐户的名称、ID 和描述,然后点击Create and continue
  5. 可选:在Grant this service account access to project下,选择要授予服务帐户的 IAM 角色。
  6. 单击继续
  7. 可选:在Grant users access to this service account下,添加允许使用和管理服务帐户的用户或组。
  8. 单击完成

接下来,创建一个服务帐户密钥:

  1. 单击您创建的服务帐户的电子邮件地址。
  2. 单击密钥选项卡。
  3. 添加密钥下拉列表中,选择创建新密钥
  4. 单击创建

您的新公钥/私钥对已生成并下载到您的机器上;它作为私钥的唯一副本。您有责任安全地存储它。如果您丢失了这个密钥对,您将需要生成一个新的。

Puoi tornare allo API Console in qualsiasi momento per visualizzare l'indirizzo email, pubblico le impronte digitali delle chiavi e altre informazioni o per generare altre coppie di chiavi pubbliche/private. Per per ulteriori dettagli sulle credenziali degli account di servizio API Console, vedi Account di servizio in API Console della guida.

Prendi nota dell'indirizzo email dell'account di servizio e memorizza la chiave privata dell'account di servizio in una posizione accessibile alla tua applicazione. La tua applicazione ha bisogno che di chiamate API autorizzate.

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

Utilizzando un account Google Workspace, un amministratore di Workspace dell'organizzazione può autorizzare una per accedere ai dati utente di Workspace 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 in un dominio Google Workspace userebbe un account di servizio per accedere all'API Google Calendar su 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à delegata a livello di dominio" a un account di servizio.

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

  1. Dal dominio del tuo dominio Google Workspace Console di amministrazione, vai al 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 visualizzare l'ID client dell'account di servizio Service accounts page.
  5. Nel campo Ambiti OAuth (delimitato da virgole), inserisci l'elenco di ambiti che il tuo l'accesso all'applicazione. Ad esempio, se la tua applicazione ha bisogno di tutto il dominio inserisci l'accesso completo all'API Google Drive e all'API Google Calendar, inserisci: https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
  6. Fai clic su Autorizza.

La tua applicazione ora dispone dell'autorità per effettuare chiamate API come utenti del tuo dominio Workspace (per "simula l'identità" utenti). Quando ti prepari a effettuare queste chiamate API delegati, specificherai esplicitamente che l'utente deve si spaccia per te.

Preparazione per effettuare una chiamata API delegata

Java

Dopo aver ottenuto l'indirizzo email e la chiave privata del client dal API Console, usa Libreria client delle API di Google per Java creare un oggetto GoogleCredential dalle credenziali dell'account di servizio e gli ambiti a cui l'applicazione deve accedere. 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 sulla piattaforma Google Cloud, puoi utilizzare credenziali predefinite dell'applicazione il che può semplificare il processo.

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, specifica l'indirizzo email dell'account utente con Metodo createDelegated dell'oggetto GoogleCredential. Per esempio:

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

Il codice riportato sopra utilizza l'oggetto GoogleCredential per chiamare il relativo createDelegated() . L'argomento del metodo createDelegated() deve essere un utente che appartiene al tuo Workspace. Il codice che effettua la richiesta utilizzerà questa credenziale per chiamare Google le API utilizzando il tuo account di servizio.

Python

Dopo aver ottenuto l'indirizzo email e la chiave privata del client dal API Console, usa Libreria client delle API di Google per Python per completare questi passaggi:

  1. Crea un oggetto Credentials dalle credenziali dell'account di servizio gli 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 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 vuoi rappresentare un account utente, usa il metodo with_subject di un Oggetto ServiceAccountCredentials. Ad 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 dal API Console, la tua richiesta deve completare seguenti passaggi:

  1. Creare un token web JSON (JWT, pronunciato, "jot") che includa un'intestazione, un set di attestazioni e una firma.
  2. Richiedi un token di accesso al server di autorizzazione OAuth 2.0 di Google.
  3. Gestire 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 accesso token, la richiesta JWT e il token non sono formate correttamente oppure l'account di servizio potrebbe non disponi dell'autorizzazione per accedere agli ambiti richiesti.)

Quando il token di accesso scade, l'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 all'account Google
                  Authorization Server, poi utilizza il token per chiamare un endpoint API di Google. No
                  è coinvolto l'utente finale.

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

Creazione di un JWT

Un JWT è composto da tre parti: un'intestazione, un insieme di attestazioni e un firma. L'intestazione e il set di attestazioni sono oggetti JSON. Questi oggetti JSON sono serializzati Byte UTF-8, quindi codificati utilizzando la codifica Base64url. Questa codifica fornisce resilienza contro le modifiche di codifica dovute a ripetute operazioni di codifica. L'intestazione, l'insieme di attestazioni sono concatenate da 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}
Creazione dell'intestazione JWT

L'intestazione è composta da tre campi che indicano l'algoritmo di firma, il formato l'asserzione e l'[ID chiave dell'account di servizio key](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) utilizzato per firmare il JWT. Algoritmo e formato sono obbligatori e ogni campo ha solo un solo valore. Con l'introduzione di altri algoritmi e formati, questa intestazione cambierà di conseguenza. L'ID chiave è facoltativo e, se viene specificato un ID chiave errato, Google Cloud proverà a tutte le chiavi associate all'account di servizio per verificare il token e rifiutarlo se non è stata trovata alcuna chiave valida. Google si riserva il diritto di rifiutare i token con ID chiave errati in futuro.

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", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

La rappresentazione Base64url di questo comando è la seguente:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=
Creazione dell'insieme di attestazioni JWT

L'insieme di attestazioni JWT contiene informazioni sul JWT, tra cui le autorizzazioni richiesto (ambiti), il target 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, L'insieme di attestazioni JWT è un oggetto JSON e viene utilizzato nel calcolo della firma.

Rivendicazioni obbligatorie

Le dichiarazioni obbligatorie nell'insieme di attestazioni JWT sono mostrate di seguito. Possono essere visualizzati in qualsiasi ordine in: l'insieme delle attestazioni.

Nome Descrizione
iss L'indirizzo email dell'account di servizio.
scope Un elenco delle autorizzazioni richieste dall'applicazione, delimitate da spazi.
aud Un descrittore del target previsto dell'asserzione. Quando crei un token di accesso questo valore è sempre https://oauth2.googleapis.com/token.
exp La scadenza dell'asserzione, specificata in secondi dalle ore 00:00:00 UTC. 1° gennaio 1970. Questo valore presenta al massimo un'ora dopo l'ora di emissione.
iat L'ora di emissione dell'asserzione, specificata in secondi dalle ore 00:00:00 UTC. 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
}
Rivendicazioni aggiuntive

In alcuni casi aziendali, un'applicazione può utilizzare la delega a livello di dominio per agire per conto di un determinato utente in un'organizzazione. Autorizzazione a eseguire questo tipo di rappresentazione deve essere concessa prima che un'applicazione possa impersonare un utente e solitamente è gestita da un come super amministratore. Per ulteriori informazioni, vedi Controlla l'accesso all'API con la delega a livello di dominio.

Per ottenere un token di accesso che conceda a un'applicazione l'accesso delegato a una risorsa, includi l'indirizzo email dell'utente nell'attestazione JWT impostata come valore del parametro campo sub.

Nome Descrizione
sub L'indirizzo email dell'utente per il quale l'applicazione ha richiesto la delega l'accesso.

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

Viene mostrato un esempio di set di attestazioni JWT che include il campo sub sotto:

{
  "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 dell'insieme di attestazioni JWT

Come per l'intestazione JWT, il set di attestazioni JWT deve essere serializzato in UTF-8 e sicuro Base64url codificati. 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 in corso...

Firma web JSON (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. La solo l'algoritmo di firma supportato dal server di autorizzazione OAuth 2.0 di Google utilizza RSA Algoritmo di hashing SHA-256. Questo valore viene espresso come RS256 nel 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 il Google API Console. L'output sarà un array di byte.

La firma deve quindi essere codificata come Base64url. L'intestazione, l'insieme di rivendicazioni e la firma sono concatenate con un punto (.). Il risultato è il JWT. it devono essere i seguenti (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

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 di token di accesso è una richiesta POST HTTPS e il corpo è un URL codificati. L'URL è il seguente:

https://oauth2.googleapis.com/token

Nella richiesta HTTPS POST sono obbligatori i seguenti parametri:

Nome Descrizione
grant_type Usa la seguente stringa, codificata nell'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 POST HTTPS utilizzata in un token di accesso richiesta:

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, 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 il JWT e la richiesta del token di accesso sono formati correttamente e l'account di servizio ha l'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 Valore expires_in.

Chiamata alle API di Google

Java

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

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

Python

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

  1. Crea un oggetto di servizio per l'API che vuoi chiamare. Crei un oggetto di servizio chiamando la funzione build con il nome e la versione dell'API e oggetto Credentials autorizzato. Ad esempio, per richiamare la versione 1beta3 del API Cloud SQL Administration:
    import googleapiclient.discovery
    
    sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)
  2. Effettuare richieste al servizio API utilizzando fornita dall'oggetto di servizio. Ad esempio, per elencare le istanze dei database Cloud SQL nella serie entusiasmante-example-123 progetto:
    response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Una volta che l'applicazione ha ottenuto un token di accesso, puoi utilizzarlo per effettuare chiamate a un per conto di un determinato account di servizio, 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 mediante l'inclusione di una query access_token o un valore Bearer dell'intestazione HTTP Authorization. Se possibile, è preferibile utilizzare l'intestazione HTTP, in quanto le stringhe di query tendono a essere visibili nei log del server. Nella maggior parte dei casi, casi puoi utilizzare una libreria client per configurare le chiamate alle API di Google (ad esempio, chiamata all'API Drive Files).

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

Esempi GET HTTP

Una chiamata al drive.files (l'API Drive Files) utilizzando il protocollo Authorization: Bearer potrebbe avere il seguente aspetto. Tieni presente che devi specificare un 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 access_token parametro della stringa di query:

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

Oppure, in alternativa, l'opzione del parametro della 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 questa durata fornita dal valore expires_in. Quando un token di accesso scade, dovrebbe 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 in alla Console di amministrazione del dominio dell'utente.

Assicurati che l'account di servizio sia autorizzato nel Pagina di delega a livello di dominio della Console di amministrazione per l'utente nella Rivendicazione sub (campo).

In genere questa operazione richiede alcuni minuti, ma potrebbero essere necessarie fino a 24 ore prima che l'autorizzazione si propagano 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. Nel 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 nel Pagina di delega a livello di dominio della Console di amministrazione per l'utente nella sub (campo) e che includa tutti gli ambiti richiesti nella dichiarazione scope del tuo JWT.

In genere questa operazione richiede alcuni minuti, ma potrebbero essere necessarie fino a 24 ore prima che l'autorizzazione si propagano a tutti gli utenti nel tuo Account Google.

admin_policy_enforced (qualsiasi valore) L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa dell'amministratore di Google Workspace.

Consulta l'articolo del Centro assistenza per amministratori di Google Workspace Controllare quali terze parti e quali app interne accedono ai dati di Google Workspace per ulteriori informazioni su come può limitare l'accesso a tutti gli ambiti o a tutti gli ambiti sensibili e con restrizioni finché l'accesso viene concesso esplicitamente al tuo ID client OAuth.

invalid_client (qualsiasi valore)

Il client OAuth o il token JWT non sono validi o sono configurati in modo errato.

Per maggiori dettagli, consulta la descrizione dell'errore.

Assicurati che il token JWT sia valido e contenga le attestazioni corrette.

Verifica che il client e l'account di servizio OAuth siano configurato correttamente e che l'indirizzo email utilizzato sia corretto.

Verifica che il token JWT sia corretto e che sia stato emesso per l'ID client nel richiesta.

invalid_grant Not a valid email. L'utente non esiste. Verifica che l'indirizzo email nel reclamo (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 anche verificarsi se Il valore exp è superiore a 65 minuti nel futuro rispetto al valore iat, o il valore exp è inferiore al valore iat.

Accertati che l'orologio sul sistema in cui viene generato il JWT sia corretto. Se necessarie, 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 identificata dall'email del client o che la chiave utilizzata è stata eliminata, disattivata o è scaduto.

In alternativa, l'asserzione JWT potrebbe essere codificata in modo errato. Deve essere Codifica Base64, senza segni di uguale in corrispondenza di ritorni a capo o spaziatura interna.

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

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 è stato richiesto alcun ambito (elenco degli ambiti vuoto) oppure uno degli ambiti richiesti non lo è esistenti (ovvero non validi).

Assicurati che l'attestazione scope (campo) del JWT sia compilata e confronta gli ambiti che contiene con quelli documentati per le API che vuoi utilizzare, assicurati che non ci siano errori o di battitura.

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

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

Vai al Google API Consolee nella sezione IAM e Amministratore > Account di servizio, abilita l'account di servizio che contiene l'"ID chiave" in uso 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 a Google Account in una specifica Organizzazione Google Cloud.

Utilizza un account di servizio dell'organizzazione per l'autenticazione. Conferma il tipo di utente configurazione della tua applicazione OAuth.

Appendice: autorizzazione dell'account di servizio senza OAuth

Con alcune API di Google, puoi effettuare chiamate API autorizzate utilizzando un JWT firmato direttamente come di connessione, anziché un token di accesso OAuth 2.0. Quando è possibile, evita di avere per 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 e conserva il file JSON che ricevi quando crei l'account.
  2. Utilizzando qualsiasi libreria JWT standard, ad esempio quella che si trova in jwt.io, crea un JWT con un'intestazione e payload come nell'esempio seguente:
    {
      "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 la chiave privata dell'account di servizio ID. Puoi trovare questo valore nel campo private_key_id del tuo account di servizio JSON.
    • Per i campi iss e sub, specifica l'indirizzo email del tuo account di servizio . Puoi trovare questo valore nel campo client_email del tuo servizio di accesso al file JSON di destinazione.
    • Per il campo aud, specifica l'endpoint API. Ad esempio: https://SERVICE.googleapis.com/.
    • Per il campo iat, specifica l'ora Unix attuale e per il exp, specifica l'ora esatta, a distanza di 3600 secondi, quando il JWT scadono.

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

Ad esempio:

Java

Utilizzo 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

Con 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

Implementare la Protezione su più account

Un ulteriore passaggio da seguire per proteggere i tuoi utenti che stanno implementando più account Protezione con l'utilizzo del servizio di protezione su più account di Google. Questo servizio ti consente iscriviti alle notifiche di eventi di sicurezza che forniscono informazioni alla tua applicazione su modifiche importanti all'account utente. Puoi quindi utilizzare le informazioni per intervenire in base al come decidi di rispondere agli eventi.

Ecco alcuni esempi di tipi di eventi inviati alla tua app dal Servizio di protezione su più 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

Consulta le Proteggere gli account utente con la pagina Protezione su più account . per ulteriori informazioni su come implementare la Protezione su più account e per l'elenco completo degli eventi disponibili.