Tipi di token

Google Cloud emette più tipi di token, che differiscono per scopo e per le parti tra cui vengono scambiati.

La seguente tabella offre una panoramica delle principali categorie di token, all'interno delle quali si trovano diversi tipi di token.

Categoria token Percorso di comunicazione Finalità
Token di accesso Server di autorizzazione ⭢ Client ⭢ API Google Consente ai client di chiamare le API Google Cloud .
Token di concessione di token Server di autorizzazione ⭤ Client Consente ai clienti di ottenere token nuovi o diversi, possibilmente in un secondo momento.
Token ID Server di autorizzazione ⭢ Client Consente ai client di identificare l'utente con cui interagiscono.

I token di accesso e di identità sono token di connessione. I token di connessione sono una classe generale di token che concedono l'accesso alla parte in possesso del token.

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

Se i token di tipo bearer non forniscono una sicurezza sufficiente per il tuo caso d'uso, puoi ridurre il rischio di furto dei token utilizzando l'accesso sensibile al contesto, limitando la durata dei token di accesso o utilizzando una soluzione Transport Layer Security (mTLS) reciproca come Chrome Enterprise Premium.

Token di accesso

I token di accesso consentono ai client di effettuare chiamate autenticate alle API Google Cloud . Google Cloud supporta diversi tipi di token di accesso, che hanno in comune le seguenti proprietà:

  • Autenticano un'entità, che può essere un utente o un workload.

  • Sono emessi per un cliente specifico.

  • Hanno una durata limitata e scadono al massimo dopo poche ore.

  • Sono limitati a determinati ambiti, endpoint o risorse OAuth. Ciò significa che un token di accesso in genere non concede l'accesso a tutte le risorse di un utente, ma solo a un determinato sottoinsieme.

I token di accesso possono differire nei seguenti modi:

  • Emittente: la parte che emette il token.

  • Entità: il tipo di entità che il token può autenticare.

  • Limitazioni: le limitazioni che possono essere imposte al token.

La tabella seguente elenca i diversi tipi di token di accesso:

Tipo di token Emittente Entità Limitazioni
Token di accesso utente Server di autorizzazione Google
  • Utente (utente gestito)
  • Utente (account consumer)
 ambito OAuth
Token di accesso all'account di servizio
  • Server di autorizzazione Google
  • Google Cloud Server di autorizzazione IAM
 Service account ambito OAuth
Token di delega a livello di dominio Server di autorizzazione Google Utente (utente gestito) ambito OAuth
JSON Web Token (JWT) dell'account di servizio Client Service account Ambito OAuth o API
Token di accesso federato Google Cloud Server di autorizzazione IAM
  • Entità pool di identità della forza lavoro
  • Entità pool di identità del workload
 ambito OAuth
Token del limite di accesso alle credenziali Google Cloud Server di autorizzazione IAM
  • Utente (utente gestito)
  • Utente (account consumer)
  • Service account
 Oggetti Cloud Storage specifici
Token del limite di accesso alle credenziali emesso dal client Client Service account Oggetti Cloud Storage specifici

I diversi tipi di token di accesso presentano anche proprietà di sicurezza diverse:

  • Formato: alcuni token di accesso sono opachi, ovvero sono in un formato proprietario e non possono essere ispezionati. Gli altri token sono codificati come token web JSON, che può essere decodificato dal client.

  • Introspezione: alcuni token opachi possono essere introspezionati utilizzando l'API Google Cloud , mentre altri no.

  • Durata: i token differiscono per durata e per il grado in cui possono essere modificati.

  • Revocabilità: alcuni token possono essere revocati. Gli altri token rimangono validi fino alla scadenza.

La seguente tabella riepiloga le differenze tra i tipi di token di accesso.

Tipo di token Formato Introspectable Durata Revocabile
Token di accesso utente Opaque Sì 1 ora Sì
Token di accesso al service account Opaque Sì Da 5 minuti a 12 ore No
Token di delega a livello di dominio Opaque Sì 1 ora No
Token web JSON (JWT) del service account JWT N/D 5 minuti - 1 ora No
Token di accesso federato Opaque No Vedi Token di accesso federati No
Token del limite di accesso alle credenziali Opaque No Vedi Token di limite di accesso alle credenziali No
Token del limite di accesso delle credenziali emesso dal client Opaque No N/D No

Token di accesso utente

I token di accesso utente autenticano un utente e autorizzano un client ad agire per conto dell'utente:

