Tipi di token

La maggior parte dei token di accesso e di identità sono token di tipo bearer. I token di tipo Bearer concedono l'accesso alla parte in possesso del token, indipendentemente da come lo ha ottenuto. Se un malintenzionato intercetta un token di autenticazione, può utilizzarlo per ottenere un accesso non autorizzato.

I token vincolati concedono l'accesso a un client specifico. Per utilizzare un token vincolato, un client deve fornire ulteriori prove che dimostrino che è il legittimo proprietario del token. I token vincolati sono quindi più restrittivi dei token di tipo bearer e possono contribuire a ridurre il rischio di furto di token.

Token di accesso

I token di accesso consentono ai client di effettuare chiamate autenticate alle API Cloud de Confiance by S3NS . Cloud de Confiance by S3NS 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.

• Vengono 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.

• Principal: il tipo di principal 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:

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 esaminati. Gli altri token sono codificati come token web JSON, che può essere decodificato dal client.
• 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.
• Binding: alcuni token possono essere facoltativamente associati a un'ulteriore credenziale, il che li rende token associati.

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

Token di accesso al service account

I token di accesso al service account sono token di tipo bearer che autenticano un service account. I token sono opachi.

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

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

Un token del account di servizio include i seguenti campi:

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 all'account di servizio con durate superiori a un'ora.

Token web JSON del service account

I token web JSON (JWT) del service account sono token di connessione che autenticano un account di servizio. I token di accesso del service account vengono emessi da un server di autorizzazione, mentre 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 una data 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.s3ns.iam.gserviceaccount.com",
  "sub": "service-account@example.s3ns.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.s3ns.iam.gserviceaccount.com",
  "sub": "service-account@example.s3ns.iam.gserviceaccount.com",
  "aud": "https://cloudresourcemanager.googleapis.com/",
  "exp": 1744854799,
  "iat": 1744851199
}.SIGNATURE

Un JWT del account di servizio include i seguenti campi:

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 sono token di tipo bearer che autenticano un principal del pool di identità della forza lavoro o un principal del pool di identità del workload.

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à del pool di identità della forza lavoro è 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à del pool di identità del workload è identificata da un identificatore dell'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 sono impostate come segue:

• La federazione delle identità per la forza lavoro imposta la scadenza del token sul valore più piccolo tra i seguenti due:

  • Tempo rimanente prima della scadenza della sessione della federazione delle identità per la forza lavoro

  • 1 ora

  La scadenza della sessione della federazione delle identità per la forza lavoro è determinata in base all'ora di accesso e alla durata della sessione configurata per il pool di federazione delle 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 di accesso all'identità dell'agente

I token di accesso con identità dell'agente autenticano un agente a cui è stata assegnata un'identità dell'agente e utilizzano un identificatore principale simile al seguente:

principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/REASONING_ENGINE_ID

L'identificatore principale si basa sull'ID SPIFFE del certificato client X.509 dell'agente, ma utilizza il prefisso principal:// anziché spiffe://.

Un agente può ottenere un token di accesso all'identità dell'agente dal server di metadati Compute Engine. Se vuole, l'agente può richiedere che il token venga associato al proprio certificato client X.509. Un token di accesso con identità dell'agente associata è valido solo se utilizzato su una connessione mutual TLS autenticata utilizzando il certificato client X.509 a cui è stato associato il token.

Come i token di accesso federato, i token di accesso all'identità dell'agente sono opachi, non possono essere esaminati o revocati e rimangono validi fino alla scadenza. Per impostazione predefinita, i token di accesso all'identità dell'agente sono validi per 1 ora, ma la scadenza di un token potrebbe essere più breve se associato a un certificato client X.509 in scadenza.

Token del limite di accesso alle credenziali

I token di confine di accesso alle credenziali sono token di connessione che autenticano un utente o un account di servizio e includono un confine 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 è 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. Cloud de Confiance by S3NS supporta diversi tipi di token di concessione e tutti hanno in comune quanto segue:

• Rappresentano un'autenticazione precedente.

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

• Possono essere riscattati per ottenere un token di accesso.

• Non possono essere utilizzati per effettuare chiamate 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.

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 differiscono per durata e per il grado di modificabilità.

• Multi-uso: alcuni token che concedono gettoni 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.

