Iniziare a utilizzare la libreria di autenticazione Google

Panoramica

Google Auth Library è una libreria client di autenticazione open source per Java. Questo documento descrive come utilizzare questa libreria per autenticare le tue applicazioni Java per accedere ai servizi Google Cloud .

Seguendo questa guida, imparerai a:

  • Aggiungi le dipendenze necessarie della libreria di autenticazione al tuo progetto utilizzando Maven, Gradle o Simple Build Tool (SBT).
  • Eseguire l'autenticazione utilizzando vari metodi, con particolare attenzione alle credenziali predefinite dell'applicazione (ADC).
  • Configura scenari di autenticazione avanzati, tra cui la federazione Workload Identity, la federazione delle identità per la forza lavoro e la simulazione dell'identità dei account di servizio.
  • Genera e utilizza token con ambito ridotto per limitare le autorizzazioni.
  • Integra le credenziali con le librerie client HTTP di Google.

Questa documentazione è rivolta agli sviluppatori Java. Per i dettagli completi sull'API, consulta la documentazione dell'API Google Auth Library.

La libreria di autenticazione Google per Java è composta da quattro artefatti:

  • google-auth-library-credentials contiene classi base e interfacce per le credenziali Google.
  • google-auth-library-appengine contiene le credenziali di App Engine e dipende dall'SDK App Engine.
  • google-auth-library-oauth2-http contiene una serie di credenziali e metodi di utilità, tra cui funzionalità per ottenere le credenziali predefinite dell'applicazione. Fornisce inoltre l'approccio lato server per la generazione di token con ambito ridotto.
  • google-auth-library-cab-token-generator fornisce l'approccio lato client per la generazione di token con ambito ridotto.

Convalida le configurazioni delle credenziali

Quando utilizzi configurazioni delle credenziali, come JSON, percorsi file o stream, da una fonte esterna, devi convalidarle. Fornire credenziali non convalidate alle API di Google o alle librerie client per l'autenticazione suGoogle Cloud può compromettere la sicurezza dei tuoi sistemi e dei tuoi dati.

Per saperne di più, consulta Credenziali di origine esterna. Credenziali predefinite.

Importa la libreria Auth

Per importare la libreria Auth, utilizza com.google.cloud:libraries-bom o la distinta base della libreria Auth di Google con Maven o Gradle.

Librerie SDK Java-bom

Per autenticarti in una libreria client nell'SDK Java (ad esempio google-cloud-datastore) utilizzando la libreria di autenticazione, utilizza libraries-bom, che recupererà le versioni della libreria di autenticazione compatibili con quella libreria client.

Ad esempio, per importare la libreria Auth con Maven utilizzando un pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Se non utilizzi libraries-bom o altre librerie client, importa i moduli Auth direttamente con la distinta base della libreria di autenticazione Google.

Distinta base della libreria di autenticazione Google

Puoi utilizzare la distinta base della libreria di autenticazione Google per assicurarti che i moduli di autenticazione e le relative dipendenze transitive siano compatibili.

Maven

Aggiungi quanto segue al tuo file pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Nella sezione <dependencies>, puoi specificare uno qualsiasi dei moduli Auth necessari. Ad esempio, per includere il modulo google-auth-library-oauth2-http, aggiungi il seguente elemento <dependency>:

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

Sostituisci google-auth-library-oauth2-http nell'esempio con google-auth-library-credentials o google-auth-library-appengine, a seconda delle esigenze della tua applicazione.

Gradle

Analogamente a Maven, gli utenti di Gradle possono utilizzare google-auth-library-bom per gestire le versioni delle dipendenze e garantire la compatibilità tra i diversi moduli google-auth-library.

Per utilizzare la distinta base (BOM) con Gradle, aggiungila come dipendenza platform. Poi, aggiungi i moduli google-auth-library di cui hai bisogno. La distinta base garantisce che le versioni di tutti i moduli che utilizzi siano compatibili. Ad esempio, aggiungi quanto segue al file build.gradle:

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

A differenza di Maven e Gradle, SBT (Scala Build Tool) non supporta le distinte base (BOM) di Maven. Di conseguenza, quando utilizzi Scala, non puoi importare la google-auth-library-bom per gestire automaticamente le versioni compatibili dei moduli della libreria Auth e delle relative dipendenze transitive.

Dovrai invece aggiungere ogni sottomodulo richiesto direttamente al file build.sbt. È fondamentale specificare e allineare in modo esplicito le versioni di tutti i moduli google-auth-library che utilizzi. Se non mantieni la coerenza delle versioni, possono verificarsi conflitti tra le versioni delle dipendenze transitive, con il rischio di causare comportamenti imprevisti o errori di runtime nell'applicazione.

Aggiungi questo alle tue dipendenze se utilizzi SBT:

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

Logging della libreria Auth

La libreria Java Auth consiglia di eseguire il logging utilizzando il logging di debug della libreria client. Il logging di debug eseguirà l'hashing dei token sensibili (ad es. access_token, refresh_token e così via) e i valori verranno mascherati. Il logging con java.util.logging è disabilitato nella libreria Auth per impedire la fuga di token sensibili.