L'entità autenticata è un account utente gestito o un account consumer. Il client può essere un'applicazione web o un'applicazione nativa.

I token di accesso utente sono opachi. A scopo diagnostico, puoi esaminare un token di accesso utilizzando il seguente comando, sostituendo ACCESS_TOKEN con un token di accesso valido:

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

Questo comando produce un output simile al seguente esempio:

{
  "azp": "0000000000.apps.googleusercontent.com",
  "aud": "0000000000.apps.googleusercontent.com",
  "sub": "00000000000000000000",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744687132",
  "expires_in": "3568",
  "email": "user@example.com",
  "email_verified": "true"
}

L'output include i seguenti campi:

Campo Nome Descrizione
aud Pubblico

Il client OAuth a cui è destinato questo token, identificato dal relativo ID client OAuth.

I client OAuth possono ottenere token di accesso per altri client OAuth che appartengono allo stesso progetto. Il pubblico potrebbe essere diverso dalla parte autorizzata.

azp Parte autorizzata Il client OAuth che ha richiesto il token, identificato dal suo ID client OAuth.
email Indirizzo email principale

L'indirizzo email principale dell'utente.

Questo campo è presente solo se il token include l'ambito https://www.googleapis.com/auth/userinfo.email.

exp Scadenza L'ora di scadenza del token, nel formato ora epoca di Unix.
scope ambiti OAuth Il set di API a cui il client può accedere per conto dell'utente, identificato dall' ambito OAuth.
sub Oggetto

L'entità autenticata, identificata dal suo ID univoco.

Questo ID è equivalente all'ID esposto nell' API Directory.

I token di accesso utente scadono automaticamente dopo un'ora, ma possono essere revocati in precedenza, se necessario.

Per impostazione predefinita, i token di accesso utente sono token di tipo bearer, il che significa che non sono associati a nessun canale di comunicazione, rete o credenziale aggiuntiva in particolare. Puoi implementare facoltativamente il token binding eseguendo il deployment dell'accesso basato su certificati in modo che i token di accesso utente possano essere utilizzati solo in combinazione con un certificato client mTLS valido.

Token di accesso al service account

I token di accesso al service account autenticano un account di servizio. I token sono opachi e puoi esaminarli utilizzando l'API https://oauth2.googleapis.com/tokeninfo.

Per un token di accesso del account di servizio, l'API restituisce un output simile al seguente esempio:

{
  "azp": "000000000000000000000",
  "aud": "000000000000000000000",
  "scope": "https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744687132",
  "expires_in": "3568",
  "email": "service-account@example.iam.gserviceaccount.com",
  "email_verified": "true",
  "access_type": "online"
}

Un token del account di servizio include i seguenti campi:

Campo Nome Descrizione
aud Pubblico Il account di servizio a cui è destinato il token, equivalente alla parte autorizzata.
azp Parte autorizzata Il account di servizio che ha richiesto il token, identificato dal suo ID univoco.
email Indirizzo email principale

L'indirizzo email del account di servizio.

Questo campo è presente solo se il token include l'ambito https://www.googleapis.com/auth/userinfo.email.

exp Scadenza L'ora di scadenza del token, nel formato ora epoca di Unix.

I token di accesso del service account non possono essere revocati e rimangono validi fino alla scadenza.

Per impostazione predefinita, i token di accesso al account di servizio scadono dopo un'ora. Utilizzando il metodo serviceAccounts.generateAccessToken, puoi richiedere token con durate diverse. Poiché durate più lunghe dei token possono aumentare il rischio, devi configurare il vincolo iam.allowServiceAccountCredentialLifetimeExtension per consentire ai client di richiedere token di accesso al account di servizio con durate superiori a un'ora.

Token di delega a livello di dominio

I token di delega a livello di dominio autenticano un utente e autorizzano un account di servizio ad agire per conto dell'utente. I token sono opachi e puoi esaminarli utilizzando l'API https://oauth2.googleapis.com/tokeninfo.

Per un token di delega a livello di dominio, l'API restituisce un output simile al seguente esempio:

{
  "azp": "000000000000000000000",
  "aud": "000000000000000000000",
  "scope": "https://www.googleapis.com/auth/admin.directory.user.readonly https://www.googleapis.com/auth/userinfo.email",
  "exp": "1744688957",
  "expires_in": "3540",
  "email": "user@example.com",
  "email_verified": "true",
  "access_type": "offline"
}

