Tipi di token

Questa pagina descrive i tipi di token utilizzati per l'autenticazione alle API di Google, ai serviziGoogle Cloud e ai servizi creati dai clienti ospitati su Google Cloud.

Se accedi alle API e ai servizi di Google utilizzando una libreria client, puoi configurare le credenziali predefinite dell'applicazione e la libreria client gestisce 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'entità che effettua la richiesta e sul tipo di accesso per cui è autorizzata. Nella maggior parte dei flussi di autenticazione, l'applicazione o una libreria utilizzata dall'applicazione scambia una credenziale con un token, che determina a quali risorse l'applicazione è autorizzata ad accedere.

Tipi di token

In ambienti diversi vengono utilizzati tipi diversi di token. In questa pagina vengono descritti i seguenti tipi di token:

Questa pagina non tratta di chiavi API o ID client, che sono considerati credenziali.

Token di accesso

I token di accesso sono token opachi conformi al framework OAuth 2.0. Contengono informazioni sul tipo di principal utilizzato per creare il token, nonché informazioni sull'autorizzazione. Vengono utilizzati per autenticare e fornire informazioni di autorizzazione alle API di Google. I token di accesso non contengono l'identità dell'entità.

Se utilizzi le credenziali predefinite dell'applicazione (ADC) e le librerie client Cloud o le librerie client delle API di Google, non devi 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 necessità.

Contenuti del token di accesso

I token di accesso sono token opachi, il che significa che sono in un formato proprietario e le applicazioni non possono ispezionarli.

Puoi ottenere le informazioni da un token di accesso valido (non scaduto o revocato) utilizzando l'endpoint tokeninfo di Google OAuth 2.0.

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 un output simile al seguente esempio:

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

La tabella seguente elenca i campi più importanti da comprendere:

Campo Descrizione
azp Il progetto, l'email o l'ID 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 , è consigliabile utilizzare l'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 prima della scadenza del token. Per maggiori informazioni, vedi Durata del token di accesso.

Durata del token di accesso

Per impostazione predefinita, i token di accesso sono validi per 1 ora (3600 secondi). Quando il token di accesso è scaduto, il codice di gestione dei token deve ottenerne uno nuovo.

Se hai bisogno di un token di accesso con una durata più lunga o più breve, puoi utilizzare il metodo serviceAccounts.generateAccessToken per creare il token. Questo metodo ti consente di scegliere la durata del token, con una durata massima di 12 ore.

Se vuoi estendere la durata del token oltre il valore predefinito, devi creare un criterio dell'organizzazione che attivi il vincolo iam.allowServiceAccountCredentialLifetimeExtension. Per saperne di più, consulta Creare un token di accesso temporaneo.

Token di accesso federati

I token di accesso federati sono token di accesso restituiti dall'API Security Token Service in cambio delle credenziali esterne generate dalle identità federate da federazione delle identità per i carichi di lavoro e federazione delle identità per la forza lavoro. I token di accesso federati sono simili ai token di accesso standard, ad eccezione delle seguenti differenze:

  • I token di accesso federato non possono essere utilizzati per tutti i servizi Google Cloud . Per un elenco delle limitazioni per i token di accesso federati, consulta Federazione delle identità: prodotti e limitazioni.
  • I token di accesso federati asseriscono l'identità federata esterna.

Se devi utilizzare un'API che non supporta i token di accesso federati, puoi utilizzare il token di accesso federato per rappresentare unaccount di serviziot e generare un token di accesso standard. Per saperne di più, consulta Creare un token di accesso temporaneo.

Per saperne di più su come le applicazioni Google Kubernetes Engine si autenticano alle API di Google, consulta Informazioni sulla federazione delle identità per i carichi di lavoro per GKE.

Token ID

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