La funzionalità di logging di debug del client è facoltativa e richiede la configurazione.

Il logging di debug può registrare quanto segue in base al livello di log:

  • Informazioni sulla richiesta: intestazioni, URL, metodo (livello INFO)
  • Informazioni sulla risposta: intestazioni, stato, messaggio (livello INFO)
  • Payload della risposta (livello DEBUG)

Esegui la migrazione da GoogleCredential a GoogleCredentials

GoogleCredential di google-api-java-client è deprecato e GoogleCredentials è la sostituzione consigliata.

Crea un'istanza di GoogleCredentials utilizzando le Credenziali predefinite dell'applicazione (ADC). Questo è l'approccio consigliato:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

Il modo in cui utilizzi GoogleCredentials dipende dalla libreria client:

Credenziali predefinite dell'applicazione

La libreria di autenticazione Google fornisce un'implementazione delle Credenziali predefinite dell'applicazione (ADC) per Java. Le ADC forniscono un modo per ottenere le credenziali di autorizzazione per chiamare le API di Google.

Utilizza ADC quando la tua applicazione richiede un livello di identità e autorizzazione coerente, indipendentemente dall'utente. Ti consigliamo di utilizzare ADC per autorizzare le chiamate alle API Cloud, soprattutto quando crei applicazioni su Google Cloud.

ADC supporta anche la federazione delle identità per i workload, consentendo alle applicazioni di accedere alle risorse Google Cloud da piattaforme esterne come Amazon Web Services (AWS), Microsoft Azure o qualsiasi provider di identità che supporti OpenID Connect (OIDC). Ti consigliamo la federazione delle identità per i workload per gli ambienti nonGoogle Cloud perché elimina la necessità di scaricare, gestire e archiviare localmente le chiavi private dei account di servizio.

Ottieni le Credenziali predefinite dell'applicazione

Per ottenere le Credenziali predefinite dell'applicazione, utilizza GoogleCredentials.getApplicationDefault() o GoogleCredentials.getApplicationDefault(HttpTransportFactory). Questi metodi restituiscono le Credenziali predefinite dell'applicazione per identificare e autorizzare l'intera applicazione.

Per trovare le credenziali predefinite dell'applicazione, vengono eseguite ricerche nei seguenti elementi, in questo ordine:

  1. File delle credenziali a cui punta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.
  2. Credenziali fornite dal comando gcloud auth application-default login di Google Cloud SDK.
  3. Credenziali integrate di Google App Engine.
  4. Google Cloud Credenziali integrate della shell.
  5. Credenziali integrate di Google Compute Engine.
    • Salta questo controllo impostando la variabile di ambiente NO_GCE_CHECK=true.
    • Personalizza l'indirizzo del server di metadati impostando la variabile di ambiente GCE_METADATA_HOST=<hostname>.

Caricamento esplicito delle credenziali

Per ottenere le credenziali da una chiave JSON del service account, utilizza GoogleCredentials.fromStream(InputStream) o GoogleCredentials.fromStream(InputStream, HttpTransportFactory) come mostrato nel seguente codice di esempio.

Le credenziali devono essere aggiornate prima che il token di accesso sia disponibile.

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

Credenziali di simulazione dell'identità

Utilizza ImpersonatedCredentials per consentire a una credenziale (l'entità) di impersonare un account di servizio (la destinazione). In questo modo, l'entità può accedere alle risorse come target, senza bisogno della chiave privata del target.

Per utilizzare ImpersonatedCredentials, devi soddisfare i seguenti requisiti:

  • Il progetto dell'entità deve avere l'API IAMCredentials abilitata.
  • L'entità deve avere il ruolo Service Account Token Creator (Identity and Access Management) nel account di servizio di destinazione.

Il seguente esempio di codice crea ImpersonatedCredentials. La credenziale dell'entità viene ottenuta dalle Credenziali predefinite dell'applicazione (ADC). I ImpersonatedCredentials risultanti vengono quindi utilizzati per accedere a Google Cloud Storage come account di servizio di destinazione.

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "impersonated-account@project.")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

Token associati ai certificati per le identità degli agenti

Quando l'applicazione viene eseguita con un'identità dell'agente (ad esempio, un servizio o un job Cloud Run di cui è stato eseguito il deployment con --identity-type=agent-identity), ComputeEngineCredentials richiede per impostazione predefinita token di accesso e token ID associati al certificato dal server dei metadati. Un token associato è collegato al certificato X.509 del workload e richiede la dimostrazione del possesso della chiave privata corrispondente tramite mutual TLS (mTLS). Poiché la chiave privata è disponibile solo per il workload, un token divulgato non può essere utilizzato da nessun'altra posizione.

