Iniziare a utilizzare la libreria di autenticazione Google

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 Auth al tuo progetto utilizzando Maven, Gradle o Simple Build Tool (SBT).
  • Esegui 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à del 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 è destinata agli sviluppatori Java. Per tutti i dettagli dell'API, consulta la documentazione dell'API Google Auth Library.

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

  • google-auth-library-credentials contiene classi di 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 anche l'approccio lato server per la generazione di token con ambito ridotto.
  • google-auth-library-cab-token-generator fornisce l'approccio lato client per generare token con ambito ridotto.

Convalida le configurazioni delle credenziali

Quando utilizzi configurazioni delle credenziali, come JSON, percorsi di file o stream, da una fonte esterna, devi convalidarle. Fornire credenziali non convalidate alle API di Google o alle librerie client per l'autenticazione a Google 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 di autenticazione

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

Java SDK libraries-bom

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

Ad esempio, per importare la libreria di autenticazione 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 di autenticazione direttamente con la Bill of Materials della libreria di autenticazione Google.

Distinta base della libreria Google Auth

Puoi utilizzare la distinta materiali della libreria di autenticazione Google per assicurarti che i moduli di autenticazione e le dipendenze transitive pertinenti 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 i moduli di autenticazione 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 con Gradle, aggiungila come dipendenza platform. Poi, aggiungi i moduli google-auth-library che ti servono. La distinta materiali garantisce che le versioni di tutti i moduli che utilizzi siano compatibili. Ad esempio, aggiungi quanto segue al tuo 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 BOM (Bills of Materials) di Maven. Di conseguenza, quando utilizzi Scala, non puoi importare google-auth-library-bom per gestire automaticamente le versioni compatibili dei moduli della libreria Auth e le 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 tra le versioni, possono verificarsi conflitti tra le dipendenze transitive, causando potenzialmente comportamenti imprevisti o errori di runtime nell'applicazione.

Aggiungi questo elemento alle 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"

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). Ecco 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. ADC fornisce 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, indipendente dall'utente. Ti consigliamo di utilizzare ADC per autorizzare le chiamate alle API Cloud, soprattutto quando crei applicazioni su Google Cloud.

ADC supporta anche Workload Identity Federation, 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). 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.

Recupera 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.

Di seguito sono elencati gli elementi in cui viene eseguita la ricerca, in questo ordine, per trovare le credenziali predefinite dell'applicazione:

  1. File delle credenziali a cui fa riferimento 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. Credenziali integrate diGoogle Cloud Shell.
  5. Credenziali integrate di Google Compute Engine.
    • Ignora 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 esempio di codice.

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 impersonate

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

Per utilizzare ImpersonatedCredentials, devi soddisfare i seguenti requisiti:

  • Nel progetto dell'entità deve essere abilitata l'API IAMCredentials.
  • L'entità deve disporre del ruolo Service Account Token Creator (Identity and Access Management) nell'account di servizio di destinazione.

Il seguente esempio di codice crea ImpersonatedCredentials. Le credenziali del principal vengono ottenute dalle credenziali predefinite dell'applicazione (ADC). I ImpersonatedCredentials risultanti vengono poi 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.iam.gserviceaccount.com")
        .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);
}

Federazione delle identità per i workload

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

In genere, le applicazioni in esecuzione all'esterno Google Cloud hanno utilizzato le chiavi del 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 carico di lavoro 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 questo processo, genererai un file di configurazione delle credenziali. Questo file contiene metadati non sensibili che indicano alla libreria come recuperare i token soggetto 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 fornitore AWS.
  • SERVICE_ACCOUNT_EMAIL: l'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 di AWS.

Accesso alle risorse da Microsoft Azure

Per accedere alle risorse di Microsoft Azure, devi prima configurare la federazione delle identità per i carichi di lavoro. Google Cloud La procedura di configurazione è descritta in dettaglio in Accesso alle risorse da Azure.

Nell'ambito di questo processo, genererai un file di configurazione delle credenziali. Questo file contiene metadati non sensibili che indicano alla libreria come recuperare i token soggetto 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'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 Google Cloud le risorse da 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à per i carichi di lavoro come descritto in Configurazione della federazione delle identità per i carichi di lavoro 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 soggetto esterni e scambiarli con i token di accesso al 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 basate su file

