Premiers pas avec la bibliothèque Google Auth

La bibliothèque Google Auth est une bibliothèque cliente d'authentification Open Source pour Java. Ce document explique comment utiliser cette bibliothèque pour authentifier vos applications Java et accéder aux services Google Cloud .

En suivant ce guide, vous apprendrez à :

  • Ajoutez les dépendances nécessaires de la bibliothèque Auth à votre projet à l'aide de Maven, Gradle ou Simple Build Tool (SBT).
  • Authentifiez-vous à l'aide de différentes méthodes, en particulier les identifiants par défaut de l'application (ADC).
  • Configurez des scénarios d'authentification avancés, y compris la fédération d'Workload Identity, la fédération d'identité des employés et l'emprunt d'identité de compte de service.
  • Générez et utilisez des jetons à accès limité pour limiter les autorisations.
  • Intégrez les identifiants aux bibliothèques clientes HTTP Google.

Cette documentation est destinée aux développeurs Java. Pour obtenir tous les détails sur l'API, consultez la documentation de l'API Google Auth Library.

La bibliothèque Google Auth pour Java se compose de quatre artefacts :

  • google-auth-library-credentials contient des classes de base et des interfaces pour les identifiants Google.
  • google-auth-library-appengine contient les identifiants App Engine et dépend du SDK App Engine.
  • google-auth-library-oauth2-http contient divers identifiants et méthodes utilitaires, y compris des fonctionnalités permettant d'obtenir les identifiants par défaut de l'application. Il fournit également l'approche côté serveur pour générer des jetons à portée limitée.
  • google-auth-library-cab-token-generator fournit l'approche côté client pour générer des jetons à champ d'application limité.

Valider les configurations d'identifiants

Lorsque vous utilisez des configurations d'identifiants, telles que des fichiers JSON, des chemins d'accès ou des flux, à partir d'une source externe, vous devez les valider. Fournir des identifiants non validés aux API ou aux bibliothèques clientes Google pour l'authentification àGoogle Cloud peut compromettre la sécurité de vos systèmes et de vos données.

Pour en savoir plus, consultez Identifiants provenant d'une source externe. Identifiants par défaut.

Importer la bibliothèque Auth

Pour importer la bibliothèque Auth, utilisez com.google.cloud:libraries-bom ou la nomenclature de la bibliothèque Google Auth avec Maven ou Gradle.

Bibliothèques Java SDK libraries-bom

Pour vous authentifier auprès d'une bibliothèque cliente du SDK Java (par exemple, google-cloud-datastore) à l'aide de la bibliothèque Auth, utilisez libraries-bom, qui extraira les versions de la bibliothèque Auth compatibles avec cette bibliothèque cliente.

Par exemple, pour importer la bibliothèque Auth avec Maven à l'aide d'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>

Si vous n'utilisez pas libraries-bom ni d'autres bibliothèques clientes, importez les modules Auth directement avec la nomenclature de la bibliothèque Google Auth.

Nomenclature de la bibliothèque Google Auth

Vous pouvez utiliser la nomenclature de la bibliothèque Google Auth pour vous assurer que les modules Auth et les dépendances transitives pertinentes sont compatibles.

Maven

Ajoutez le code ci-dessous à votre fichier 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>

Dans la section <dependencies>, vous pouvez spécifier les modules d'authentification nécessaires. Par exemple, pour inclure le module google-auth-library-oauth2-http, ajoutez l'élément <dependency> suivant :

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

Dans l'exemple, remplacez google-auth-library-oauth2-http par google-auth-library-credentials ou google-auth-library-appengine, selon les besoins de votre application.

Gradle

Comme pour Maven, les utilisateurs de Gradle peuvent utiliser google-auth-library-bom pour gérer les versions des dépendances et assurer la compatibilité entre les différents modules google-auth-library.

Pour utiliser la BOM avec Gradle, ajoutez-la en tant que dépendance platform. Ajoutez ensuite les modules google-auth-library dont vous avez besoin. La nomenclature garantit la compatibilité des versions de tous les modules que vous utilisez. Par exemple, ajoutez le code suivant à votre fichier 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

Contrairement à Maven et Gradle, SBT (Scala Build Tool) n'est pas compatible avec les BOM (Bills of Materials) Maven. Par conséquent, lorsque vous utilisez Scala, vous ne pouvez pas importer google-auth-library-bom pour gérer automatiquement les versions compatibles des modules de la bibliothèque Auth et leurs dépendances transitives.