Un token associato viene accettato solo quando la richiesta che lo contiene viene inviata tramite mTLS con lo stesso certificato. Le librerie client di Cloud per Java configurano mTLS e ricaricano automaticamente i certificati dei workload ruotati quando l'identità dell'agente è abilitata. Se chiami le API di Google con il tuo client HTTP, devi configurare mTLS con il certificato del workload e ricaricarlo quando il runtime ruota il certificato sul disco. Dopo la rotazione, i token di aggiornamento appena aggiornati vengono associati al nuovo certificato. Se un nuovo token viene inviato tramite una connessione mTLS stabilita con il certificato precedente, l'API rifiuta la richiesta con 401 UNAUTHENTICATED.

La libreria richiede un token associato solo se sono soddisfatte tutte le seguenti condizioni:

  • Viene trovato un certificato del workload, tramite il file denominato dalla variabile di ambiente GOOGLE_API_CERTIFICATE_CONFIG o nella posizione predefinita (/var/run/secrets/workload-spiffe-credentials/).
  • L'ID SPIFFE del certificato appartiene a un dominio di attendibilità dell'identità dell'agente.
  • L'associazione dei token e mTLS non sono stati disattivati (consulta Disattiva l'associazione dei token).

In tutti gli altri ambienti, ComputeEngineCredentials si comporta come prima e restituisce token non associati.

Disattiva l'associazione dei token

Se devi disattivare l'associazione dei token (vedi Limitazioni note), imposta la seguente variabile di ambiente:

GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false
Variabile di ambiente Effetto
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN Imposta su false per richiedere token non associati.
GOOGLE_API_USE_CLIENT_CERTIFICATE Se imposti questo criterio su false, mTLS viene disattivato completamente, il che disattiva anche l'associazione dei token. Preferisci GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false se hai bisogno solo di token non associati.

I valori non fanno distinzione tra maiuscole e minuscole e gli spazi vuoti circostanti vengono ignorati. Solo false disattiva una funzionalità; qualsiasi altro valore lascia invariata l'impostazione predefinita.

Le variabili di ambiente si applicano all'intero processo, quindi la disattivazione dell'associazione dei token influisce su ogni libreria della tua applicazione che utilizza le Credenziali predefinite dell'applicazione, non solo su quella che ne ha bisogno. Se hai bisogno di token ID non associati solo per alcuni target, utilizza l'opzione per target descritta in Richiedi token ID non associati per target specifici.

Richiedi token ID non associati per target specifici