Un token di delega a livello di dominio include i seguenti campi:

Campo Nome Descrizione
aud Pubblico Il account di servizio a cui è destinato il token, equivalente alla parte autorizzata.
azp Parte autorizzata Il account di servizio che ha richiesto il token, identificato dal suo ID univoco.
email Indirizzo email principale

L'indirizzo email principale dell'utente impersonato.

Questo campo è presente solo se il token include l'ambito https://www.googleapis.com/auth/userinfo.email.

exp Scadenza L'ora di scadenza del token, nel formato ora epoca di Unix.
scope ambiti OAuth Il set di API a cui il client può accedere per conto dell'utente rappresentato, identificato dall'ambito OAuth.

I token di delega a livello di dominio scadono automaticamente dopo un'ora e non possono essere revocati.

Token web JSON del service account

I token web JSON (JWT) dell'account di servizio autenticano un service account. Mentre i token di accesso del service account vengono emessi da un server di autorizzazione, i JWT del account di servizio possono essere emessi dal client stesso.

A volte questi JWT vengono chiamati "autofirmati". Possono essere utili quando devi autenticarti con alcune API di Google senza ottenere un token di accesso dal server di autorizzazione, ad esempio quando crei le tue librerie client.

Per emettere un JWT del account di servizio, i client devono eseguire i seguenti passaggi:

  1. Prepara un payload di firma web JSON che includa l'indirizzo email dell'account di servizio, un ambito OAuth o un endpoint API e un orario di scadenza.

  2. Firma il payload utilizzando una chiave del account di servizio del service account corrispondente. I client possono firmare il payload offline utilizzando una chiave del account di servizio gestita dall'utente oppure online utilizzando il metodo signJwt e una chiave del account di servizio gestita da Google. Per saperne di più, vedi Creare un token web JSON autofirmato

Un JWT del account di servizio decodificato è simile al seguente, con SIGNATURE sostituito dalla firma del token:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.iam.gserviceaccount.com",
  "sub": "service-account@example.iam.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/cloud-platform",
  "exp": 1744851267,
  "iat": 1744850967
}.SIGNATURE

Anziché specificare un ambito OAuth nella chiave scope, un JWT dell'account di servizio può specificare un endpoint API nella chiave aud:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.iam.gserviceaccount.com",
  "sub": "service-account@example.iam.gserviceaccount.com",
  "aud": "https://cloudresourcemanager.googleapis.com/",
  "exp": 1744854799,
  "iat": 1744851199
}.SIGNATURE

Un JWT del account di servizio include i seguenti campi:

Campo Nome Descrizione
aud Pubblico Endpoint API a cui il client può accedere. Valido solo se scope non è specificato.
exp Scadenza L'ora di scadenza del token, nel formato ora epoca di Unix.
iat Ora del problema L'ora in cui è stato emesso il token, nel formato ora epoca di Unix.
iss Emittente L'emittente del token, ovvero il account di servizio stesso.
scope ambiti OAuth Il set di API a cui il client può accedere, identificato dall' ambito OAuth. Valido solo se aud non è specificato.
sub Oggetto Entità autenticata, ovvero il account di servizio stesso.

I JWT del service account possono essere validi fino a un'ora e non possono essere revocati.

Token di accesso federati

I token di accesso federati autenticano un'entità pool di workload o un'entità pool di forza lavoro.

La federazione delle identità per la forza lavoro consente ai client di scambiare un token esterno con un token di accesso federato che autentica un principal del pool di forza lavoro. L'entità pool di identità del workload è identificata da un identificatore di entità simile al seguente:

principal://iam.googleapis.com/locations/global/workforcePools/POOL/subject/raha@altostrat.com.

La federazione delle identità per i workload consente ai client di scambiare un token esterno con un token di accesso federato che autentica un principal del pool di workload. L'entità pool di identità del workload è identificata da un identificatore di entità simile al seguente:

principal://iam.googleapis.com/projects/PROJECT/locations/global/workloadIdentityPools/POOL/subject/SUBJECT_ATTRIBUTE_VALUE

I token di accesso federati sono opachi e non possono essere esaminati. I token non possono essere revocati e rimangono validi fino alla scadenza. Le scadenze per ogni tipo di token si basano su quanto segue:

  • La federazione delle identità per la forza lavoro imposta la scadenza del token in base alla configurazione del provider del pool di identità per la forza lavoro.

  • La federazione delle identità per i workload imposta la scadenza del token in modo che corrisponda alla scadenza del token esterno.