Per le credenziali basate su 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 memorizzare 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'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 URL, un server locale deve ospitare un endpoint GET che fornisce un token OIDC in formato JSON o testo normale. Se richiesto dall'endpoint, puoi specificare intestazioni HTTP aggiuntive da inviare nella richiesta di token.

Per generare una configurazione dell'identità del workload OIDC basata su 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'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 aggiuntiva da trasmettere 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.

Accedere 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 file di configurazione per la federazione X.509

Per configurare le credenziali provenienti da certificati X.509, genera 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 trust.

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 si chiama config.json e il file di configurazione del certificato predefinito si chiama certificate_config.json.

Ad esempio, esegui il seguente 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 fornitore.
  • SERVICE_ACCOUNT_EMAIL: l'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 un file in formato PEM contenente 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à dei workload. Il certificato foglia è facoltativo in questo file.

Questo comando genera il seguente risultato:

  • /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 o %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 (posizione 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 punta al percorso personalizzato.
  • cert_config.json: creato alle ore /custom/path/cert_config.json, come specificato dal flag.

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

Utilizzare le credenziali provenienti da eseguibili con OIDC e SAML

Per le credenziali basate su eseguibili, 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 eseguibili, la variabile di ambiente GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES deve essere impostata su 1.

Per generare una configurazione dell'identità del workload basata su eseguibile, esegui questo 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'email del account di servizio di cui simulare l'identità.
  • SUBJECT_TOKEN_TYPE: il tipo di token soggetto.
  • EXECUTABLE_COMMAND: il comando completo da eseguire, inclusi gli argomenti. Deve essere un percorso assoluto del programma.

Il flag --executable-timeout-millis è facoltativo; 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 memorizzate nella cache valide, le librerie le utilizzano, evitando esecuzioni non necessarie.

L'eseguibile deve scrivere la risposta delle credenziali in questo file. Le librerie auth leggono solo da questa posizione. Il contenuto del file deve 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 della risposta specificato negli esempi seguenti e deve restituire la risposta a stdout.

Ecco un esempio di risposta OIDC eseguibile corretta:

{
  "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 corretta:

{
  "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 eseguibili riuscite devono includere un campo expiration_time. Ciò consente alla libreria di autenticazione di memorizzare nella cache e gestire in modo efficace la validità delle credenziali archiviate in questo file.

Di seguito è riportato 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 codice e messaggio 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 true, 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 anche uscire con un codice di uscita pari a 0. Se il valore è false, la risposta deve includere i campi codice di errore e messaggio e uscire con un valore diverso da zero. * token_type: questo campo specifica il tipo di token 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 scadenza del token soggetto di terze parti in secondi (tempo Unix epoch). * 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 i campi code che 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à del 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 codificare questi valori.

Considerazioni sulla sicurezza

Si consiglia di adottare le seguenti pratiche di sicurezza:

  • Impedisci ai processi non autorizzati di eseguire l'eseguibile perché restituirà credenziali sensibili a questi processi e ai relativi utenti tramite stdout.
  • Impedisci a processi non autorizzati di modificare la configurazione o l'invocazione dell'eseguibile.

A causa della complessità dell'utilizzo delle credenziali basate su eseguibili, ti consigliamo vivamente di utilizzare altri meccanismi supportati, come le origini file o URL, per fornire le 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.

Utilizzare un fornitore personalizzato con OIDC e SAML

Durante la creazione di IdentityPoolCredentials, è possibile utilizzare un'implementazione personalizzata di IdentityPoolSubjectTokenSupplier 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 dalle credenziali 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 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 segmento di 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 fornitore.

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

Utilizzare un fornitore personalizzato con AWS

È possibile fornire un'implementazione personalizzata di AwsSecurityCredentialsSupplier durante l'inizializzazione di AwsCredentials. Se fornita, l'istanza AwsCredentials rimanderà 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 da Google Cloud credential.

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 impedire 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 fornitore.

Puoi anche trovare i valori per il pubblico, l'URL di simulazione dell'identità del 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 carichi di lavoro utilizzando la simulazione dell'identità delaccount di serviziot, puoi fornire un argomento facoltativo per configurare la durata del token di accesso deaccount di serviziont.

Per generare la configurazione con la 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à per i 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 fornitore AWS.
  • SERVICE_ACCOUNT_EMAIL: l'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 è impostato su un'ora per impostazione predefinita. Il valore minimo consentito è 600 (10 minuti) e il valore massimo consentito è 43.200 (12 ore). Se richiedi una durata superiore a un'ora, devi aggiungere l'account di servizio come valore consentito in un servizio criteri 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 di token ogni 10 minuti. Viene chiamato il fornitore di token di terze parti anche se il token di terze parti non è scaduto.

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

Le credenziali utente autorizzato dell'account esterno ti consentono di accedere con un browser web a un account del provider di identità esterno utilizzando gcloud CLI e creare una configurazione da utilizzare per la libreria di autenticazione.

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

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

Dove deve essere sostituita la seguente variabile:

Si apre un flusso del browser per accedere utilizzando il provider di identità di terze parti configurato. Quindi, memorizza la configurazione dell'utente autorizzato dell'account esterno nella posizione nota di ADC.

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 modificando la durata della sessione del pool di forza lavoro, e puoi impostarla fino a 12 ore.

Utilizzare identità esterne

Puoi utilizzare identità esterne con Application Default Credentials. Per utilizzare 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 Workload Identity Federation. Una volta generato, memorizza il percorso di questo file nella variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

La libreria ora può 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 esplicitamente i client di 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 dei 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 tu non verifichi che i campi URL puntino a un dominio googleapis.com.

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

Il downscoping con i limiti di accesso alle credenziali consente di limitare le autorizzazioni 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 applicate al token con ambito ridotto. L'utilizzo di credenziali con ambito ridotto garantisce che i token in transito abbiano sempre i privilegi minimi. Consulta Principio del privilegio minimo.

Crea un CredentialAccessBoundary

Il confine di accesso delle credenziali specifica a quali risorse può accedere la credenziale appena creata. Specifica inoltre un limite superiore per le autorizzazioni disponibili per 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 in 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 a partire da credenziali di origine con accesso superiore. 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 archiviazione. Google Cloud

Generare token con ambito ridotto

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

  • Lato server (utilizzando DownscopedCredentials): il client chiama il servizio token di sicurezza (STS) ogni volta che è necessario un token con ambito ridotto. Questa opzione è adatta alle applicazioni in cui le regole relative ai limiti all'accesso con credenziali cambiano di rado o in cui riutilizzi più volte una singola credenziale con privilegi ridotti. Un aspetto fondamentale è che ogni modifica alla regola 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 sola volta e poi genera localmente più token con ambito ridotto. In questo modo si riducono al minimo le chiamate a STS ed è più efficiente quando le regole di Credential Access Boundary cambiano di frequente, perché il client non deve contattare STS per ogni modifica della regola. Inoltre, è 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 include 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 unici sono le tue priorità. Dovrai anche gestire le dipendenze aggiuntive.

CAB lato server

La classe DownscopedCredentials può essere utilizzata per produrre un token di accesso con ambito 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 CAB lato client, viene utilizzato ClientSideCredentialAccessBoundaryFactory con una credenziale di origine. Dopo aver inizializzato la fabbrica, il metodo generateToken() può essere chiamato ripetutamente con diversi oggetti CredentialAccessBoundary 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);

Utilizzare token di accesso con ambito ridotto

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

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 queste credenziali per inizializzare un'istanza del client di archiviazione per accedere alle risorse di archiviazione con accesso limitato. Google Cloud

// 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 delle credenziali; altri Google Cloud servizi non supportano questa funzionalità.

Utilizzare 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 dei token JWT (funzionalità beta)

Per verificare un token JWT, utilizza la classe TokenVerifier.

Verificare una firma

Per verificare una firma, utilizza TokenVerifier predefinito:

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.
}

Personalizzare TokenVerifier

Per personalizzare un TokenVerifier, istanzialo 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 relativa a TokenVerifier.Builder.

google-auth-library-credentials

Questo artefatto contiene classi e interfacce di base 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 di Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) asincrono.
  • 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 account di servizio 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 dato 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, consentendo 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 del perimetro di accesso alle credenziali o la generazione di molti token con ambito ridotto unici, perché riduce al minimo le chiamate al servizio token di sicurezza (STS). Per esempi di utilizzo, consulta la sezione Client-side CAB. Questo modulo ha un proprio insieme di dipendenze. Valuta se i vantaggi della riduzione dell'ambito lato client superano la maggiore complessità per il tuo caso d'uso specifico.