Tipi di token

Questa pagina illustra i tipi di token utilizzati per l'autenticazione nelle API di Google, nei servizi Google Cloud e nei servizi creati dal cliente ospitati su Google Cloud.

Se accedi alle API e ai servizi Google utilizzando una libreria client, puoi configurare le credenziali predefinite dell'applicazione e la libreria client gestirà i token per te. Questo è l'approccio consigliato.

Cosa sono i token

Per l'autenticazione e l'autorizzazione, un token è un oggetto digitale che contiene informazioni sull'identità dell'entità che effettua la richiesta e sul tipo di accesso per cui sono autorizzati. Nella maggior parte dei flussi di autenticazione, l'applicazione (o una libreria utilizzata dall'applicazione) scambia una credenziali con un token, che determina a quali risorse l'applicazione è autorizzata ad accedere.

Tipi di token

Vengono utilizzati diversi tipi di token in ambienti diversi. In questa pagina sono descritti i seguenti tipi di token:

In questa pagina non vengono trattate le chiavi API o gli ID client, che sono considerati credenziali.

Token di accesso

I token di accesso sono token opachi conformi al framework OAuth 2.0. Contengono informazioni sull'autorizzazione, ma non sull'identità. Vengono usate per autenticare e fornire informazioni sulle autorizzazioni alle API di Google.

Se utilizzi le Credenziali predefinite dell'applicazione (ADC) e le librerie client di Cloud o delle librerie client delle API di Google, non è necessario gestire i token di accesso; le librerie recuperano automaticamente le credenziali, le scambiano con un token di accesso e aggiornano il token di accesso in base alle esigenze.

Contenuti dei token di accesso

I token di accesso sono opachi, ovvero in formato proprietario; le applicazioni non possono ispezionarli. Puoi ottenere le informazioni da un token di accesso valido (non scaduto o revocato) utilizzando l'endpoint OAuth 2.0 tokeninfo di Google.

Sostituisci ACCESS_TOKEN con il token di accesso valido e non scaduto.

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

Questo comando restituisce qualcosa di simile all'esempio seguente:

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

Nella tabella seguente sono elencati i campi più importanti da comprendere:

Campo Descrizione
azp L'ID progetto, email o account di servizio dell'applicazione che ha richiesto il token. Questo valore viene incluso solo se https://www.googleapis.com/auth/userinfo.email è specificato nell'elenco degli ambiti.
scope Gli ambiti OAuth che sono stati aggiunti a questo token di accesso. Per i servizi Google Cloud, le best practice prevedono l'utilizzo dell'ambito https://www.googleapis.com/auth/cloud-platform , che include tutte le API Google Cloud, insieme a Identity and Access Management (IAM), che fornisce un controllo dell'accesso granulare.
expires_in Il numero di secondi che mancano alla scadenza del token. Per maggiori informazioni, consulta Durata del token di accesso.

Durata del token di accesso

Per impostazione predefinita, i token di accesso sono validi per 1 ora (3600 secondi). Allo scadere del token di accesso, al tuo codice di gestione dei token deve essere assegnato un nuovo token.

Se ti serve un token di accesso con una durata maggiore o minore, puoi utilizzare il metodo serviceAccounts.generateAccessToken per crearlo. Questo metodo consente di scegliere la durata del token, con una durata massima di 12 ore.

Se vuoi estendere la durata del token oltre quella predefinita, devi creare un criterio dell'organizzazione che attivi il vincolo iam.allowServiceAccountCredentialLifetimeExtension. Non puoi creare token di accesso con una durata estesa per credenziali utente o identità esterne. Per maggiori informazioni, consulta Creare un token di accesso di breve durata.

Token ID

I token ID sono JSON Web Token (JWT) conformi alla specifica OpenID Connect (OIDC). Sono composte da un insieme di coppie chiave-valore chiamate rivendicazioni.

A differenza dei token di accesso, che sono oggetti opachi che non possono essere esaminati dall'applicazione, i token ID devono essere ispezionati e utilizzati dall'applicazione. Le informazioni del token, ad esempio chi ha firmato il token o l'identità per la quale è stato emesso il token ID, possono essere utilizzate dall'applicazione.

Per ulteriori informazioni sull'implementazione OIDC di Google, consulta OpenID Connect. Per le best practice per lavorare con i JWT, consulta le best practice attuali per i token web JSON.

Contenuti token ID

Puoi controllare un token ID valido (non scaduto o revocato) utilizzando l'endpoint tokeninfo OAuth 2.0 di Google.

Sostituisci ID_TOKEN con il token ID valido e non scaduto.

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

Questo comando restituisce qualcosa di simile all'esempio seguente:

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

La tabella seguente descrive le rivendicazioni dei token ID richieste o di uso comune:

Rivendica Descrizione
iss L'emittente o il firmatario del token. Per i token ID firmati da Google, questo valore è https://accounts.google.com.
azp Facoltativo. A chi è stato emesso il token.
aud Il pubblico del token. Il valore di questa attestazione deve corrispondere all'applicazione o al servizio che utilizza il token per autenticare la richiesta. Per maggiori informazioni, consulta Rivendicazione del token ID aud.
sub Oggetto: l'ID che rappresenta l'entità che effettua la richiesta.
iat Ora epoch di Unix quando è stato emesso il token.
exp Tempo epoch di Unix alla scadenza del token.

Potrebbero essere presenti altri reclami, a seconda dell'emittente e della richiesta.

Attestazione token ID aud

L'attestazione aud descrive il nome del servizio per richiamare questo token. Se un servizio riceve un token ID, deve verificarne l'integrità (la firma) e la validità (è scaduto) e se l'attestazione aud corrisponde al nome previsto. Se non corrisponde, il servizio deve rifiutare il token, perché potrebbe essere una riproduzione destinata a un altro sistema.

In genere, quando ricevi un token ID, devi utilizzare le credenziali fornite da un account di servizio anziché le credenziali utente. Questo perché la rivendicazione aud per i token ID generati utilizzando le credenziali utente è associata in modo statico all'applicazione utilizzata dall'utente per l'autenticazione. Quando utilizzi un account di servizio per acquisire un token ID, puoi specificare un valore diverso per la richiesta aud.

Durata del token ID

I token ID sono validi per un massimo di 1 ora (3600 secondi). Quando un token ID scade, devi acquisirne uno nuovo.

Convalida token ID

Quando il tuo servizio o la tua applicazione utilizza un servizio Google come Cloud Run, Cloud Functions o Identity-Aware Proxy, Google convalida i token ID per te; in questi casi, i token ID devono essere firmati da Google.

Se devi convalidare i token ID all'interno dell'applicazione, puoi farlo, anche se si tratta di un flusso di lavoro avanzato. Per informazioni, consulta Convalida di un token ID.

Token web JSON (JWT) autofirmati

I JWT autofirmati sono necessari per eseguire l'autenticazione nelle API di cui è stato eseguito il deployment con API Gateway. Inoltre, puoi utilizzare JWT autofirmati per l'autenticazione su alcune API di Google senza dover ottenere un token di accesso da Authorization Server.

Se stai creando librerie client personalizzate per accedere alle API di Google, ti consigliamo di creare JWT autofirmati, ma si tratta di un flusso di lavoro avanzato. Per saperne di più sui JWT autofirmati, consulta Creazione di un token web JSON autofirmato. Per le best practice per lavorare con i JWT, consulta le best practice attuali per i token web JSON.

Token di aggiornamento

Per impostazione predefinita, i token di accesso e ID sono validi per un'ora. Un token di aggiornamento è un token speciale usato per ottenere token ID o token di accesso aggiuntivi. Quando l'applicazione esegue l'autenticazione per la prima volta, riceve un token di accesso o un token ID, oltre a un token di aggiornamento. Successivamente, se l'applicazione deve accedere di nuovo alle risorse e il token fornito in precedenza è scaduto, utilizza il token di aggiornamento per richiedere un nuovo token. I token di aggiornamento vengono utilizzati solo per l'autenticazione degli utenti, ad esempio per Cloud Identity o Google Workspace.

I token di aggiornamento non hanno una durata predefinita; possono scadere, ma in caso contrario continuano a essere utilizzabili. Per l'accesso degli utenti in Google Workspace o Cloud Identity Premium Edition, puoi configurare la durata della sessione per assicurarti che un utente debba accedere periodicamente per mantenere l'accesso ai servizi Google Cloud.

Se l'applicazione crea e gestisce i propri token, dovrà anche gestire i token di aggiornamento. Per ulteriori informazioni, consulta i seguenti link:

Token federati

I token federati vengono utilizzati come passaggio intermedio dalla federazione delle identità per i carichi di lavoro. I token federati vengono restituiti dal Security Token Service e non possono essere utilizzati direttamente. Devono essere scambiati con un token di accesso utilizzando il furto d'identità dell'account di servizio.

Token di connessione

I token di connessione sono una classe generale di token che concede l'accesso alla parte in possesso del token. I token di accesso, i token ID e i JWT autofirmati sono tutti token di connessione.

L'utilizzo dei token di connessione per l'autenticazione si basa sulla sicurezza fornita da un protocollo criptato, come HTTPS. Se un token di connessione viene intercettato, può essere utilizzato da un malintenzionato per ottenere l'accesso.

Se i token di connessione non offrono una sicurezza sufficiente per il tuo caso d'uso, valuta la possibilità di aggiungere un altro livello di crittografia o di utilizzare una soluzione mTLS (Transport Layer Security) reciproca come BeyondCorp Enterprise, che limita l'accesso solo agli utenti autenticati su un dispositivo attendibile.

Passaggi successivi