Token del limite di accesso alle credenziali

I token di limite di accesso alle credenziali autenticano un utente o un account di servizio e includono un limite di accesso. Il confine di accesso limita il token in modo che possa essere utilizzato solo per accedere a un sottoinsieme definito di risorse Cloud Storage.

I token di confine di accesso alle credenziali sono a volte chiamati con ambito ridotto perché derivano da un token di input, ma sono più limitati nelle risorse a cui concedono l'accesso.

La scadenza dei token del perimetro di accesso alle credenziali deriva dalla scadenza del token di input, che può essere un token di accesso utente o un token di accesso al service account. I token del limite di accesso alle credenziali sono opachi e non possono essere esaminati o revocati.

Token dei limiti di accesso delle credenziali emessi dal client

I token dei limiti di accesso delle credenziali emessi dal client sono simili ai token dei limiti di accesso delle credenziali, ma sono ottimizzati per scenari in cui i client devono ottenere token dei limiti di accesso delle credenziali con limiti di accesso diversi con elevata frequenza.

I client possono creare token di limite di accesso delle credenziali emesse dal client localmente utilizzando le librerie client Cloud e un token intermediario del limite di accesso, che devono aggiornare periodicamente.

I token di confine di accesso alle credenziali emesse dal client sono opachi e non possono essere introspezionati o revocati.

Token di concessione token

I token di concessione consentono ai client di ottenere token nuovi o diversi, possibilmente in un secondo momento. Google Cloud supporta diversi tipi di token di concessione e tutti hanno in comune quanto segue:

  • Rappresentano un'autenticazione precedente.

  • Autenticano un principal, che può essere un'identità Google (un utente o un workload) o un'identità esterna.

  • Possono essere riscattati per un token di accesso.

  • Non possono essere utilizzati per effettuare chiamate alle API di Google, il che li distingue dai token di accesso.

I token di concessione possono differire nei seguenti modi:

  • Emittente: la parte che emette il token.

  • Entità: il tipo di identità dell'entità che il token può autenticare.

  • Limitazioni: le limitazioni che possono essere imposte al token.

La tabella seguente elenca i diversi tipi di token di concessione.

Tipo di token Emittente Tipo di token di accesso riscattato Entità Limitazioni
Token di aggiornamento Server di autorizzazione Google Token di accesso utente
  • Utente (utente gestito)
  • Utente (account consumer)
 ambito OAuth
Codice di autorizzazione Server di autorizzazione Google Token di accesso utente
  • Utente (utente gestito)
  • Utente (account consumer)
 ambito OAuth
Asserzione del token web JSON del service account Client
  • Token di delega a livello di dominio
  • Token di accesso al service account
  • Utente (utente gestito)
  • Service account
 ambito OAuth
JSON Web Token esterno Provider di identità esterno Token di accesso federato Entità esterna Nessuno
Asserzione o risposta SAML esterna Provider di identità esterno Token di accesso federato Entità esterna Nessuno
Token GetCallerIdentity Amazon Web Services (AWS) Provider di identità esterno Token di accesso federato Entità esterna Nessuno

I diversi tipi di token di concessione dei token mostrano anche proprietà di sicurezza diverse:

  • Formato: alcuni token sono opachi. Altri token possono essere decodificati dal client.

  • Durata: i token hanno una durata diversa e possono essere modificati in misura diversa.

  • Multi-uso: alcuni token che concedono token possono essere utilizzati una sola volta. Altri token possono essere utilizzati più volte.

  • Revocabilità: alcuni token possono essere revocati. Gli altri token rimangono validi fino alla scadenza.

La seguente tabella riassume le differenze tra queste proprietà per i token di concessione:

Tipo di token Formato Durata Revocabile Multiuso
Token di aggiornamento Opaque Consulta la sezione Token di aggiornamento. Sì Sì
Codice di autorizzazione Opaque 10 minuti No No
Asserzione del token web JSON del service account JWT 5 minuti - 1 ora No Sì
Token esterno o token web JSON esterno JWT Dipende dal provider di identità Dipende dal provider di identità Sì
Asserzione o risposta SAML esterna SAML Dipende dal provider di identità Dipende dal provider di identità Sì
Token GetCallerIdentity Amazon Web Services (AWS) Blob di testo Dipende dal provider di identità Dipende dal provider di identità Sì

