Questa pagina è stata tradotta dall'API Cloud Translation.

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'applicazione web e un servizio Google. In questo caso, devi avere un account di servizio, ovvero un account che appartiene all'applicazione anziché a un singolo utente finale. La tua applicazione chiama le API di Google per conto dell'account di servizio, in modo che gli utenti non siano coinvolti direttamente. Questo scenario viene talvolta chiamato "Due vie OAuth" 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 in cui a volte è richiesto il consenso dell'utente).

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 di un utente. Ad esempio, un'applicazione che utilizza Google Cloud Datastore per la persistenza dei dati userebbe un account di servizio per autenticare le sue chiamate all'API Google Cloud Datastore.

Gli amministratori di dominio di Google Workspace possono anche consentire agli account di servizio a livello di dominio di accedere ai dati degli utenti 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-server, crea prima un account di servizio per il tuo progetto in API Console. Se vuoi accedere ai dati utente per gli utenti del tuo account Google Workspace, delega l'accesso a livello di dominio all'account di servizio.

Quindi, 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 chiamare le API di Google.

Creazione di un account di servizio

Le credenziali di un account di servizio includono un indirizzo email 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, quando crei il progetto viene configurato automaticamente un account di servizio.

Se la tua applicazione viene eseguita su Google Compute Engine, anche un account di servizio viene configurato automaticamente quando crei il progetto, ma devi specificare gli ambiti a cui la tua applicazione deve accedere quando crei un'istanza di Google Compute Engine. Per scoprire di più, consulta 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 nella Google API Console. Per generare le credenziali dell'account di servizio o per visualizzare le credenziali pubbliche che hai già generato, segui questi passaggi:

Innanzitutto, crea un account di servizio:

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

Successivamente, crea una chiave dell'account di servizio:

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

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

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

Prendi nota dell'indirizzo email 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

Utilizzando un account Google Workspace, un amministratore di Workspace dell'organizzazione può autorizzare un'applicazione ad 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 di un dominio Google Workspace utilizzerà 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 viene a volte denominata "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, un super amministratore del dominio Google Workspace deve completare i seguenti passaggi:

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

La tua applicazione ora ha l'autorità per effettuare chiamate API come utenti nel tuo dominio Workspace (per impersonare gli utenti). Quando ti prepari a effettuare queste chiamate API con delega, dovrai specificare esplicitamente l'utente a cui rubare l'identità.

Preparazione per una chiamata API con delega

Java

Dopo aver ottenuto l'indirizzo email e la chiave privata del client 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 la procedura.

Delega 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 il metodo createDelegated dell'oggetto GoogleCredential. Ad 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 richiamare il relativo metodo createDelegated(). L'argomento del metodo createDelegated() deve essere un utente appartenente al tuo account Workspace. Il codice che effettua la richiesta utilizzerà questa credenziale per chiamare le API di Google tramite il tuo account di servizio.

Python

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

Crea un oggetto Credentials dalle credenziali dell'account di servizio e dagli ambiti a cui deve accedere l'applicazione. 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 la procedura.
Delega 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 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 applicazione deve completare i seguenti passaggi:

Crea un token web JSON (JWT, pronunciato "jot") che include un'intestazione, un set di rivendicazioni e una firma.
Richiedi un token di accesso al server di autorizzazione Google OAuth 2.0.
Gestire la risposta JSON restituita dal server di autorizzazione.

Nelle sezioni seguenti viene descritto come completare questi passaggi.

Se la risposta include un token di accesso, puoi utilizzarlo per chiamare un'API di Google. Se la risposta non include un token di accesso, la tua richiesta di JWT e token potrebbe non essere stata creata correttamente oppure l'account di servizio potrebbe non avere l'autorizzazione per accedere agli ambiti richiesti.

Alla scadenza del token di accesso, l'applicazione genera un altro JWT, lo firma e richiede un altro token di accesso.

L'applicazione del tuo server utilizza un JWT per richiedere un token al server di autorizzazione di Google, quindi lo utilizza per chiamare un endpoint dell'API di Google. Non
viene coinvolto nessun utente finale.

Il resto di questa sezione descrive le specifiche del creare un JWT, firmare il JWT, formare la richiesta del token di accesso e gestire la risposta.

Creazione di un JWT

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

Un JWT è così composto:

{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}

Formazione dell'intestazione JWT