Un token ID associato include il fingerprint del certificato del workload nella sua attestazione cnf (x5t#S256). I servizi di ricezione possono convalidare questa attestazione rispetto al certificato client presentato durante un handshake mTLS o ignorarla se non applicano l'associazione del certificato.

Cloud Run applica automaticamente l'associazione dei certificati quando la rivendicazione cnf è presente in un token ID. Se chiami un servizio Cloud Run con un token ID associato, devi chiamare il relativo URL *.mtls.run.app tramite mTLS. Le richieste a un URL *.run.app standard o a un dominio personalizzato senza mTLS vengono rifiutate con 401 Unauthorized.

Se chiami un servizio che applica l'associazione dei certificati su un endpoint non mTLS (ad esempio un URL *.run.app standard) o se non hai bisogno dell'associazione dei certificati per un endpoint di destinazione, passa IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN per richiedere un token ID non associato solo per quella destinazione:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
IdTokenCredentials idTokenCredentials =
    IdTokenCredentials.newBuilder()
        .setIdTokenProvider((IdTokenProvider) credentials)
        .setTargetAudience("https://my-service-12345.us-central1.run.app")
        .setOptions(Arrays.asList(IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN))
        .build();

I token di accesso e i token ID per altri target sono ancora associati. Questa opzione è supportata solo da ComputeEngineCredentials; altre implementazioni di IdTokenProvider non richiedono token ID associati e ignorano questa opzione, pertanto lo stesso codice funziona anche al di fuori degli ambienti di identità degli agenti.

Limitazioni note

  • Agent Development Kit (ADK) per Java non utilizza mTLS quando chiama le API di Google, come Gemini su Vertex AI. Con i token associati (impostazione predefinita), queste chiamate non vanno a buon fine e restituiscono l'errore com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials. Per risolvere questo problema, imposta GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false per gli agenti che utilizzano ADK per Java. Per saperne di più, consulta Autentica gli agenti su Cloud Run.

Federazione delle identità per i workload

La federazione delle identità per i workload consente alla tua applicazione di accedere alle risorse Google Clouddi Amazon Web Services (AWS), Microsoft Azure o di qualsiasi provider di identità che supporti OpenID Connect (OIDC).

In genere, le applicazioni in esecuzione al di fuori di Google Cloud utilizzano le chiavi dei service account per accedere alle risorse Google Cloud . Utilizzando la federazione delle identità, il tuo workload può simulare l'identità di un account di servizio. In questo modo, il workload esterno può accedere direttamente alle risorse Google Cloud , eliminando l'onere di manutenzione e sicurezza associato alle chiavi dei account di servizio.

Accesso alle risorse da AWS

Per accedere alle risorse Google Cloud da Amazon Web Services (AWS), devi prima configurare la federazione delle identità per i workload. La procedura di configurazione è descritta in dettaglio in Accesso alle risorse da AWS.

Nell'ambito di questa procedura, genererai un file di configurazione delle credenziali. Questo file contiene metadati non sensibili che indicano alla libreria come recuperare i token oggetto esterni e scambiarli con i token di accesso del account di servizio. Puoi generare il file utilizzando Google Cloud CLI:

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • AWS_PROVIDER_ID: l'ID provider AWS.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio di cui simulare l'identità.

L'esempio genera il file di configurazione nel file di output specificato.

Se utilizzi AWS IMDSv2, devi aggiungere un flag aggiuntivo --enable-imdsv2 al comando gcloud iam workload-identity-pools create-cred-config:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

Ora puoi utilizzare la libreria Auth per chiamare le risorseGoogle Cloud da AWS.

Accesso alle risorse da Microsoft Azure

Per accedere alle risorse Google Cloud da Microsoft Azure, devi prima configurare la federazione delle identità dei workload. La procedura di configurazione è descritta in Accesso alle risorse da Azure.

Nell'ambito di questa procedura, genererai un file di configurazione delle credenziali. Questo file contiene metadati non sensibili che indicano alla libreria come recuperare i token oggetto esterni e scambiarli con i token di accesso del account di servizio. Puoi generare il file utilizzando Google Cloud CLI:

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • AZURE_PROVIDER_ID: l'ID provider Azure.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio di cui simulare l'identità.

Questo comando genera il file di configurazione nel file di output specificato.

Ora puoi utilizzare la libreria Auth per chiamare le risorse Google Cloudda Azure.

Accesso alle risorse da un provider di identità OIDC

Per accedere alle risorse Google Cloud da un provider di identità che supporta OpenID Connect (OIDC), devi prima configurare la federazione delle identità dei workload, come descritto in Configurazione della federazione delle identità dei workload da un provider di identità OIDC.

Nell'ambito di questo processo, genererai un file di configurazione delle credenziali utilizzando Google Cloud CLI. Questo file contiene metadati non sensibili che indicano alla libreria come recuperare i token oggetto esterni e scambiarli con i token di accesso del account di servizio.

Per i provider OIDC, la libreria Auth può recuperare i token OIDC da un file locale (credenziali provenienti da file), da un server locale (credenziali provenienti da URL) o da una combinazione di certificato X.509 e chiave privata (credenziali provenienti da certificato X.509).

Credenziali provenienti da file

Per le credenziali provenienti da file, un processo in background deve aggiornare continuamente la posizione del file con un nuovo token OIDC prima della scadenza. Per i token con una durata di un'ora, devi aggiornare il token nel file ogni ora. Puoi archiviare il token direttamente come testo normale o in formato JSON.

Per generare una configurazione OIDC basata su file, esegui questo comando:

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • OIDC_PROVIDER_ID: l'ID del provider OIDC.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio di cui simulare l'identità.
  • PATH_TO_OIDC_ID_TOKEN: il percorso utilizzato per recuperare il token OIDC.

Questo comando genera il file di configurazione nel file di output specificato.

Credenziali provenienti da URL

Per le credenziali provenienti da un URL, un server locale deve ospitare un endpoint GET che fornisce un token OIDC in formato testo normale o JSON. Puoi specificare intestazioni HTTP aggiuntive da inviare nella richiesta del token, se richiesto dall'endpoint.

Per generare una configurazione dell'identità del Workload Identity OIDC con origine URL, esegui il seguente comando:

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • OIDC_PROVIDER_ID: l'ID del provider OIDC.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio di cui simulare l'identità.
  • URL_TO_GET_OIDC_TOKEN: l'URL dell'endpoint del server locale da chiamare per recuperare il token OIDC.
  • HEADER_KEY e HEADER_VALUE: le coppie chiave-valore dell'intestazione aggiuntive da passare insieme alla richiesta GET a URL_TO_GET_OIDC_TOKEN, ad esempio Metadata-Flavor=Google.

Ora puoi utilizzare la libreria Auth per chiamare le risorseGoogle Cloud da un provider OIDC.

Accedi alle risorse utilizzando le credenziali provenienti da certificati X.509

Per le credenziali provenienti da certificati X.509, la libreria di autenticazione utilizza un certificato X.509 e una chiave privata per dimostrare l'identità della tua applicazione. I certificati X.509 includono una data di scadenza e devono essere rinnovati prima della scadenza per mantenere l'accesso.

Per saperne di più, consulta la documentazione ufficiale.

Genera i file di configurazione per la federazione X.509

Per configurare le credenziali provenienti da certificati X.509, devi generare due file separati: un file di configurazione delle credenziali principali e un file di configurazione del certificato.

  • Il file di configurazione delle credenziali principali contiene i metadati necessari per l'autenticazione. Questo file fa riferimento anche al file di configurazione del certificato.
  • Il file di configurazione del certificato specifica i percorsi dei file per il certificato X.509, la chiave privata e la catena di attendibilità.

Il comando gcloud iam workload-identity-pools create-cred-config può essere utilizzato per creare entrambi.

La posizione in cui gcloud crea il file di configurazione del certificato dipende dall'utilizzo o meno del flag --credential-cert-configuration-output-file.

Se ometti il flag --credential-cert-configuration-output-file, gcloud crea il file di configurazione del certificato in una posizione predefinita e nota che la libreria Auth può rilevare automaticamente. Questo approccio è adatto alla maggior parte dei casi d'uso. Il file di configurazione delle credenziali predefinito è denominato config.json e il file di configurazione del certificato predefinito è denominato certificate_config.json.

Ad esempio, esegui questo comando per creare i file di configurazione utilizzando il comportamento predefinito:

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • PROVIDER_ID: l'ID provider.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio di cui simulare l'identità.
  • PATH_TO_CERTIFICATE: il percorso in cui si trova il certificato X.509 foglia.
  • PATH_TO_PRIVATE_KEY: il percorso in cui si trova la chiave privata corrispondente per il certificato foglia.
  • PATH_TO_TRUST_CHAIN: il percorso del file della catena di attendibilità del certificato X.509. Questo file deve essere in formato PEM e contenere tutti i certificati intermedi necessari per completare la catena di attendibilità tra il certificato foglia e l'archivio di attendibilità configurato nel pool di federazione delle identità per i workload. Il certificato foglia è facoltativo in questo file.

Questo comando genera quanto segue:

  • /path/to/config.json: creato nel percorso specificato. Questo file conterrà "use_default_certificate_config": true per indicare ai client di cercare la configurazione del certificato nel percorso predefinito.
  • certificate_config.json: Creato nel percorso di configurazione predefinito di Google Cloud CLI, che in genere è ~/.config/gcloud/certificate_config.json su Linux e macOS, oppure %APPDATA%\gcloud\certificate_config.json su Windows.

Comportamento della posizione personalizzata

Se devi archiviare il file di configurazione del certificato in una posizione non predefinita, utilizza il flag --credential-cert-configuration-output-file.

Comando di esempio (località personalizzata):

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

Questo comando genera:

  • /path/to/config.json: creato nel percorso specificato. Questo file conterrà un campo "certificate_config_location" che rimanda al tuo percorso personalizzato.
  • cert_config.json: creato in /custom/path/cert_config.json, come specificato dal flag.

Ora puoi utilizzare la libreria Auth per chiamare le risorseGoogle Cloud con credenziali provenienti da certificati X.509.

Utilizza le credenziali provenienti da un eseguibile con OIDC e SAML

Per le credenziali provenienti da un eseguibile, viene utilizzato un eseguibile locale per recuperare il token di terze parti. L'eseguibile deve fornire un token ID OIDC o un'asserzione SAML validi e non scaduti in formato JSON a stdout.

Per utilizzare le credenziali provenienti da un eseguibile, la variabile di ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES deve essere impostata su 1.

Per generare una configurazione di Workload Identity con origine eseguibile, esegui il seguente comando:

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • PROVIDER_ID: l'ID provider OIDC o SAML.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio di cui simulare l'identità.
  • SUBJECT_TOKEN_TYPE: il tipo di token del soggetto.
  • EXECUTABLE_COMMAND: il comando completo da eseguire, inclusi gli argomenti. Deve essere un percorso assoluto al programma.

Il flag --executable-timeout-millis è facoltativo e specifica la durata (in millisecondi) per cui la libreria Auth attenderà il completamento dell'eseguibile. Se non viene fornito, il valore predefinito è 30 secondi. Il valore massimo consentito è di due minuti, mentre il valore minimo è di cinque secondi.

Il flag facoltativo --executable-output-file specifica un percorso per memorizzare nella cache la risposta delle credenziali di terze parti dell'eseguibile. La memorizzazione nella cache contribuisce a migliorare le prestazioni perché le librerie di autenticazione controllano prima questo file per verificare la presenza di credenziali valide e non scadute prima di eseguire l'eseguibile. Se esistono credenziali valide memorizzate nella cache, le librerie le utilizzano, evitando esecuzioni non necessarie dell'eseguibile.

Il file eseguibile deve scrivere la risposta della credenziale in questo file. Le librerie di autenticazione leggono solo da questa posizione. I contenuti del file devono corrispondere al formato JSON previsto.

Per recuperare il token di terze parti, la libreria eseguirà l'eseguibile utilizzando il comando specificato. L'output dell'eseguibile deve rispettare il formato di risposta specificato negli esempi seguenti e deve restituire la risposta a stdout.

Ecco un esempio di risposta OIDC eseguibile con esito positivo:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Ecco un esempio di risposta SAML eseguibile riuscita:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Quando specifichi un file di output utilizzando l'argomento --executable-output-file nella configurazione delle credenziali, le risposte dell'eseguibile andate a buon fine devono includere un campo expiration_time. In questo modo, la libreria di autenticazione può memorizzare nella cache e gestire in modo efficace la validità delle credenziali archiviate nel file.

Ecco un esempio di risposta di errore eseguibile:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Questi sono tutti i campi obbligatori per una risposta di errore. La libreria utilizza i campi code e message come parte di un'eccezione generata.

Riepilogo dei campi del formato di risposta: * version: la versione dell'output JSON. È supportata solo la versione 1. * success: Se vero, la risposta deve includere il token di terze parti e il tipo di token. La risposta deve includere anche il campo expiration_time se è stato specificato un file di output nella configurazione delle credenziali. L'eseguibile deve inoltre terminare con un codice di uscita pari a 0. Se è false, la risposta deve includere i campi del codice di errore e del messaggio e uscire con un valore diverso da zero. * token_type: Questo campo specifica il tipo di token del soggetto di terze parti. Deve essere urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token o urn:ietf:params:oauth:token-type:saml2. * id_token: il token OIDC di terze parti. * saml_response: la risposta SAML di terze parti. * expiration_time: la data e l'ora di scadenza del token del soggetto di terze parti in secondi (epoca di Unix). * code: la stringa del codice di errore. * message: il messaggio di errore.

Tutti i tipi di risposta devono includere i campi version e success. * Le risposte riuscite devono includere token_type e uno tra id_token o saml_response. Il campo expiration_time deve essere presente anche se è stato specificato un file di output nella configurazione delle credenziali. * Le risposte di errore devono includere sia il campo code sia il campo message.

La libreria compila le seguenti variabili di ambiente quando esegue l'eseguibile:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: il campo audience della configurazione delle credenziali. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: questo tipo di token soggetto previsto. Sempre presente.
  • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: l'indirizzo email del account di servizio. Presente solo quando viene utilizzata la simulazione dell'identità dei account di servizio.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: la posizione del file di output dalla configurazione delle credenziali. Presente solo se specificato nella configurazione delle credenziali.

Queste variabili di ambiente possono essere utilizzate dall'eseguibile per evitare di impostare questi valori come hardcoded.

Considerazioni sulla sicurezza

Si consiglia di adottare le seguenti pratiche di sicurezza:

  • Impedisci a processi non autorizzati di eseguire l'eseguibile, perché questo restituirà credenziali sensibili a questi processi e ai loro utenti tramite stdout.
  • Impedisci a processi non autorizzati di alterare la configurazione o la chiamata dell'eseguibile.

A causa della complessità dell'utilizzo di credenziali provenienti da eseguibili, ti consigliamo vivamente di utilizzare altri meccanismi supportati, come origini file o URL, per fornire credenziali di terze parti, a meno che non soddisfino i tuoi requisiti specifici.

Ora puoi utilizzare la libreria Auth per chiamare le risorseGoogle Cloud da un provider OIDC o SAML.

Utilizza un fornitore personalizzato con OIDC e SAML

È possibile utilizzare un'implementazione personalizzata di IdentityPoolSubjectTokenSupplier durante la creazione di IdentityPoolCredentials per fornire un token soggetto che può essere scambiato con un token di accesso Google Cloud . Il fornitore deve restituire un token soggetto valido e non scaduto quando viene chiamato dalla credenziale Google Cloud.

IdentityPoolCredentials non memorizza nella cache il token restituito, quindi implementa la logica di memorizzazione nella cache nel fornitore di token per impedire più richieste per lo stesso token del soggetto.

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

Dove si trova il pubblico:

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • WORKLOAD_POOL_ID: l'ID del pool di identità del workload.
  • PROVIDER_ID: l'ID provider.

Puoi anche trovare i valori per il pubblico, l'URL di simulazione dell'identità dei account di servizio e qualsiasi altro campo del builder generando un file di configurazione delle credenziali con gcloud CLI.

Utilizza un fornitore personalizzato con AWS

È possibile fornire un'implementazione personalizzata di AwsSecurityCredentialsSupplier durante l'inizializzazione di AwsCredentials. Se fornito, l'istanza AwsCredentials si affiderà al fornitore per recuperare le credenziali di sicurezza AWS da scambiare con un token di accessoGoogle Cloud . Il fornitore deve restituire credenziali di sicurezza AWS valide e non scadute quando viene chiamato dalla credenziale Google Cloud .

AwsCredentials non memorizza nella cache le credenziali di sicurezza o la regione AWS restituite, quindi implementa la logica di memorizzazione nella cache nel fornitore per evitare più richieste per le stesse risorse.

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

Dove il pubblico è: //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • WORKLOAD_POOL_ID: l'ID del pool di identità del workload.
  • PROVIDER_ID: l'ID provider.

Puoi anche trovare i valori per il pubblico, l'URL di simulazione dell'identità dei account di servizio e qualsiasi altro campo del builder generando un file di configurazione delle credenziali con gcloud CLI.

Durata del token configurabile

Quando crei una configurazione delle credenziali con la federazione delle identità per i workload utilizzando la simulazione dell'identità dei account di servizio, puoi fornire un argomento facoltativo per configurare la durata del token di accesso del account di servizio.

Per generare la configurazione con una durata del token configurabile, esegui il seguente comando (questo esempio utilizza una configurazione AWS, ma la durata del token può essere configurata per tutti i provider di federazione delle identità dei workload):

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

Sostituisci quanto segue:

  • PROJECT_NUMBER: il numero di progetto Google Cloud .
  • POOL_ID: l'ID del pool di identità del workload.
  • AWS_PROVIDER_ID: l'ID provider AWS.
  • SERVICE_ACCOUNT_EMAIL: l'indirizzo email del account di servizio di cui simulare l'identità.
  • TOKEN_LIFETIME: la durata selezionata del token di accesso del account di servizio in secondi.

Il flag service-account-token-lifetime-seconds è facoltativo. Se non viene fornito, il flag assume il valore predefinito di un'ora. Il valore minimo consentito è 600 (10 minuti) e il valore massimo consentito è 43.200 (12 ore). Se hai bisogno di una durata superiore a un'ora, devi aggiungere il service account come valore consentito in un servizio policy dell'organizzazione che applica il vincolo constraints/iam.allowServiceAccountCredentialLifetimeExtension.

La configurazione di una durata breve (ad esempio 10 minuti) fa sì che la libreria avvii l'intero flusso di scambio dei token ogni 10 minuti. In questo modo viene chiamato il provider di token di terze parti anche se il token di terze parti non è scaduto.

Utilizza le credenziali della forza lavoro dell'utente autorizzato dell'account esterno

Le credenziali utente autorizzate dell'account esterno ti consentono di accedere con un browser web a un account provider di identità esterno utilizzando gcloud CLI e di creare una configurazione che la libreria di autenticazione può utilizzare.

Per generare una configurazione dell'identità della forza lavoro per un utente autorizzato di un account esterno, esegui questo comando:

gcloud auth application-default login --login-config=LOGIN_CONFIG

Dove è necessario sostituire la seguente variabile:

In questo modo si apre un flusso del browser che ti consente di accedere utilizzando il provider di identità di terze parti configurato. Quindi, archivia la configurazione dell'utente autorizzato dell'account esterno nella posizione ADC nota.

La libreria Auth utilizzerà quindi il token di aggiornamento fornito dalla configurazione per generare e aggiornare un token di accesso per chiamare i servizi Google Cloud .

La durata predefinita del token di aggiornamento è di un'ora. Dopodiché, devi generare una nuova configurazione da gcloud CLI. Puoi modificare la durata cambiando la durata della sessione del pool di forza lavoro e puoi impostarla su un massimo di 12 ore.

Utilizza identità esterne

Puoi utilizzare le identità esterne con Application Default Credentials. Per utilizzare le identità esterne con le Credenziali predefinite dell'applicazione, genera il file di configurazione delle credenziali JSON per la tua identità esterna come descritto nella sezione Federazione delle identità per i workload. Una volta generato, archivia il percorso di questo file nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

La libreria può ora scegliere il tipo di client corretto e inizializzare le credenziali dal contesto fornito dal file di configurazione.

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

Puoi anche inizializzare in modo esplicito i client degli account esterni utilizzando il file di configurazione generato.

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

Considerazioni sulla sicurezza

Questa libreria non esegue alcuna convalida sui campi token_url, token_info_url o service_account_impersonation_url della configurazione delle credenziali. Ti sconsigliamo di utilizzare una configurazione delle credenziali che non hai generato con gcloud CLI, a meno che non verifichi che i campi URL puntino a un dominio googleapis.com.

Riduzione dell'ambito mediante confini per l'accesso con credenziali

La riduzione dell'ambito con i limiti di accesso alle credenziali consente di limitare le autorizzazioni di Identity and Access Management (IAM) che una credenziale di breve durata può utilizzare per Cloud Storage. Ciò comporta la creazione di un CredentialAccessBoundary che definisce le limitazioni che si applicano al token con ambito ridotto. L'utilizzo di credenziali con ambito ridotto garantisce che i token in transito abbiano sempre i privilegi minimi. Consulta il principio del privilegio minimo.

Crea un CredentialAccessBoundary

Il confine di accesso alle credenziali specifica le risorse a cui può accedere la credenziale appena creata. Inoltre, specifica un limite superiore per le autorizzazioni disponibili su ogni risorsa. Include uno o più oggetti AccessBoundaryRule.

Il seguente snippet mostra come inizializzare un CredentialAccessBoundary con un AccessBoundaryRule. Questa regola specifica che il token con ambito ridotto avrà accesso di sola lettura agli oggetti che iniziano con customer-a nel bucket bucket-123.

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

Pattern di utilizzo comune

Il pattern di utilizzo comune prevede un broker di token con accesso con privilegi elevati. Questo broker genera credenziali con ambito ridotto da credenziali di origine con accesso più elevato. Quindi, passa i token di accesso di breve durata con ambito ridotto a un consumer di token tramite un canale autenticato sicuro per l'accesso limitato alle risorse di Google CloudStorage.

Genera token con ambito ridotto

Esistono due modi per generare token con ambito ridotto utilizzando un CredentialAccessBoundary:

  • Lato server (utilizzando DownscopedCredentials): il client chiama il Security Token Service (STS) ogni volta che è necessario un token con ambito ridotto. Questa opzione è adatta per le applicazioni in cui le regole del limite di accesso alle credenziali cambiano raramente o in cui riutilizzi più volte una singola credenziale con ambito ridotto. Una considerazione principale è che ogni modifica alle regole richiede una nuova chiamata all'STS. Questo approccio è disponibile nella libreria google-auth-library-oauth2-http e non richiede dipendenze aggiuntive. In questo modo l'integrazione è più semplice. È una buona scelta se il tuo caso d'uso non richiede i vantaggi specifici dell'approccio lato client.

  • Lato client (utilizzando ClientSideCredentialAccessBoundaryFactory): il client recupera il materiale crittografico una volta e poi genera localmente più token con ambito ridotto. In questo modo, le chiamate a STS vengono ridotte al minimo e l'efficienza aumenta quando le regole del confine di accesso alle credenziali cambiano di frequente, perché il client non deve contattare STS per ogni modifica delle regole. Questo è anche più efficiente per le applicazioni che devono generare molti token con ambito ridotto univoci. Questo approccio è disponibile nel modulo google-auth-library-cab-token-generator. Tuttavia, questo modulo ha un proprio insieme di dipendenze. Queste dipendenze possono aggiungere complessità al tuo progetto. Prendi in considerazione questo approccio se la riduzione al minimo delle chiamate STS e la generazione di numerosi token univoci sono le tue principali preoccupazioni. Dovrai anche gestire le dipendenze aggiuntive.

CAB lato server

La classe DownscopedCredentials può essere utilizzata per produrre un token di accesso con scope ridotto da una credenziale di origine e da CredentialAccessBoundary.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

CAB lato client

Per il CAB lato client, viene utilizzato ClientSideCredentialAccessBoundaryFactory con una credenziale di origine. Dopo aver inizializzato la factory, il metodo generateToken() può essere chiamato ripetutamente con oggetti CredentialAccessBoundary diversi per creare più token con ambito ridotto.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

Utilizza token di accesso con ambito ridotto

Puoi configurare un broker di token su un server in una rete privata. Vari workload (consumer di token) nella stessa rete inviano richieste autenticate al broker per i token con ambito ridotto. Questi token consentono di accedere o modificare bucket di archiviazione Google Cloud specifici.

Il broker crea istanze di credenziali con ambito ridotto che possono generare token di accesso con ambito ridotto di breve durata. Quindi, passa questi token al consumer di token.

Questi token di accesso con ambito ridotto possono essere utilizzati dal consumer di token utilizzando OAuth2Credentials o OAuth2CredentialsWithRefresh. Puoi quindi utilizzare questa credenziale per inizializzare un'istanza del client di archiviazione per accedere alle risorse di Google CloudStorage con accesso limitato.

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

Solo Cloud Storage supporta i limiti di accesso alle credenziali; altri serviziGoogle Cloud non supportano questa funzionalità.

Utilizza le credenziali con google-http-client

Le credenziali fornite da com.google.auth:google-auth-library-oauth2-http possono essere utilizzate con i client basati su HTTP di Google. I client basati su HTTP di Google forniscono un HttpCredentialsAdapter che può essere utilizzato come HttpRequestInitializer, l'ultimo argomento per i relativi builder.

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

Verifica i token JWT (funzionalità beta)

Per verificare un token JWT, utilizza la classe TokenVerifier.

Verifica una firma

Per verificare una firma, utilizza il valore predefinito TokenVerifier:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Personalizza la sezione TokenVerifier

Per personalizzare un TokenVerifier, creane un'istanza utilizzando il relativo builder:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Per altre opzioni, consulta la documentazione di TokenVerifier.Builder.

google-auth-library-credentials

Questo artefatto contiene classi base e interfacce per le credenziali Google:

  • Credentials: questa è la classe base per un'identità autorizzata. Le implementazioni di questa classe possono autorizzare la tua applicazione.
  • RequestMetadataCallback: questa è l'interfaccia per il callback che riceve il risultato della chiamata asincrona Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback).
  • ServiceAccountSigner: questa è l'interfaccia per un firmatario del account di servizio. Le implementazioni di questa classe sono in grado di firmare array di byte utilizzando le credenziali associate a un service account Google.

google-auth-library-appengine

Questo artefatto dipende dall'SDK App Engine (appengine-api-1.0-sdk). Utilizzalo solo per le applicazioni in esecuzione in ambienti App Engine che utilizzano urlfetch. La classe AppEngineCredentials ti consente di autorizzare la tua applicazione App Engine data un'istanza di AppIdentityService.

Utilizzo:

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

google-auth-library-cab-token-generator

Questo modulo fornisce la classe ClientSideCredentialAccessBoundaryFactory, che consente la generazione lato client di token con ambito ridotto per Cloud Storage utilizzando i limiti di accesso delle credenziali. Questo approccio è particolarmente utile per le applicazioni che richiedono modifiche frequenti alle regole di Credential Access Boundary o la generazione di molti token con ambito ridotto univoci, perché riduce al minimo le chiamate a Security Token Service (STS). Per esempi di utilizzo, consulta la sezione CAB lato client. Questo modulo ha un proprio insieme di dipendenze. Valuta se i vantaggi del downscoping lato client superano la complessità aggiuntiva per il tuo caso d'uso specifico.