Token di aggiornamento

I token di aggiornamento sono token opachi che consentono ai client di ottenere token ID e token di accesso per un utente, se l'utente ha precedentemente autorizzato un client ad agire per suo conto.

I token di aggiornamento sono associati a un client specifico e possono essere utilizzati solo in combinazione con credenziali client valide, ad esempio un ID client e un client secret.

Se l'autorizzazione del client include uno o più ambiti OAuth, la durata del token di aggiornamento è soggetta al controllo della Google Cloud durata della sessione.Google Cloud In caso contrario, i token di aggiornamento rimangono validi finché l'utente non revoca l'autorizzazione o non si verificano altri eventi di revoca dei token.

Codici di autorizzazione

I codici di autorizzazione sono token opachi e di breve durata. I codici sono destinati a essere utilizzati solo durante l'autenticazione dell'utente come intermediario tra il client e il server di autorizzazione di Google.

Come i token di aggiornamento, i codici di autorizzazione sono associati a un client e possono essere utilizzati solo in combinazione con credenziali client valide. A differenza dei token di aggiornamento, i codici di autorizzazione possono essere utilizzati una sola volta.

Asserzioni del token web JSON del service account

Le asserzioni JSON Web Token (JWT) del service account affermano l'identità di un account di servizio. I workload possono utilizzare le asserzioni JWT del account di servizio per ottenere token di accesso del service account o token di delega a livello di dominio. L'asserzione JWT del service account è firmata da una chiave del account di servizio.

Un'asserzione JWT del account di servizio decodificata ha un aspetto simile al seguente, con SIGNATURE sostituito dalla firma del token:

{
  "alg": "RS256",
  "kid": "290b7bf588eee0c35d02bf1164f4336229373300",
  "typ": "JWT"
}.{
  "iss": "service-account@example.iam.gserviceaccount.com",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1744851267,
  "iat": 1744850967
}.SIGNATURE

Le asserzioni JWT del service account sono strutturalmente simili ai JWT del service account: entrambi i tipi di token possono essere emessi dal client stesso e sono firmati da una chiave del account di servizio. Tuttavia, i due tipi di token utilizzano payload diversi, come descritto nella tabella seguente.

Campo JWT del service account Asserzione JWT del service account
aud APIGoogle Cloud , omessa se è specificato scope Deve essere https://oauth2.googleapis.com/token
exp Scadenza Scadenza
iat Ora del problema Ora del problema
iss Indirizzo email del account di servizio Indirizzo email del account di servizio
scope Ambiti OAuth, omessi se è specificato aud ambiti OAuth
sub Indirizzo email del account di servizio Indirizzo email di un account utente per la delega sull'intero dominio, omesso altrimenti

Le asserzioni JWT del service account possono essere valide fino a un'ora e non possono essere revocate.

Token web JSON esterni

I token JWT (JSON Web Token) esterni vengono emessi da un provider di identità esterno come Microsoft Entra ID, Okta, Kubernetes o GitHub. Potrebbero differire per struttura e contenuti.

Configurando la federazione delle identità per la forza lavoro o la federazione delle identità per i carichi di lavoro, puoi configurare una relazione di trust tra Google Cloud e un provider di identità esterno. I workload possono quindi utilizzare i JWT esterni come token di concessione per ottenere token di accesso federati.

Quando utilizzi la federazione delle identità per la forza lavoro, il token di accesso federato risultante autentica un principal del pool di identità della forza lavoro.

Quando utilizzi la federazione delle identità per i carichi di lavoro, il token di accesso federato risultante autentica un principal del pool di identità del carico di lavoro.

In entrambi i casi, l'identificatore principale viene derivato da una o più rivendicazioni del JWT esterno.

Per essere compatibili con la federazione delle identità per la forza lavoro o la federazione delle identità dei workload, i JWT esterni devono soddisfare requisiti specifici.

Asserzioni o risposte SAML esterne

Le asserzioni Security Assertion Markup Language (SAML) esterne sono asserzioni SAML 2.0 emesse da un provider di identità esterno come Microsoft Entra ID, Okta o Active Directory Federation Services. Queste asserzioni SAML esterne possono essere facoltativamente incluse in una risposta SAML 2.0 o essere criptate.

Come per i token web JSON esterni, puoi configurare la federazione delle identità per la forza lavoro o la federazione delle identità del workload in modo che i workload possano utilizzare asserzioni o risposte SAML esterne come token di concessione di token per ottenere token di accesso federati.