L'intestazione è composta da tre campi che indicano l'algoritmo di firma, il formato dell'asserzione e l'[ID chiave della chiave dell'account di servizio](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) utilizzato per firmare il JWT. L'algoritmo e il formato sono obbligatori e ogni campo ha un solo valore. Man mano che vengono introdotti altri algoritmi e formati, questa intestazione cambierà di conseguenza. L'ID chiave è facoltativo e, se viene specificato un ID chiave errato, GCP prova tutte le chiavi associate all'account di servizio a verificare il token e a rifiutarlo se non viene 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 di Base64url è la seguente:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

Creazione del set di rivendicazioni JWT

Il set di rivendicazioni JWT contiene informazioni sul 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 rivendicazioni JWT è un oggetto JSON e viene utilizzato nel calcolo della firma.

Rivendicazioni obbligatorie

Di seguito sono mostrate le rivendicazioni richieste nel set di rivendicazioni JWT. Le rivendicazioni possono essere mostrate in qualsiasi ordine nelle rivendicazioni.

Nome	Descrizione
`iss`	L'indirizzo email dell'account di servizio.
`scope`	Un elenco di autorizzazioni delimitati da spazi richiesto dall'applicazione.
`aud`	Un descrittore del target previsto dell'asserzione. Quando si effettua una richiesta di token di accesso, questo valore è sempre `https://oauth2.googleapis.com/token`.
`exp`	La scadenza dell'asserzione, espressa in secondi dalle 00:00:00 UTC, 1 gennaio 1970. Questo valore ha un massimo di 1 ora dopo l'orario di emissione.
`iat`	L'ora in cui è stata rilasciata l'affermazione, espressa in secondi dopo le 00:00:00 UTC, 1 gennaio 1970.

Di seguito è mostrata la rappresentazione JSON dei campi obbligatori in un set di rivendicazioni 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 di un'organizzazione. L'autorizzazione a eseguire questo tipo di rappresentazione deve essere concessa prima che un'applicazione possa impersonare un utente e in genere è gestita da un super amministratore. Per saperne di più, consulta Controllare l'accesso all'API con la delega a livello di dominio.

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

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

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

Di seguito è riportato un esempio di 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, anche il set di rivendicazioni JWT deve essere serializzato su codifica UTF-8 e Base64url-safe. Di seguito è riportato un esempio di rappresentazione JSON di un set JWT Claim:

{
  "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 della 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 quando si elabora la firma. L'unico algoritmo di firma supportato dal server di autorizzazione Google OAuth 2.0 è RSA che utilizza l'algoritmo di hashing SHA-256. Questo valore è espresso come RS256 nel campo alg nell'intestazione JWT.

Firma la rappresentazione UTF-8 dell'input utilizzando SHA256conRSA (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à una matrice di byte.

La firma deve essere codificata in Base64url. L'intestazione, il set di rivendicazioni e la firma sono concatenati con un carattere di punto (.). Il risultato è il JWT. Dovrebbero essere i seguenti (le interruzioni di riga sono state aggiunte 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 JWT firmato e pronto per la trasmissione:

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

Esecuzione della richiesta di 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 HTTPS di POST e il corpo è codificato tramite URL. L'URL è il seguente:

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 secondo necessità: `urn:ietf:params:oauth:grant-type:jwt-bearer`
`assertion`	Il JWT, inclusa la firma.

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

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

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

Di seguito è riportata la stessa richiesta utilizzando curl:

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

Gestione della risposta

Se la richiesta di JWT e token di accesso è formattata correttamente e l'account di servizio dispone dell'autorizzazione per 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 alle API di Google

Java

Utilizza l'oggetto GoogleCredential per chiamare le API di Google seguendo questi passaggi:

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();
```
Effettua richieste al servizio API utilizzando l'interfaccia fornita dall'oggetto di servizio. Ad esempio, per elencare le istanze dei database Cloud SQL nel emozionante progetto 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:

Crea un oggetto di servizio per l'API che vuoi chiamare. Per creare un oggetto di servizio, chiama 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)
```
Effettua richieste al servizio API utilizzando l'interfaccia fornita dall'oggetto di servizio. Ad esempio, per elencare le istanze dei database Cloud SQL nel emozionante progetto 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 dell'intestazione HTTP Authorization Bearer. 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 chiamate l'API Drive Files).

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

Esempi HTTP GET

Una chiamata all'endpoint drive.files (API Drive Files) 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 che utilizza 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, 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 OAuth 2.0 di Google scadono dopo la durata fornita dal valore expires_in. Alla scadenza di 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 cercando 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 questa operazione richieda in genere pochi minuti, la propagazione delle autorizzazioni a tutti gli utenti nel tuo Account Google potrebbe richiedere 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 richiesti nella rivendicazione `scope` del tuo JWT. Sebbene questa operazione richieda in genere pochi minuti, la propagazione delle autorizzazioni a tutti gli utenti nel tuo Account Google potrebbe richiedere fino a 24 ore.
`admin_policy_enforced`	(qualsiasi valore)	L'Account Google non è in grado di autorizzare uno o più ambiti richiesti a causa dei criteri impostati dall'amministratore di Google Workspace.	Per ulteriori informazioni su come un amministratore può limitare l'accesso a tutti gli ambiti o agli ambiti sensibili e con restrizioni fino a quando non viene esplicitamente concesso l'accesso al tuo ID client OAuth, consulta l'articolo del Centro assistenza per amministratori di Google Workspace Specificare quali app di terze parti e interne possono accedere ai dati di Google Workspace.
`invalid_client`	(qualsiasi valore)	Il client o il token JWT OAuth non è valido o è configurato in modo errato. Per informazioni dettagliate, consulta la descrizione dell'errore.	Assicurati che il token JWT sia valido e contenga dichiarazioni corrette. Verifica che il client e l'account di servizio OAuth siano configurati correttamente e di utilizzare l'indirizzo email corretto. Verifica che il token JWT sia corretto e che sia stato emesso per l'ID client nella richiesta.
`invalid_grant`	`Not a valid email.`	L'utente non esiste.	Verifica che l'indirizzo email indicato nel campo `sub` (rivendicazione) 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 significa che l'ora locale del sistema non è corretta. Potrebbe anche verificarsi se il valore `exp` è superiore a 65 minuti in futuro dal valore `iat` o se il valore `exp` è inferiore al valore `iat`.	Assicurati che l'orologio sul 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 segni di spaziatura interna uguali.	Decodifica il set di rivendicazioni JWT e verifica 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 venga generato correttamente.
`invalid_scope`	`Invalid OAuth scope or ID token audience provided.`	Non sono stati richiesti ambiti (elenco di ambiti vuoto) oppure non esiste uno degli ambiti richiesti (ovvero non valido).	Assicurati che la rivendicazione `scope` (campo) del JWT sia completata e confronta gli ambiti in cui si trova 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 rivendicazione `scope` deve essere separato da uno spazio, non da virgole.
`disabled_client`	`The OAuth client was disabled.`	La chiave utilizzata per firmare l'asserzione JWT è disabilitata.	Vai a Google API Consolee in IAM e amministrazione > Account di servizio, abilita l'account di servizio che contiene l'"ID chiave" utilizzato per firmare l'asserzione.
`org_internal`	`This client is restricted to users within its organization.`	L'ID client OAuth nella richiesta fa parte di un progetto che limita l'accesso agli Account Google in una specifica organizzazione Google Cloud.	Per l'autenticazione devi utilizzare un account di servizio dell'organizzazione. Conferma la configurazione del tipo di utente per l'applicazione OAuth.

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é come 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:

Crea un account di servizio come descritto in precedenza. Assicurati di conservare il file JSON che ricevi quando crei l'account.

Utilizzando una libreria JWT standard, ad esempio quella trovata all'indirizzo jwt.io, crea un JWT con un'intestazione e un 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 l'ID della chiave privata dell'account di servizio. Puoi trovare questo valore nel campo private_key_id del file JSON dell'account di servizio.
Per i campi iss e sub, specifica l'indirizzo email del tuo 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 attuale e, per il campo exp, specifica l'ora esattamente 3600 secondi dopo, quando il JWT scadrà.

Firma il JWT con RSA-256 utilizzando la chiave privata presente nel file JSON 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')

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

Utilizzo di OAuth 2.0 per le applicazioni da server a server

Panoramica

Creazione di un account di servizio

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

Preparazione per una chiamata API con delega

Java

Delega l'autorità a livello di dominio

Python

HTTP/REST

Creazione di un JWT

Formazione dell'intestazione JWT

Creazione del set di rivendicazioni JWT

Rivendicazioni obbligatorie

Rivendicazioni aggiuntive

Codifica del set di rivendicazioni JWT

Elaborazione della firma

Esecuzione della richiesta di token di accesso

Gestione della risposta

Chiamata alle API di Google

Java

Python

HTTP/REST

Esempi HTTP GET

Esempi di curl

Quando i token di accesso scadono

Codici di errore JWT

Addendum: autorizzazione dell'account di servizio senza OAuth

Java

Python

Esempi di `curl`