Vous devez ajouter chaque sous-module requis directement à votre fichier build.sbt. Il est essentiel de spécifier explicitement et d'aligner les versions de tous les modules google-auth-library que vous utilisez. Si vous ne maintenez pas la cohérence des versions, cela peut entraîner des conflits de versions entre les dépendances transitives, ce qui peut potentiellement provoquer un comportement inattendu ou des erreurs d'exécution dans votre application.

Si vous utilisez SBT, ajoutez ceci à vos dépendances :

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

Migrer de GoogleCredential vers GoogleCredentials

GoogleCredential de google-api-java-client est obsolète. Il est recommandé de le remplacer par GoogleCredentials.

Instanciez GoogleCredentials à l'aide des identifiants par défaut de l'application (ADC). Voici l'approche recommandée :

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

La façon dont vous utilisez GoogleCredentials dépend de la bibliothèque cliente :

Identifiants par défaut de l'application

La bibliothèque Google Auth fournit une implémentation des identifiants par défaut de l'application (ADC) pour Java. Les ADC permettent d'obtenir des identifiants d'autorisation pour appeler les API Google.

Utilisez ADC lorsque votre application nécessite une identité et un niveau d'autorisation cohérents, indépendamment de l'utilisateur. Nous vous recommandons d'utiliser ADC pour autoriser les appels aux APIs Cloud, en particulier lorsque vous créez des applications sur Google Cloud.

ADC est également compatible avec la fédération d'identité de charge de travail, qui permet aux applications d'accéder aux ressources Google Cloud à partir de plates-formes externes telles qu'Amazon Web Services (AWS), Microsoft Azure ou tout fournisseur d'identité compatible avec OpenID Connect (OIDC). Nous recommandons la fédération d'identité de charge de travail pour les environnements autres queGoogle Cloud , car elle élimine la nécessité de télécharger, de gérer et de stocker localement les clés privées des comptes de service.

Obtenir les identifiants par défaut de l'application

Pour obtenir les Identifiants par défaut de l'application, utilisez GoogleCredentials.getApplicationDefault() ou GoogleCredentials.getApplicationDefault(HttpTransportFactory). Ces méthodes renvoient les Identifiants par défaut de l'application pour identifier et autoriser l'ensemble de l'application.

Les éléments suivants sont recherchés, dans cet ordre, pour trouver les identifiants par défaut de l'application :

  1. Fichier d'identifiants pointé par la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.
  2. Identifiants fournis par la commande gcloud auth application-default login du SDK Google Cloud.
  3. Informations d'identification intégrées à Google App Engine.
  4. Google Cloud Identifiants intégrés à Shell.
  5. Identifiants intégrés Google Compute Engine.
    • Ignorez cette vérification en définissant la variable d'environnement NO_GCE_CHECK=true.
    • Personnalisez l'adresse du serveur de métadonnées en définissant la variable d'environnement GCE_METADATA_HOST=<hostname>.

Chargement explicite des identifiants

Pour obtenir des identifiants à partir d'une clé JSON de compte de service, utilisez GoogleCredentials.fromStream(InputStream) ou GoogleCredentials.fromStream(InputStream, HttpTransportFactory), comme indiqué dans l'exemple de code suivant.

Les identifiants doivent être actualisés avant que le jeton d'accès ne soit disponible.

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

Identifiants usurpés

Utilisez ImpersonatedCredentials pour autoriser un identifiant (le compte principal) à emprunter l'identité d'un compte de service (la cible). Cela permet au principal d'accéder aux ressources en tant que cible, sans avoir besoin de la clé privée de la cible.

Pour utiliser ImpersonatedCredentials, vous devez remplir les conditions suivantes :

  • L'API IAMCredentials doit être activée pour le projet du principal.
  • Le compte principal doit disposer du rôle Service Account Token Creator (Identity and Access Management) sur le compte de service cible.

L'exemple de code suivant crée ImpersonatedCredentials. Les identifiants du principal sont obtenus à partir des identifiants par défaut de l'application (ADC). Les ImpersonatedCredentials obtenus sont ensuite utilisés pour accéder à Google Cloud Storage en tant que compte de service cible.

// 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);
}

Fédération d'identité de charge de travail

La fédération d'identité de charge de travail permet à votre application d'accéder aux ressources Google Cloudd'Amazon Web Services (AWS), de Microsoft Azure ou de tout fournisseur d'identité compatible avec OpenID Connect (OIDC).

Traditionnellement, les applications exécutées en dehors de Google Cloud utilisent des clés de compte de service pour accéder aux ressources Google Cloud . Grâce à la fédération d'identité, votre charge de travail peut emprunter l'identité d'un compte de service. Cela permet à la charge de travail externe d'accéder directement aux ressources Google Cloud , ce qui élimine les tâches de maintenance et de sécurité associées aux clés de compte de service.