Per essere compatibili con la federazione delle identità per la forza lavoro o la federazione delle identità per i carichi di lavoro, le asserzioni SAML esterne devono soddisfare requisiti specifici.

Token GetCallerIdentity Amazon Web Services (AWS)

I token AWS GetCallerIdentity esterni sono blob di testo che contengono una richiesta firmata all'API AWS GetCallerIdentity. Analogamente ai token web JSON esterni e alle asserzioni SAML, puoi configurare la federazione delle identità per la forza lavoro o la federazione delle identità per i workload in modo che i workload possano utilizzare questi blob di testo come token di concessione di token per ottenere token di accesso federati.

Token di identità

I token ID consentono ai client di identificare l'utente con cui interagiscono. Google Cloud supporta diversi tipi di token ID e tutti hanno in comune quanto segue:

  • Sono formattati come token web JSON (JWT) in modo che possano essere decodificati, verificati e interpretati dal client.

  • Autenticano un'entità, che può essere un utente o un workload.

  • Sono emessi per un cliente specifico.

  • Hanno una durata breve e scadono dopo al massimo un'ora.

  • Non sono revocabili.

  • Non possono essere utilizzati per effettuare chiamate API Google, il che li distingue dai token di accesso.

  • Non possono essere utilizzati per ottenere token di accesso, il che li distingue dai token di concessione.

  • Possono essere utilizzati per autenticare le chiamate tra microservizi o per autenticarsi in modo programmatico in Identity-Aware Proxy (IAP).

I token ID possono differire nei seguenti modi:

  • Pubblico: la parte che deve decodificare e utilizzare il token.

  • Emittente: la parte che emette il token.

  • Durata: i token differiscono per durata e per il grado di modificabilità.

  • Entità: il tipo di identità dell'entità che il token può autenticare.

La seguente tabella elenca i diversi tipi di token di identità.

Tipo di token Emittente Pubblico Entità Durata
Token ID utente Server di autorizzazione Google Client OAuth/OIDC
  • Utente (utente gestito)
  • Utente (account consumer)
 1 ora
Token ID service account Google Cloud Server di autorizzazione IAM Libero di scegliere qualsiasi segmento di pubblico Service account 1 ora
Asserzione Identity-Aware Proxy (IAP) IAP
  • Backend
  • Applicazione di App Engine
  • Utente (utente gestito)
  • Utente (account consumer)
  • Entità pool di identità della forza lavoro
 10 minuti
Asserzione SAML Server di autorizzazione Google App SAML Utente (utente gestito) 10 minuti

Token ID utente

I token ID utente sono token web JSON (JWT) che autenticano un utente. I client possono ottenere un token ID utente avviando un flusso di autenticazione OIDC.

I token ID utente sono firmati utilizzando il set di chiavi web JSON (JWKS) di Google. Il JWKS di Google è una risorsa globale e le stesse chiavi di firma vengono utilizzate per diversi tipi di utenti, tra cui:

  • Account utente gestiti

  • Account utente consumer

  • Account di servizio

Un token ID utente decodificato è simile al seguente, con SIGNATURE sostituito dalla firma del token:

{
  "alg": "RS256",
  "kid": "c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9",
  "typ": "JWT"
}.{
  "iss": "https://accounts.google.com",
  "azp": "1234567890-123456789abcdef.apps.googleusercontent.com",
  "aud": "1234567890-123456789abcdef.apps.googleusercontent.com",
  "sub": "12345678901234567890",
  "at_hash": "y0LZEe-ervzRNSxn4R-t9w",
  "name": "Example user",
  "picture": "https://lh3.googleusercontent.com/a/...",
  "given_name": "Example",
  "family_name": "User",
  "hd": "example.com",
  "iat": 1745361695,
  "exp": 1745365295
}.SIGNATURE

Un token ID include i seguenti campi:

Campo Nome Descrizione
aud Pubblico

Il client OAuth a cui è destinato questo token, identificato dal suo ID client OAuth.

I client OAuth possono ottenere token di accesso per altri client OAuth che appartengono allo stesso progetto. In questo caso, il pubblico potrebbe essere diverso dalla parte autorizzata.

azp Parte autorizzata Il client OAuth che ha eseguito il flusso di autenticazione OIDC, identificato dal suo ID client OAuth.
exp Scadenza L'ora di scadenza del token, nel formato ora epoca di Unix.
hd Dominio ospitato

