Questa pagina illustra i tipi di token utilizzati per l'autenticazione alle API di Google, ai servizi Google Cloud e ai servizi creati dai clienti 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.
Che 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 è autorizzata. Nella maggior parte dei flussi di autenticazione, l'applicazione o una libreria utilizzata dall'applicazione scambia una credenziale con un token, che determina le risorse a cui l'applicazione è autorizzata ad accedere.
Tipi di token
Vengono utilizzati tipi diversi di token in ambienti diversi. In questa pagina sono descritti i seguenti tipi di token:
Questa pagina non tratta 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 di autorizzazione, ma non informazioni sull'identità. Vengono utilizzati per autenticare e fornire informazioni di autorizzazione alle API di Google.
Se utilizzi le credenziali predefinite dell'applicazione (ADC) e le librerie client Cloud o le librerie client delle API di Google, non è necessario gestire i token di accesso. Le librerie recuperano automaticamente la credenziale, la scambiano con un token di accesso e lo aggiornano 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 ispezzionarli.
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 qualcosa di 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 |
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, è buona prassi 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 granulare degli accessi.
|
expires_in |
Il numero di secondi che mancano alla scadenza del token. Per maggiori informazioni, consulta Tempo di vita 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 maggiore o minore, puoi utilizzare il
metodo serviceAccounts.generateAccessToken
per crearlo. 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 quella predefinita, devi creare un criterio dell'organizzazione che attivi il vincolo iam.allowServiceAccountCredentialLifetimeExtension.
Per ulteriori informazioni, consulta
Creare un token di accesso di breve durata.
Token ID
I token di identità sono token web JSON (JWT) conformi alla specifica OpenID Connect (OIDC). Sono costituiti da un insieme di coppie chiave-valore chiamate claim.
A differenza dei token di accesso, che sono oggetti opachi che non possono essere ispezionati dall'applicazione, i token ID sono destinati a essere ispezionati e utilizzati dall'applicazione. Le informazioni del token, ad esempio chi lo ha firmato o l'identità per cui è stato emesso, sono disponibili per l'utilizzo da parte dell'applicazione.
Per ulteriori informazioni sull'implementazione di OIDC da parte di Google, consulta OpenID Connect. Per le best practice per l'utilizzo dei token JWT, consulta Best practice correnti per i token web JSON.Contenuti del token ID
Puoi ispezionare 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 qualcosa di 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 i claim degli token ID richiesti o di uso comune:
| 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 questo claim deve corrispondere all'
applicazione o al servizio che utilizza il token per autenticare la richiesta.
Per ulteriori informazioni, consulta la sezione Rivendicazione del token ID aud.
|
sub |
L'oggetto: l'ID che rappresenta il principale che effettua la richiesta. |
iat |
Tempo di epocha Unix quando è stato emesso il token. |
exp |
Tempo Unix epoch alla scadenza del token. |
Potrebbero essere presenti altri diritti, a seconda dell'emittente e dell'applicazione.
Attestazione token aud
L'affermazione aud descrive il nome del servizio per cui è stato creato il token.
Se un servizio riceve un token di identità, deve verificarne l'integrità (firma), la validità (è scaduto) e se l'affermazione aud corrisponde al nome previsto.
In caso di mancata corrispondenza, il servizio deve rifiutare il token, in quanto potrebbe trattarsi di un replay destinato a un altro sistema.
In genere, quando ricevi un token ID, utilizzi le credenziali fornite da un account di servizio anziché le credenziali utente. Questo accade perché la rivendicazione di aud per i token ID generati utilizzando le credenziali utente è vincolata 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 rivendicazione aud.
Durata del token ID
I token ID sono validi per un massimo di un'ora (3600 secondi). Quando un token di identità scade, devi acquisirne uno nuovo.
Convalida del token di identità
Quando il tuo servizio o la tua applicazione utilizza un servizio Google come Cloud Run, le funzioni Cloud Run o Identity-Aware Proxy, Google convalida per te i token ID. In questi casi, i token ID devono essere firmati da Google.
Se devi convalidare gli ID token all'interno della tua 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
Puoi utilizzare JWT autofirmati per autenticarti ad alcune API Google senza dover ottenere un token di accesso dal server di autorizzazione.La creazione di JWT autofirmati è consigliata se crei le tue librerie client per accedere alle API di Google, ma si tratta di un flusso di lavoro avanzato. Per ulteriori informazioni sui token JWT autofirmati, consulta Creare un token web JSON autofirmato. Per le best practice per l'utilizzo dei token JWT, consulta JSON Web Token Best Current Practices.
Token di aggiornamento
L'identità provider gestisce la durata dei token longevi. Un'eccezione sono i file ADC locali, che contengono token di aggiornamento utilizzati dalle librerie di autenticazione per aggiornare automaticamente i token di accesso per le librerie client.
Token federati
I token federati vengono generati dalle identità federate da Workload Identity Federation e Workforce Identity Federation.
I token federati vengono utilizzati nei seguenti modi:
Per i servizi che supportano questi token, i token federati possono essere utilizzati direttamente. Questo metodo è talvolta chiamato accesso diretto.
I token federati possono essere scambiati con un token di accesso OAuth 2.0 utilizzando l'API Security Token Service.
I token federati restituiti da Workload Identity Federation e Workforce Identity Federation non sono equivalenti ai token restituiti da Workload Identity Federation for GKE. Per ulteriori informazioni su come le applicazioni Google Kubernetes Engine si autenticano nelle API di Google, consulta Configurare le applicazioni per utilizzare la federazione delle identità per i carichi di lavoro per GKE.
Token di accesso
I token di accesso 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 bearer.
L'utilizzo di token di accesso per l'autenticazione si basa sulla sicurezza fornita da un protocollo criptato, come HTTPS. Se un token di accesso viene intercettato, può essere utilizzato da un malintenzionato per ottenere l'accesso.
Passaggi successivi
- Scopri come configurare le credenziali per l'ADC.
- Consulta le informazioni su come ottenere gli ID token.
- Scopri di più sui metodi di autenticazione.