Accéder aux ressources d'AWS

Pour accéder aux ressources Google Cloud depuis Amazon Web Services (AWS), vous devez d'abord configurer la fédération d'identité de charge de travail. La procédure de configuration est détaillée dans Accéder aux ressources depuis AWS.

Dans le cadre de ce processus, vous générerez un fichier de configuration des identifiants. Ce fichier contient des métadonnées non sensibles qui indiquent à la bibliothèque comment récupérer les jetons de sujet externes et les échanger contre des jetons d'accès au compte de service. Vous pouvez générer le fichier à l'aide de la 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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • POOL_ID : ID du pool d'identités de charge de travail.
  • AWS_PROVIDER_ID : ID du fournisseur AWS.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service dont l'identité doit être empruntée.

L'exemple génère le fichier de configuration dans le fichier de sortie spécifié.

Si vous utilisez AWS IMDSv2, vous devez ajouter une option supplémentaire --enable-imdsv2 à la commande 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

Vous pouvez désormais utiliser la bibliothèque Auth pour appeler les ressourcesGoogle Cloud depuis AWS.

Accéder aux ressources de Microsoft Azure

Pour accéder aux ressources Google Cloud depuis Microsoft Azure, vous devez d'abord configurer la fédération d'identité de charge de travail. La procédure de configuration est décrite dans Accéder aux ressources depuis Azure.

Dans le cadre de ce processus, vous générerez un fichier de configuration des identifiants. Ce fichier contient des métadonnées non sensibles qui indiquent à la bibliothèque comment récupérer les jetons de sujet externes et les échanger contre des jetons d'accès au compte de service. Vous pouvez générer le fichier à l'aide de la 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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • POOL_ID : ID du pool d'identités de charge de travail.
  • AZURE_PROVIDER_ID : ID du fournisseur Azure.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service dont l'identité doit être empruntée.

Cette commande génère le fichier de configuration dans le fichier de sortie spécifié.

Vous pouvez désormais utiliser la bibliothèque Auth pour appeler des ressources Google Clouddepuis Azure.

Accéder aux ressources depuis un fournisseur d'identité OIDC

Pour accéder aux ressources Google Cloud à partir d'un fournisseur d'identité compatible avec OpenID Connect (OIDC), vous devez d'abord configurer la fédération d'identité de charge de travail, comme décrit dans Configurer la fédération d'identité de charge de travail à partir d'un fournisseur d'identité OIDC.

Dans le cadre de ce processus, vous générerez un fichier de configuration des identifiants à l'aide de la Google Cloud CLI. Ce fichier contient des métadonnées non sensibles qui indiquent à la bibliothèque comment récupérer les jetons de sujet externes et les échanger contre des jetons d'accès au compte de service.