Il dominio principale dell'account Cloud Identity o Google Workspace dell'utente.

Questa rivendicazione è presente solo se l'utente è un account utente gestito e il client ha specificato il parametro hd nella richiesta di autenticazione.

iss Emittente L'emittente del token. Sempre impostato su https://accounts.google.com.
sub Oggetto

L'entità autenticata, identificata dal suo ID univoco.

Questo ID è equivalente all'ID esposto nell' API Directory.

L'insieme esatto di rivendicazioni incluse in un token ID dipende dal parametro scope nella richiesta di autenticazione.

Per identificare se un utente è un account utente gestito o per identificare l'account Cloud Identity o Google Workspace a cui appartiene un utente, i client devono esaminare l'attestazione hd.

I token ID utente sono validi per un'ora e non possono essere revocati.

Token ID service account

I token ID service account sono token web JSON (JWT) che autenticano un service account.

A differenza dei JWT dell'account di servizio e delle asserzioni JWT dell'account di servizio, i token ID dell'account di servizio non sono firmati da una chiave dell'account di servizio. I token ID account di servizio, invece, sono firmati dal set di chiavi web JSON (JWKS) di Google.

Un token ID account di servizio decodificato ha un aspetto simile al seguente, con SIGNATURE sostituito dalla firma del token:

{
  "alg": "RS256",
  "kid": "c37da75c9fbe18c2ce9125b9aa1f300dcb31e8d9",
  "typ": "JWT"
}.{
  "aud": "example-audience",
  "azp": "112010400000000710080",
  "email": "service-account@example.iam.gserviceaccount.com",
  "email_verified": true,
  "exp": 1745365618,
  "iat": 1745362018,
  "iss": "https://accounts.google.com",
  "sub": "112010400000000710080"
}.SIGNATURE

Un token ID account di servizio include i seguenti campi:

Campo Nome Descrizione
aud Pubblico Identificatore della parte a cui è destinato questo token. Il valore può essere scelto liberamente dal richiedente del token.
azp Parte autorizzata Il account di servizio che ha richiesto il token, identificato dal suo ID univoco.
exp Scadenza L'ora di scadenza del token, nel formato ora epoca di Unix.
iss Emittente L'emittente del token, sempre impostata su https://accounts.google.com.
sub Oggetto Il account di servizio che ha richiesto il token, identificato dal suo ID univoco.

L'insieme esatto di rivendicazioni incluse in un token ID dipende dal modo in cui viene richiesto. Ad esempio, i token ID richiesti dal server metadati di Compute Engine possono includere facoltativamente rivendicazioni aggiuntive che asseriscono l'identità della VM. I token ID richiesti utilizzando l'API IAM Credentials possono facoltativamente contenere l'ID organizzazione del progetto del account di servizio.

A differenza dei token ID utente, i token ID account di servizio non supportano la rivendicazione hd.

I token ID service account sono validi per un'ora e non possono essere revocati.

Asserzioni di Identity-Aware Proxy

Le asserzioni Identity-Aware Proxy (IAP) sono token web JSON (JWT) che IAP passa alle applicazioni web protette da IAP nell'intestazione della richiesta HTTP x-goog-iap-jwt-assertion. Le asserzioni IAP autenticano un utente e fungono anche da prova che una richiesta è stata autorizzata da IAP.

A differenza dei token ID utente e dei token ID service account, le asserzioni IAP non sono firmate utilizzando il set di chiavi web JSON (JWKS) di Google. Le asserzioni IAP vengono invece firmate utilizzando un JWKS separato, il JWKS IAP. Questo JWKS è una risorsa globale e le stesse chiavi di firma vengono utilizzate per diversi tipi di utenti, tra cui:

  • Account utente gestiti

  • Account consumer

  • Account di servizio

  • Entità pool di identità della forza lavoro

Un'asserzione IAP decodificata è simile alla seguente, con SIGNATURE sostituito dalla firma del token:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "4BCyVw"
}.{
  "aud": "/projects/0000000000/global/backendServices/000000000000",
  "azp": "/projects/0000000000/global/backendServices/000000000000",
  "email": "user@example.com",
  "exp": 1745362883,
  "google": {
    "access_levels": [
      "accessPolicies/0000000000/accessLevels/Australia"
    ]
  },
  "hd": "example.com",
  "iat": 1745362283,
  "identity_source": "GOOGLE",
  "iss": "https://cloud.google.com/iap",
  "sub": "accounts.google.com:112010400000000710080"
}.SIGNATURE