A differenza dei token di accesso, che sono oggetti opachi che non possono essere ispezionati dall'applicazione, i token ID sono pensati per essere ispezionati e utilizzati dall'applicazione. Le informazioni del token, ad esempio chi lo ha firmato o l'identità per cui è stato emesso il token ID, sono disponibili per l'utilizzo da parte dell'applicazione.

Per saperne di più sull'implementazione di OIDC da parte di Google in Google Cloud, consulta OpenID Connect nella documentazione di Google Identity. Per le best practice per l'utilizzo dei JWT, consulta Best practice correnti per i token web JSON.

Contenuti del token ID

Puoi esaminare un token ID valido (non scaduto o revocato) utilizzando l'endpoint tokeninfo.

Sostituisci ID_TOKEN con il token ID valido e non scaduto.

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

Questo comando restituisce un output simile al seguente esempio:

{
  "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 seguente tabella descrive le rivendicazioni del token ID richieste o utilizzate di frequente:

Richiedi 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 rivendicazione deve corrispondere all'applicazione o al servizio che utilizza il token per autenticare la richiesta. Per maggiori informazioni, consulta la sezione Attestazione  ID token.aud
sub Il soggetto: l'ID che rappresenta il principale che effettua la richiesta.
iat Ora Unix epoch in cui è stato emesso il token.
exp Ora Unix epoch in cui il token scade.

A seconda dell'emittente e dell'applicazione, potrebbero essere presenti altre rivendicazioni.

Rivendicazione aud del token ID

L'attestazione aud descrive il nome del servizio che questo token è stato creato per richiamare. Se un servizio riceve un token ID, deve verificarne l'integrità (firma), la validità (se è 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 ottieni un token ID, utilizzi le credenziali fornite da un account di servizio, anziché le credenziali utente. Questo perché l'attestazione aud per i token ID generati utilizzando le credenziali utente è associata staticamente 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 rivendicazione 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 del token ID

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

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

Token web JSON (JWT) autofirmati

Puoi utilizzare i JWT autofirmati per l'autenticazione ad alcune API Google senza dover ottenere un token di accesso dal server di autorizzazione.

La creazione di JWT autofirmati è consigliata se crei librerie client personalizzate per accedere alle API di Google, ma è un workflow avanzato. Per saperne di più sui JWT autofirmati, consulta Creazione di un token web JSON autofirmato. Per le best practice per l'utilizzo dei JWT, consulta Best practice correnti per i token web JSON.

Token di aggiornamento

Per impostazione predefinita, i token di accesso e i token ID sono validi per 1 ora. Un token di aggiornamento è un token speciale utilizzato per ottenere token di accesso o token ID aggiuntivi. Quando l'applicazione viene autenticata per la prima volta, riceve un token di accesso o un token ID, nonché un token di aggiornamento. In un secondo momento, 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.

Se i tuoi account utente sono gestiti da un provider di identità (IdP) esterno, questo IdP gestisce la durata dei token di lunga durata. Un'eccezione è rappresentata dai file ADC locali, che contengono token di aggiornamento utilizzati dalle librerie di autenticazione per aggiornare automaticamente i token di accesso per le librerie client.

I token di aggiornamento non hanno una durata prestabilita; possono scadere, ma altrimenti continuano a essere utilizzabili.

Per l'accesso degli utenti in Google Workspace o Cloud Identity Premium, puoi configurare la durata della sessione per assicurarti che un utente debba accedere periodicamente per mantenere l'accesso ai servizi Google Cloud . Se la tua applicazione crea e gestisce i propri token, deve anche gestire i token di aggiornamento.

Per saperne di più, consulta le seguenti pagine della documentazione di Google Identity:

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

L'utilizzo di 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 tipo bearer non forniscono una sicurezza sufficiente per il tuo caso d'uso, valuta la possibilità di aggiungere un altro livello di crittografia o di utilizzare una soluzione Transport Layer Security (mTLS) reciproca come Chrome Enterprise Premium, che limita l'accesso solo agli utenti autenticati su un dispositivo attendibile.

Passaggi successivi