Pour les fournisseurs OIDC, la bibliothèque Auth peut récupérer les jetons OIDC à partir d'un fichier local (identifiants provenant de fichiers), d'un serveur local (identifiants provenant d'URL) ou d'une combinaison de certificat X.509 et de clé privée (identifiants provenant de certificats X.509).

Identifiants d'origine du fichier

Pour les identifiants provenant de fichiers, un processus en arrière-plan doit actualiser en permanence l'emplacement du fichier avec un nouveau jeton OIDC avant son expiration. Pour les jetons d'une heure, vous devez mettre à jour le jeton dans le fichier toutes les heures. Vous pouvez stocker le jeton directement en texte brut ou au format JSON.

Pour générer une configuration OIDC basée sur un fichier, exécutez la commande suivante :

# 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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • POOL_ID : ID du pool d'identités de charge de travail.
  • OIDC_PROVIDER_ID : ID du fournisseur OIDC.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service dont l'identité doit être empruntée.
  • PATH_TO_OIDC_ID_TOKEN : chemin d'accès utilisé pour récupérer le jeton OIDC.

Cette commande génère le fichier de configuration dans le fichier de sortie spécifié.

Identifiants provenant d'URL

Pour les identifiants provenant d'une URL, un serveur local doit héberger un point de terminaison GET qui fournit un jeton OIDC au format texte brut ou JSON. Vous pouvez spécifier des en-têtes HTTP supplémentaires à envoyer dans la demande de jeton, si le point de terminaison l'exige.

Pour générer une configuration d'identité de charge de travail OIDC basée sur une URL, exécutez la commande suivante :

# 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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • POOL_ID : ID du pool d'identités de charge de travail.
  • OIDC_PROVIDER_ID : ID du fournisseur OIDC.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service dont l'identité doit être empruntée.
  • URL_TO_GET_OIDC_TOKEN : URL du point de terminaison du serveur local à appeler pour récupérer le jeton OIDC.
  • HEADER_KEY et HEADER_VALUE : paires clé/valeur d'en-tête supplémentaires à transmettre avec la requête GET à URL_TO_GET_OIDC_TOKEN, par exemple Metadata-Flavor=Google.

Vous pouvez désormais utiliser la bibliothèque Auth pour appeler des ressourcesGoogle Cloud à partir d'un fournisseur OIDC.

Accéder aux ressources à l'aide d'identifiants provenant de certificats X.509

Pour les identifiants provenant d'un certificat X.509, la bibliothèque d'authentification utilise un certificat X.509 et une clé privée pour prouver l'identité de votre application. Les certificats X.509 incluent une date d'expiration et doivent être renouvelés avant leur expiration pour maintenir l'accès.

Pour en savoir plus, consultez la documentation officielle.

Générer des fichiers de configuration pour la fédération X.509

Pour configurer des identifiants basés sur un certificat X.509, vous devez générer deux fichiers distincts : un fichier de configuration des identifiants principaux et un fichier de configuration du certificat.

  • Le fichier de configuration des identifiants principal contient les métadonnées nécessaires à l'authentification. Ce fichier fait également référence au fichier de configuration du certificat.
  • Le fichier de configuration du certificat spécifie les chemins d'accès au certificat X.509, à la clé privée et à la chaîne de confiance.

La commande gcloud iam workload-identity-pools create-cred-config peut être utilisée pour créer les deux.

L'emplacement où gcloud crée le fichier de configuration du certificat dépend de l'utilisation ou non de l'indicateur --credential-cert-configuration-output-file.

Si vous omettez l'indicateur --credential-cert-configuration-output-file, gcloud crée le fichier de configuration du certificat à un emplacement par défaut bien connu que la bibliothèque Auth peut découvrir automatiquement. Cette approche convient à la plupart des cas d'utilisation. Le fichier de configuration des identifiants par défaut est nommé config.json et le fichier de configuration des certificats par défaut est nommé certificate_config.json.

Par exemple, exécutez la commande suivante pour créer les fichiers de configuration en utilisant le comportement par défaut :

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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • POOL_ID : ID du pool d'identités de charge de travail.
  • PROVIDER_ID : ID du fournisseur.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service dont l'identité doit être empruntée.
  • PATH_TO_CERTIFICATE : chemin d'accès à votre certificat X.509 de feuille.
  • PATH_TO_PRIVATE_KEY : chemin d'accès à la clé privée correspondant au certificat de feuille.
  • PATH_TO_TRUST_CHAIN : chemin d'accès au fichier de la chaîne de confiance du certificat X.509. Ce fichier doit être au format PEM et contenir tous les certificats intermédiaires requis pour compléter la chaîne de confiance entre le certificat feuille et le truststore configuré dans le pool de fédération d'identité de charge de travail. Le certificat de feuille est facultatif dans ce fichier.

Cette commande génère les éléments suivants :

  • /path/to/config.json : créé au chemin d'accès que vous avez spécifié. Ce fichier contiendra "use_default_certificate_config": true pour indiquer aux clients de rechercher la configuration du certificat au chemin d'accès par défaut.
  • certificate_config.json : créé au niveau du chemin de configuration par défaut du Google Cloud CLI, qui est généralement ~/.config/gcloud/certificate_config.json sous Linux et macOS, ou %APPDATA%\gcloud\certificate_config.json sous Windows.

Comportement des zones géographiques personnalisées

Si vous devez stocker le fichier de configuration du certificat dans un emplacement autre que celui par défaut, utilisez l'option --credential-cert-configuration-output-file.

Exemple de commande (emplacement personnalisé) :

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

Cette commande génère le résultat suivant :

  • /path/to/config.json créé au chemin d'accès que vous avez spécifié. Ce fichier contiendra un champ "certificate_config_location" qui pointe vers votre chemin d'accès personnalisé.
  • cert_config.json : créé à /custom/path/cert_config.json, comme spécifié par le flag.

Vous pouvez désormais utiliser la bibliothèque Auth pour appeler les ressourcesGoogle Cloud avec des identifiants provenant de certificats X.509.

Utiliser des identifiants exécutables avec OIDC et SAML

Pour les identifiants exécutables, un exécutable local est utilisé pour récupérer le jeton tiers. L'exécutable doit fournir un jeton d'ID OIDC ou une assertion SAML valides et non expirés au format JSON à stdout.

Pour utiliser des identifiants d'origine exécutable, la variable d'environnement GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES doit être définie sur 1.

Pour générer une configuration d'identité de charge de travail basée sur un exécutable, exécutez la commande suivante :

# 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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • POOL_ID : ID du pool d'identités de charge de travail.
  • PROVIDER_ID : ID du fournisseur OIDC ou SAML.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service dont l'identité doit être empruntée.
  • SUBJECT_TOKEN_TYPE : type de jeton d'objet.
  • EXECUTABLE_COMMAND : commande complète à exécuter, y compris les arguments. Il doit s'agir d'un chemin d'accès absolu au programme.

L'option --executable-timeout-millis est facultative. Elle spécifie la durée (en millisecondes) pendant laquelle la bibliothèque Auth attendra la fin de l'exécutable. Si aucune valeur n'est spécifiée, la valeur par défaut est de 30 secondes. La valeur maximale autorisée est de deux minutes et la valeur minimale de cinq secondes.

L'option facultative --executable-output-file spécifie un chemin d'accès pour mettre en cache la réponse des identifiants tiers de l'exécutable. La mise en cache permet d'améliorer les performances, car les bibliothèques d'authentification vérifient d'abord ce fichier pour voir s'il contient des identifiants valides et non expirés avant d'exécuter le fichier exécutable. Si des identifiants mis en cache valides existent, les bibliothèques les utilisent, ce qui évite d'exécuter des exécutables inutiles.

Votre exécutable doit écrire la réponse d'identifiant dans ce fichier. Les bibliothèques d'authentification ne lisent que cet emplacement. Le contenu du fichier doit correspondre au format JSON attendu.

Pour récupérer le jeton tiers, la bibliothèque exécutera l'exécutable à l'aide de la commande spécifiée. La sortie de l'exécutable doit respecter le format de réponse spécifié dans les exemples suivants et doit générer la réponse dans stdout.

Voici un exemple de réponse OIDC exécutable réussie :

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

Voici un exemple de réponse SAML exécutable réussie :

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

Lorsque vous spécifiez un fichier de sortie à l'aide de l'argument --executable-output-file dans la configuration des identifiants, les réponses exécutables réussies doivent inclure un champ expiration_time. Cela permet à la bibliothèque d'authentification de mettre en cache et de gérer efficacement la validité des identifiants stockés dans ce fichier.

Voici un exemple de réponse d'erreur exécutable :

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

Ces champs sont tous obligatoires pour une réponse d'erreur. La bibliothèque utilise les champs de code et de message dans une exception générée.

Récapitulatif des champs du format de réponse : * version : version de la sortie JSON. Seule la version 1 est compatible. * success : lorsque la valeur est "true", la réponse doit inclure le jeton tiers et le type de jeton. La réponse doit également inclure le champ expiration_time si un fichier de sortie a été spécifié dans la configuration des identifiants. L'exécutable doit également se fermer avec le code de sortie 0. Lorsque la valeur est "false", la réponse doit inclure le code d'erreur et les champs du message, et se fermer avec une valeur différente de "0". * token_type : ce champ spécifie le type de jeton d'objet tiers. La valeur doit être urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token ou urn:ietf:params:oauth:token-type:saml2. * id_token : jeton OIDC tiers. * saml_response : réponse SAML tierce. * expiration_time : délai d'expiration du jeton d'objet tiers en secondes (epoch Unix). * code : chaîne du code d'erreur. * message : message d'erreur.

Tous les types de réponses doivent inclure les champs version et success. * Les réponses réussies doivent inclure token_type et l'un des éléments suivants : id_token ou saml_response. Le champ expiration_time doit également être présent si un fichier de sortie a été spécifié dans la configuration des identifiants. * Les réponses d'erreur doivent inclure les champs code et message.

La bibliothèque renseigne les variables d'environnement suivantes lorsqu'elle exécute l'exécutable :

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE : champ d'audience de la configuration des identifiants. Toujours présent.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE : type de jeton d'objet attendu. Toujours présent.
  • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL : adresse e-mail du compte de service. Présent uniquement en cas d'usurpation d'identité d'un compte de service.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE : emplacement du fichier de sortie issu de la configuration des identifiants. N'est présent que s'il est spécifié dans la configuration des identifiants.

Ces variables d'environnement peuvent être utilisées par l'exécutable pour éviter de coder ces valeurs en dur.

Points à noter concernant la sécurité

Nous vous recommandons de respecter les bonnes pratiques de sécurité suivantes :

  • Empêchez les processus malveillants d'exécuter l'exécutable, car il transmettra des identifiants sensibles à ces processus et à leurs utilisateurs via stdout.
  • Empêchez les processus malveillants de modifier la configuration ou l'appel de l'exécutable.

En raison de la complexité de l'utilisation d'identifiants provenant d'exécutables, nous vous recommandons vivement d'utiliser d'autres mécanismes compatibles, tels que des sources de fichiers ou d'URL, pour fournir des identifiants tiers, sauf s'ils ne répondent pas à vos exigences spécifiques.

Vous pouvez désormais utiliser la bibliothèque Auth pour appeler des ressourcesGoogle Cloud depuis un fournisseur OIDC ou SAML.

Utiliser un fournisseur personnalisé avec OIDC et SAML

Une implémentation personnalisée de IdentityPoolSubjectTokenSupplier peut être utilisée lors de la création de IdentityPoolCredentials pour fournir un jeton d'objet pouvant être échangé contre un jeton d'accès Google Cloud . Le fournisseur doit renvoyer un jeton d'objet valide et non expiré lorsqu'il est appelé par les identifiants Google Cloud.

IdentityPoolCredentials ne met pas en cache le jeton renvoyé. Vous devez donc implémenter une logique de mise en cache dans le fournisseur de jetons pour éviter d'envoyer plusieurs requêtes pour le même jeton de sujet.

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();

Où se trouve l'audience :

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

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • WORKLOAD_POOL_ID : ID du pool d'identités de charge de travail.
  • PROVIDER_ID : ID du fournisseur.

Vous pouvez également trouver les valeurs de l'audience, de l'URL d'emprunt d'identité du compte de service et de tout autre champ du générateur en générant un fichier de configuration des identifiants avec gcloud CLI.

Utiliser un fournisseur personnalisé avec AWS

Une implémentation personnalisée de AwsSecurityCredentialsSupplier peut être fournie lors de l'initialisation de AwsCredentials. Si elle est fournie, l'instance AwsCredentials s'en remettra au fournisseur pour récupérer les identifiants de sécurité AWS à échanger contre un jeton d'accèsGoogle Cloud . Le fournisseur doit renvoyer des identifiants de sécurité AWS valides et non expirés lorsqu'il est appelé par l'identifiant Google Cloud .

AwsCredentials ne mettez pas en cache les identifiants de sécurité ou la région AWS renvoyés. Implémentez plutôt une logique de mise en cache dans le fournisseur pour éviter d'envoyer plusieurs requêtes pour les mêmes ressources.

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();

Où l'audience est : //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • WORKLOAD_POOL_ID : ID du pool d'identités de charge de travail.
  • PROVIDER_ID : ID du fournisseur.

Vous pouvez également trouver les valeurs de l'audience, de l'URL d'emprunt d'identité du compte de service et de tout autre champ du générateur en générant un fichier de configuration des identifiants avec gcloud CLI.

Durée de vie des jetons configurable

Lorsque vous créez une configuration d'identifiants avec la fédération d'identité de charge de travail à l'aide de l'emprunt d'identité d'un compte de service, vous pouvez fournir un argument facultatif pour configurer la durée de vie du jeton d'accès au compte de service.

Pour générer la configuration avec une durée de vie de jeton configurable, exécutez la commande suivante (cet exemple utilise une configuration AWS, mais la durée de vie du jeton peut être configurée pour tous les fournisseurs de fédération d'identité de charge de travail) :

  # 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>

Remplacez les éléments suivants :

  • PROJECT_NUMBER : numéro du projet Google Cloud .
  • POOL_ID : ID du pool d'identités de charge de travail.
  • AWS_PROVIDER_ID : ID du fournisseur AWS.
  • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service dont l'identité doit être empruntée.
  • TOKEN_LIFETIME : durée de vie sélectionnée du jeton d'accès au compte de service, en secondes.

L'option service-account-token-lifetime-seconds est facultative. Si aucune valeur n'est fournie, la valeur par défaut de l'indicateur est d'une heure. La valeur minimale autorisée est de 600 (10 minutes) et la valeur maximale autorisée est de 43 200 (12 heures). Si vous avez besoin d'une durée de vie supérieure à une heure, vous devez ajouter le compte de service en tant que valeur autorisée dans un service de règles d'administration qui applique la contrainte constraints/iam.allowServiceAccountCredentialLifetimeExtension.

Si vous configurez une durée de vie courte (par exemple, 10 minutes), la bibliothèque lance l'intégralité du flux d'échange de jetons toutes les 10 minutes. Cela appelle le fournisseur de jetons tiers même si le jeton tiers n'a pas expiré.

Utiliser les identifiants autorisés du personnel pour un compte externe

Les identifiants d'utilisateur autorisé pour un compte externe vous permettent de vous connecter avec un navigateur Web à un compte de fournisseur d'identité externe à l'aide de la gcloud CLI et de créer une configuration pour la bibliothèque auth à utiliser.

Pour générer une configuration d'identité des employés pour un utilisateur autorisé d'un compte externe, exécutez la commande suivante :

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

Où la variable suivante doit être remplacée :

Un flux de navigateur s'ouvre pour vous permettre de vous connecter à l'aide du fournisseur d'identité tiers configuré. Il stocke ensuite la configuration de l'utilisateur autorisé du compte externe à l'emplacement ADC bien connu.

La bibliothèque Auth utilisera ensuite le jeton d'actualisation fourni dans la configuration pour générer et actualiser un jeton d'accès permettant d'appeler les services Google Cloud .

La durée de vie par défaut du jeton d'actualisation est d'une heure. Ensuite, vous devez générer une nouvelle configuration à partir de la gcloud CLI. Vous pouvez modifier la durée de vie en changeant la durée de session du pool d'employés, et vous pouvez la définir sur une durée maximale de 12 heures.

Utiliser des identités externes

Vous pouvez utiliser des identités externes avec Application Default Credentials. Pour utiliser des identités externes avec les Identifiants par défaut de l'application, générez le fichier de configuration des identifiants JSON pour votre identité externe, comme décrit dans la section Fédération d'identité de charge de travail. Une fois généré, stockez le chemin d'accès à ce fichier dans la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

La bibliothèque peut désormais choisir le bon type de client et initialiser les identifiants à partir du contexte fourni par le fichier de configuration.

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());

Vous pouvez également initialiser explicitement les clients de compte externe à l'aide du fichier de configuration généré.

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

Points à noter concernant la sécurité

Cette bibliothèque n'effectue aucune validation sur les champs token_url, token_info_url ou service_account_impersonation_url de la configuration des identifiants. Nous vous déconseillons d'utiliser une configuration d'identifiants que vous n'avez pas générée avec gcloud CLI, sauf si vous vérifiez que les champs d'URL pointent vers un domaine googleapis.com.

Réduire les champs d'application avec des limites d'accès aux identifiants

La réduction du champ d'application avec les limites d'accès aux identifiants permet de restreindre les autorisations IAM (Identity and Access Management) qu'un identifiant de courte durée peut utiliser pour Cloud Storage. Pour ce faire, vous devez créer un CredentialAccessBoundary qui définit les restrictions qui s'appliquent au jeton à accès limité. L'utilisation d'identifiants à accès limité garantit que les jetons en transit disposent toujours du minimum de droits d'accès. Consultez Principe du moindre privilège.

Créer un objet CredentialAccessBoundary

La limite d'accès aux identifiants spécifie les ressources auxquelles les identifiants nouvellement créés peuvent accéder. Elle spécifie également une limite supérieure des autorisations disponibles pour chaque ressource. Il inclut un ou plusieurs objets AccessBoundaryRule.

L'extrait suivant montre comment initialiser un CredentialAccessBoundary avec un AccessBoundaryRule. Cette règle spécifie que le jeton à accès limité aura un accès en lecture seule aux objets commençant par customer-a dans le 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();

Schéma d'utilisation courant

Le modèle d'utilisation courant implique un agent de service de jetons avec un accès élevé. Ce courtier génère des identifiants à champ d'application limité à partir d'identifiants sources à accès plus élevé. Il transmet ensuite les jetons d'accès de courte durée à champ d'application limité à un consommateur de jetons via un canal authentifié sécurisé pour un accès limité aux ressources de stockage Google Cloud.

Générer des jetons à accès limité

Il existe deux façons de générer des jetons à portée limitée à l'aide d'un CredentialAccessBoundary :

  • Côté serveur (avec DownscopedCredentials) : le client appelle le Security Token Service (STS) chaque fois qu'un jeton à accès limité est nécessaire. Cette approche convient aux applications dont les règles de limite d'accès aux identifiants changent rarement ou dans lesquelles vous réutilisez plusieurs fois un même identifiant à portée réduite. Un point important à prendre en compte est que chaque modification de règle nécessite un nouvel appel au STS. Cette approche est disponible dans la bibliothèque google-auth-library-oauth2-http et ne nécessite aucune dépendance supplémentaire. Cela simplifie l'intégration. C'est un bon choix si votre cas d'utilisation ne nécessite pas les avantages spécifiques de l'approche côté client.

  • Côté client (à l'aide de ClientSideCredentialAccessBoundaryFactory) : le client récupère le matériel cryptographique une seule fois, puis génère plusieurs jetons à portée limitée en local. Cela réduit au minimum les appels au STS et est plus efficace lorsque les règles de limites d'accès aux identifiants changent fréquemment, car le client n'a pas besoin de contacter le STS pour chaque modification de règle. Cette méthode est également plus efficace pour les applications qui doivent générer de nombreux jetons uniques à portée limitée. Cette approche est disponible dans le module google-auth-library-cab-token-generator. Toutefois, ce module est fourni avec son propre ensemble de dépendances. Ces dépendances peuvent complexifier votre projet. Envisagez cette approche si la réduction des appels STS et la génération de nombreux jetons uniques sont des préoccupations majeures. Vous devrez également gérer les dépendances supplémentaires.

CAB côté serveur

La classe DownscopedCredentials peut être utilisée pour générer un jeton d'accès à accès limité à partir d'un identifiant source et de 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 côté client

Pour le CAB côté client, ClientSideCredentialAccessBoundaryFactory est utilisé avec un identifiant source. Après avoir initialisé la fabrique, la méthode generateToken() peut être appelée à plusieurs reprises avec différents objets CredentialAccessBoundary pour créer plusieurs jetons à accès limité.

// 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);

Utiliser des jetons d'accès à portée limitée

Vous pouvez configurer un courtier de jetons sur un serveur d'un réseau privé. Différentes charges de travail (consommateurs de jetons) du même réseau envoient des requêtes authentifiées à cet agent de service pour obtenir des jetons à champ d'application limité. Ces jetons leur permettent d'accéder à des buckets Google Cloud Storage spécifiques ou de les modifier.

L'agent instancie des instances d'identifiants à champ d'application limité qui peuvent générer des jetons d'accès à champ d'application limité éphémères. Il transmet ensuite ces jetons au consommateur de jetons.

Ces jetons d'accès à champ d'application limité peuvent être utilisés par le consommateur de jetons à l'aide de OAuth2Credentials ou OAuth2CredentialsWithRefresh. Vous pouvez ensuite utiliser ces identifiants pour initialiser une instance de client de stockage afin d'accéder aux ressources de stockage Google Cloudà accès restreint.

// 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(...)

Seul Cloud Storage est compatible avec les limites d'accès aux identifiants. Les autres servicesGoogle Cloud ne sont pas compatibles avec cette fonctionnalité.

Utiliser des identifiants avec google-http-client

Les identifiants fournis par com.google.auth:google-auth-library-oauth2-http peuvent être utilisés avec les clients HTTP de Google. Les clients Google basés sur HTTP fournissent un HttpCredentialsAdapter qui peut être utilisé comme HttpRequestInitializer, le dernier argument de leurs compilateurs.

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();

Valider les jetons JWT (fonctionnalité bêta)

Pour vérifier un jeton JWT, utilisez la classe TokenVerifier.

Valider une signature

Pour valider une signature, utilisez la valeur par défaut 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.
}

Personnaliser TokenVerifier

Pour personnaliser un TokenVerifier, instanciez-le à l'aide de son compilateur :

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

Pour plus d'options, consultez la documentation TokenVerifier.Builder.

google-auth-library-credentials

Cet artefact contient des classes de base et des interfaces pour les identifiants Google :

  • Credentials : classe de base pour une identité autorisée. Les implémentations de cette classe peuvent autoriser votre application.
  • RequestMetadataCallback : il s'agit de l'interface du rappel qui reçoit le résultat du Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) asynchrone.
  • ServiceAccountSigner : interface pour un signataire de compte de service. Les implémentations de cette classe sont capables de signer des tableaux d'octets à l'aide des identifiants associés à un compte de service Google.

google-auth-library-appengine

Cet artefact dépend du SDK App Engine (appengine-api-1.0-sdk). Utilisez-le uniquement pour les applications exécutées dans des environnements App Engine qui utilisent urlfetch. La classe AppEngineCredentials vous permet d'autoriser votre application App Engine à partir d'une instance de AppIdentityService.

Utilisation :

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

Ce module fournit la classe ClientSideCredentialAccessBoundaryFactory, qui permet la génération côté client de jetons à champ d'application limité pour Cloud Storage à l'aide des limites d'accès aux identifiants. Cette approche est particulièrement utile pour les applications qui nécessitent des modifications fréquentes des règles de périmètre d'accès aux identifiants ou la génération de nombreux jetons à champ d'application limité uniques, car elle minimise les appels au service de jetons de sécurité (STS). Pour obtenir des exemples d'utilisation, consultez la section CAB côté client. Ce module est fourni avec son propre ensemble de dépendances. Évaluez si les avantages de la réduction du champ d'application côté client l'emportent sur la complexité supplémentaire pour votre cas d'utilisation spécifique.