• Binding: alcuni token sono associati a un'ulteriore credenziale, il che li rende token associati. Gli altri token non sono associati, il che li rende token di tipo bearer.

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

Token di aggiornamento federati

I token di aggiornamento federati sono token opachi che consentono ai client di ottenere token di accesso per un principal del pool di identità della forza lavoro, se l'utente ha precedentemente autorizzato un client ad agire per suo conto.

Come i token di aggiornamento, i token di aggiornamento federati 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.

A differenza dei token di aggiornamento, i token di aggiornamento federati non possono essere revocati. La durata di un token di aggiornamento federato è collegata alla sessione di identità della forza lavoro utilizzata per ottenere il token e rimane valida fino alla scadenza della sessione.

Codici di autorizzazione federati

Come i codici di autorizzazione, i codici di autorizzazione federata sono token opachi e di breve durata. I codici sono destinati all'uso solo durante l'autenticazione dell'utente come intermediario tra il client e il server di autorizzazione IAM Cloud de Confiance by S3NS .

I codici di autorizzazione sono associati a un client, possono essere utilizzati solo in combinazione con credenziali client valide e possono essere utilizzati una sola volta.

Token web JSON esterni

I token web JSON (JWT) 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 workload, puoi configurare una relazione di trust tra Cloud de Confiance by S3NS 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'entità del pool di identità della forza lavoro.

Quando utilizzi la federazione delle identità per i workload, il token di accesso federato risultante autentica un'entità del pool di identità del workload.

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à per i 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, ad esempio 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à per i 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 workload, le asserzioni SAML esterne devono soddisfare requisiti specifici.

Token Amazon Web Services (AWS) GetCallerIdentity

I token AWS GetCallerIdentity esterni sono blob di testo che contengono una richiesta firmata all'API GetCallerIdentity di AWS. Analogamente ai token web JSON esterni, 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. Cloud de Confiance by S3NS supporta diversi tipi di token ID e tutti hanno in comune quanto segue:

• Sono firmati ma non criptati, in modo che possano essere decodificati, verificati e interpretati dal client.

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

• Vengono 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 i 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.

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

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

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

• Formato: alcuni token sono token web JSON (JWT), altri utilizzano la formattazione XML.

• Durata: i token hanno durate diverse.

• Binding: alcuni token possono essere facoltativamente associati a un'ulteriore credenziale, il che li rende token associati.

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

Token ID account di servizio

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

A differenza dei JWT del service account e delle asserzioni JWT del service account, i token ID del account di servizio non sono firmati da una chiave del account di servizio. I token ID account di servizio sono invece 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.s3ns.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:

L'insieme esatto di attestazioni incluse in un token ID dipende dal modo in cui viene richiesto. Ad esempio, i token ID richiesti dal server dei 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.

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

Token ID identità agente

I token ID identità agente sono documenti di identità verificabili SPIFFE (JWT-SVID) e autenticano un agente a cui è stata assegnata un' identità agente.

Un agente può ottenere un token ID dal server dei metadati Compute Engine. Se vuole, l'agente può richiedere che il token venga associato al certificato client X.509. Un token ID identità agente vincolato contiene l'impronta del certificato client X.509 ed è valido solo se utilizzato su una connessione mutual TLS autenticata utilizzando lo stesso certificato client X.509.

A differenza dei token ID utente e dei token ID service account, i token ID identità agente non sono firmati dal set di chiavi web JSON (JWKS) di Google e non possono essere verificati.

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

{
  "alg": "RS256",
  "kid": "78ab40e4a0319f9ced58024f5bb66e6387d68066",
  "typ": "JWT"
}.{
  "iss": "https://sts.googleapis.com/v1/organizations/1234567890/locations/global/workloadIdentityPools/agents.global.org-1234567890.system.id.goog",
  "sub": "spiffe://agents.global.org-1234567890.system.id.goog/resources/aiplatform/projects/1234567890/locations/us-central1/reasoningEngines/987654321",
  "aud": ["https://example.com/"],
  "iat": 1775776191,
  "exp": 1775779791,
  "cnf": {
    "x5t#S256": "QTB5TSHeDxHrzDzcrrHU+/shhkfCnARcBEvMldp2uis"
  }
}.SIGNATURE

Un token ID identità agente include i seguenti campi:

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.

• Account utente gestiti

• Account consumer

• Service account

• 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": 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:

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.