Se configuri IAP in modo che utilizzi la federazione delle identità della forza lavoro anziché le identità Google, le asserzioni IAP hanno un aspetto leggermente diverso:

{
  "alg": "ES256",
  "typ": "JWT",
  "kid": "4BCyVw"
}.{
  "aud": "/projects/0000000000/global/backendServices/000000000000",
  "azp": "/projects/0000000000/global/backendServices/000000000000",
  "email": "user@example.com",
  "exp": 1745374290,
  "google": {
    "access_levels": [
      "accessPolicies/0000000000/accessLevels/Australia"
    ]
  },
  "iat": 1745373690,
  "identity_source": "WORKFORCE_IDENTITY",
  "iss": "https://cloud.google.com/iap",
  "sub": "sts.google.com:AAFTZ...Q",
  "workforce_identity": {
    "iam_principal": "principal://iam.googleapis.com/locations/global/workforcePools/example/subject/user-0000000000",
    "workforce_pool_name": "locations/global/workforcePools/example"
  }
}.SIGNATURE

Un'asserzione IAP include i seguenti campi:

Campo Nome Descrizione
aud Pubblico Il servizio di backend, l'applicazione App Engine o il servizio Cloud Run a cui è destinata l'asserzione IAP.
iss Emittente L'emittente del token, sempre impostata su https://cloud.google.com/iap
sub Oggetto

L'entità autenticata, identificata dal suo ID univoco.

Se IAP è configurato per utilizzare le identità Google, questo ID equivale all'ID esposto nell' API Directory.

Per ulteriori dettagli sulle rivendicazioni di asserzione IAP, consulta Verifica del payload JWT.

Le asserzioni IAP sono valide per 10 minuti e non possono essere revocate.

Asserzioni SAML

Le asserzioni SAML (Security Assertion Markup Language) autenticano un account utente gestito e lo autorizzano ad accedere a un'app SAML personalizzata. Le asserzioni SAML vengono emesse e firmate da Cloud Identity e possono essere utilizzate solo per autenticare gli account utente gestiti.

A differenza dei token ID, firmati utilizzando una chiave globale, le asserzioni SAML vengono firmate utilizzando una chiave specifica per un account Cloud Identity o Google Workspace.

Un'asserzione di risposta SAML decodificata è simile alla seguente:

<saml2:Assertion
  xmlns:saml2="urn:oasis:names:tc:SAML:2.0:assertion"
  ID="..."
  IssueInstant="2025-04-23T22:47:20.881Z"
  Version="2.0">
  <saml2:Issuer>
    https://accounts.google.com/o/saml2?idpid=C0123456789
  </saml2:Issuer>
  <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">...</ds:Signature>
  <saml2:Subject>
    <saml2:NameID
      Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
        user@example.com
    </saml2:NameID>
    <saml2:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
      <saml2:SubjectConfirmationData
        NotOnOrAfter="2025-04-23T22:52:20.881Z"
        Recipient="https://app.example.com/"/>
    </saml2:SubjectConfirmation>
  </saml2:Subject>

  <saml2:Conditions
    NotBefore="2025-04-23T22:42:20.881Z"
    NotOnOrAfter="2025-04-23T22:52:20.881Z">
    <saml2:AudienceRestriction>
      <saml2:Audience>example-app</saml2:Audience>
    </saml2:AudienceRestriction>
  </saml2:Conditions>

  <saml2:AuthnStatement
    AuthnInstant="2025-04-23T22:46:44.000Z"
    SessionIndex="...">
    <saml2:AuthnContext>
      <saml2:AuthnContextClassRef>
        urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
      </saml2:AuthnContextClassRef>
    </saml2:AuthnContext>
  </saml2:AuthnStatement>
</saml2:Assertion>

Un'asserzione SAML include i seguenti campi:

Campo Nome Descrizione
Audience Pubblico ID entità dell'app SAML.
Issuer Emittente Emittente del token, specifico per un account Cloud Identity o Google Workspace.
NameID Oggetto Il principal autenticato. Il formato dell'identificatore dipende dalla configurazione dell'app SAML.

L'insieme esatto di attributi inclusi in un'asserzione SAML dipende dalla configurazione dell'app SAML.

Le asserzioni SAML sono valide per 10 minuti e non possono essere revocate.