Premiers pas avec la bibliothèque Google Auth

Présentation

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

En suivant ce guide, vous apprendrez à :

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

Cette documentation est destinée aux développeurs Java. Pour en savoir plus 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 d'accès limité.
  • 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 aux fichiers ou des flux, provenant d'une source externe, vous devez les valider. Fournir des identifiants non validés aux API Google ou aux bibliothèques clientes pour l'authentification auprès deGoogle Cloud peut compromettre la sécurité de vos systèmes et de vos données.

Pour en savoir plus, consultez Identifiants d'origine externe. Identifiants par défaut de l'application.

Importer la bibliothèque d'authentification

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

libraries-bom du SDK Java

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

Par exemple, pour importer la bibliothèque d'authentification 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 d'authentification directement avec la nomenclature de la bibliothèque d'authentification Google.

Nomenclature de la bibliothèque Google Auth

Vous pouvez utiliser la nomenclature de la bibliothèque Google Auth pour vous assurer que les modules d'authentification 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>

Remplacez google-auth-library-oauth2-http dans l'exemple 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 le 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 nomenclature avec Gradle, ajoutez-la en tant que dépendance platform. Ajoutez ensuite les modules google-auth-library dont vous avez besoin. La nomenclature garantit que les versions de tous les modules que vous utilisez sont compatibles. 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 nomenclatures Maven (BOM). Par conséquent, lorsque vous utilisez Scala, vous ne pouvez pas importer le google-auth-library-bom pour gérer automatiquement les versions compatibles des modules de la bibliothèque d'authentification et leurs dépendances transitives.

Vous devez ajouter chaque sous-module requis directement à votre fichier build.sbt. Il est essentiel de spécifier et d'aligner explicitement les versions de tous les modules google-auth-library que vous utilisez. Si vous ne maintenez pas la cohérence des versions, des conflits de versions peuvent survenir entre les dépendances transitives, ce qui peut entraîner 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"

Journalisation de la bibliothèque d'authentification

La bibliothèque d'authentification Java recommande de consigner les journaux à l'aide de la journalisation de débogage de la bibliothèque cliente. La journalisation de débogage hachera les jetons sensibles (par exemple, access_token, refresh_token, etc.) et les valeurs seront masquées. La journalisation avec java.util.logging est désactivée dans la bibliothèque d'authentification pour éviter la fuite de jetons sensibles.

La fonctionnalité de journalisation du débogage client est facultative et nécessite une configuration.

La journalisation de débogage peut consigner les éléments suivants en fonction du niveau de journalisation :

  • Informations sur la requête : en-têtes, URL, méthode (niveau INFO)
  • Informations sur la réponse : en-têtes, état, message (niveau INFO)
  • Charge utile de la réponse (niveau DEBUG)

Migrer de GoogleCredential vers GoogleCredentials

GoogleCredential de google-api-java-client est obsolète et GoogleCredentials est l'alternative recommandée.

Instanciez GoogleCredentials à l'aide des identifiants par défaut de l'application (ADC). Il s'agit de 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 d'authentification Google 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 un niveau d'identité et d'autorisation cohérent, 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, ce 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 non-Google 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 de Google Cloud SDK.
  3. Identifiants intégrés de Google App Engine.
  4. Google Cloud Identifiants intégrés à Shell.
  5. Identifiants intégrés de 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 empruntés

Utilisez ImpersonatedCredentials pour permettre à un identifiant (le compte principal) d'emprunter l'identité d'un compte de service (la cible). Cela permet au compte 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 dans le projet du compte principal.
  • Le compte principal doit disposer du rôle IAM (Identity and Access Management) Service Account Token Creator sur le compte de service cible.

L'exemple de code suivant crée ImpersonatedCredentials. L'identifiant du compte principal est obtenu à partir des Identifiants par défaut de l'application (ADC). Les ImpersonatedCredentials résultants 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.")
        .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);
}

Jetons liés à un certificat pour les identités d'agent

Lorsque votre application s'exécute avec une identité d'agent (par exemple, un service ou un job Cloud Run déployé avec --identity-type=agent-identity), ComputeEngineCredentials demande par défaut des jetons d'accès et des jetons d'ID liés à un certificat au serveur de métadonnées. Un jeton lié est associé au certificat X.509 de la charge de travail et nécessite de prouver la possession de la clé privée correspondante via le protocole TLS mutuel (mTLS). Comme cette clé privée n'est disponible que pour la charge de travail, un jeton divulgué ne peut pas être utilisé ailleurs.

Un jeton lié n'est accepté que lorsque la requête qui le transporte est envoyée via mTLS avec le même certificat. Les bibliothèques clientes Cloud pour Java configurent mTLS et actualisent automatiquement les certificats de charge de travail alternés lorsque l'identité de l'agent est activée. Si vous appelez des API Google avec votre propre client HTTP, vous devez configurer mTLS avec le certificat de charge de travail et le recharger lorsque l'environnement d'exécution effectue une rotation du certificat sur le disque. Après la rotation, les jetons d'actualisation sont liés au nouveau certificat. Si un nouveau jeton est envoyé via une connexion mTLS établie avec le certificat précédent, l'API rejette la requête avec 401 UNAUTHENTICATED.

La bibliothèque ne demande un jeton lié que si toutes les conditions suivantes sont remplies :

  • Un certificat de charge de travail est trouvé, soit via le fichier nommé par la variable d'environnement GOOGLE_API_CERTIFICATE_CONFIG, soit à l'emplacement par défaut (/var/run/secrets/workload-spiffe-credentials/).
  • L'ID SPIFFE du certificat appartient à un domaine de confiance d'identité d'agent.
  • La liaison de jetons et mTLS n'ont pas été désactivés (voir Désactiver la liaison de jetons).

Dans tous les autres environnements, ComputeEngineCredentials se comporte comme avant et renvoie des jetons non liés.

Désactiver la liaison de jetons

Si vous devez désactiver la liaison de jetons (voir Limites connues), définissez la variable d'environnement suivante :

GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false
Variable d'environnement Effet
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN Définissez cette option sur false pour demander des jetons non liés.
GOOGLE_API_USE_CLIENT_CERTIFICATE Si vous définissez cette option sur false, mTLS est entièrement désactivé, ce qui désactive également la liaison de jetons. Privilégiez GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false si vous n'avez besoin que de jetons non liés.

Les valeurs ne sont pas sensibles à la casse, et les espaces blancs environnants sont ignorés. Seule la valeur false désactive une fonctionnalité. Toute autre valeur conserve la valeur par défaut.

Les variables d'environnement s'appliquent à l'ensemble du processus. Par conséquent, la désactivation de la liaison de jetons affecte toutes les bibliothèques de votre application qui utilisent les identifiants par défaut de l'application, et pas seulement celle qui en a besoin. Si vous n'avez besoin de jetons d'ID non liés que pour certaines cibles, utilisez plutôt l'option par cible décrite dans Demander des jetons d'ID non liés pour des cibles spécifiques.

Demander des jetons d'ID non liés pour des cibles spécifiques

Un jeton d'ID lié inclut l'empreinte du certificat de la charge de travail dans sa revendication cnf (x5t#S256). Les services de réception peuvent valider cette revendication par rapport au certificat client présenté lors d'un handshake mTLS, ou l'ignorer s'ils n'appliquent pas la liaison de certificat.

Cloud Run applique automatiquement la liaison de certificat lorsque la revendication cnf est présente dans un jeton d'ID. Si vous appelez un service Cloud Run avec un jeton d'ID lié, vous devez appeler son URL *.mtls.run.app via mTLS. Les requêtes adressées à une URL *.run.app standard ou à un domaine personnalisé sans mTLS sont rejetées avec l'erreur 401 Unauthorized.

Si vous appelez un service qui applique la liaison de certificat sur un point de terminaison non mTLS (tel qu'une URL *.run.app standard) ou si vous n'avez pas besoin de liaison de certificat pour un point de terminaison cible, transmettez IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN pour demander un jeton d'ID non lié pour cette cible uniquement :

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

Les jetons d'accès et les jetons d'ID des autres cibles sont toujours liés. Cette option n'est compatible qu'avec ComputeEngineCredentials. Les autres implémentations de IdTokenProvider ne demandent pas de jetons d'ID liés et ignorent cette option. Le même code fonctionne donc également en dehors des environnements d'identité d'agent.

Limitations connues

  • L'Agent Development Kit (ADK) pour Java n'utilise pas mTLS lorsqu'il appelle des API Google, telles que Gemini sur Vertex AI. Avec les jetons liés (par défaut), ces appels échouent avec com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials. Pour contourner ce problème, définissez GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false pour les agents qui utilisent ADK pour Java. Pour en savoir plus, consultez Authentifier des agents sur Cloud Run.

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 Clouddepuis Amazon Web Services (AWS), Microsoft Azure ou 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 . La fédération d'identité permet à votre charge de travail d'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 à partir d'Amazon Web Services (AWS), vous devez d'abord configurer la fédération d'identité de charge de travail. Le processus de configuration est décrit dans Accéder aux ressources depuis AWS.

Lors de ce processus, vous allez générer un fichier de configuration des identifiants. Ce fichier contient des métadonnées non sensibles qui indiquent à la bibliothèque comment récupérer des jetons d'objet externes et les échanger contre des jetons d'accès de 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 vous souhaitez emprunter l'identité.

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 maintenant utiliser la bibliothèque d'authentification pour appeler des ressourcesGoogle Cloud depuis AWS.

Accéder aux ressources de Microsoft Azure

Pour accéder aux ressources Google Cloud à partir de Microsoft Azure, vous devez d'abord configurer la fédération d'identité de charge de travail. Le processus de configuration est décrit dans Accéder aux ressources depuis Azure.

Lors de ce processus, vous allez générer un fichier de configuration des identifiants. Ce fichier contient des métadonnées non sensibles qui indiquent à la bibliothèque comment récupérer des jetons d'objet externes et les échanger contre des jetons d'accès de 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 vous souhaitez emprunter l'identité.

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

Vous pouvez maintenant utiliser la bibliothèque d'authentification 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 allez générer 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 des jetons d'objet externes et les échanger contre des jetons d'accès de compte de service.

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

Identifiants d'origine du fichier

Pour les identifiants basés sur des fichiers, un processus en arrière-plan doit actualiser en continu l'emplacement du fichier avec un nouveau jeton OIDC avant l'expiration. Pour les jetons d'une durée de vie d'une heure, vous devez mettre à jour le jeton dans le fichier toutes les heures. Vous pouvez stocker le jeton directement au format texte brut ou 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 vous souhaitez emprunter l'identité.
  • 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 requête de jeton, si le point de terminaison l'exige.

Pour générer une configuration Workload Identity 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 vous souhaitez emprunter l'identité.
  • 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 à la requête GET à URL_TO_GET_OIDC_TOKEN, par exemple Metadata-Flavor=Google.

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

Accéder aux ressources à l'aide d'identifiants provenant d'un certificat 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 d'identifiants principal et un fichier de configuration de certificat.

  • Le fichier de configuration des identifiants principaux 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 permet de 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'option --credential-cert-configuration-output-file.

Si vous omettez l'option --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 d'authentification peut détecter 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 vous souhaitez emprunter l'identité.
  • PATH_TO_CERTIFICATE : chemin d'accès à votre certificat X.509 feuille.
  • PATH_TO_PRIVATE_KEY : chemin d'accès à la clé privée correspondante pour le certificat d'entité finale.
  • 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 d'entité finale et le magasin de confiance configuré dans le pool de fédération d'identité de charge de travail. Le certificat d'entité finale est facultatif dans ce fichier.

Cette commande donne le résultat suivant :

  • /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 dans le chemin d'accès par défaut.
  • certificate_config.json : créé au niveau du chemin de configuration par défaut de la 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 de localisation personnalisé

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 donne 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 l'option.

Vous pouvez maintenant utiliser la bibliothèque d'authentification pour appeler des ressourcesGoogle Cloud avec des identifiants provenant d'un certificat X.509.

Utiliser des identifiants provenant d'un exécutable avec OIDC et SAML

Pour les identifiants exécutables, un fichier 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 au format JSON, valide et non expiré, à stdout.

Pour utiliser des identifiants d'origine exécutable, vous devez définir la variable d'environnement GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES sur 1.

Pour générer une configuration Workload Identity 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 vous souhaitez emprunter l'identité.
  • 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 absolu au programme.

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

L'option facultative --executable-output-file spécifie un chemin d'accès pour mettre en cache la réponse d'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 si ce fichier contient des identifiants valides et non arrivés à expiration avant d'exécuter l'exécutable. Si des identifiants valides mis en cache existent, les bibliothèques les utilisent, ce qui évite les exécutions inutiles d'exécutables.

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

Pour récupérer le jeton tiers, la bibliothèque exécute 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 le cadre d'une exception générée.

Résumé 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 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'emprunt 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 non autorisés d'exécuter l'exécutable, car il transmettra des identifiants sensibles à ces processus et à leurs utilisateurs via stdout.
  • Empêcher les processus non autorisés de modifier la configuration ou l'appel de l'exécutable.

En raison de la complexité de l'utilisation d'identifiants provenant d'un exécutable, 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 maintenant utiliser la bibliothèque d'authentification pour appeler des ressourcesGoogle Cloud à partir d'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 compilation 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 l'identifiant Google Cloud.

IdentityPoolCredentials ne met pas en cache le jeton renvoyé. Par conséquent, implémentez une logique de mise en cache dans le fournisseur de jetons pour éviter d'envoyer plusieurs requêtes pour le même jeton d'objet.

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ù 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 de compilateur en générant un fichier de configuration d'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. S'il est fourni, l'instance AwsCredentials s'en remet 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 met pas en cache les identifiants de sécurité ni la région AWS renvoyés. Par conséquent, implémentez une logique de mise en cache dans le fournisseur pour éviter les requêtes multiples 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 de compilateur en générant un fichier de configuration d'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 du 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 vous souhaitez emprunter l'identité.
  • 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 elle n'est pas fournie, l'option est définie par défaut sur 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 d'utilisateur autorisé d'un compte externe pour le personnel

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

Pour générer une configuration d'identité de personnel 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 d'authentification utilisera ensuite le jeton d'actualisation fourni par la configuration pour générer et actualiser un jeton d'accès afin 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 modifiant la durée de session du pool d'employés, et vous pouvez la définir sur une valeur 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 comptes externes à 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 la 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 applicables au jeton d'accès limité. L'utilisation d'identifiants à champ d'application réduit garantit que les jetons en cours de transfert disposent toujours du moindre privilège. 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 pour les autorisations disponibles sur chaque ressource. Il inclut un ou plusieurs objets AccessBoundaryRule.

L'extrait de code suivant montre comment initialiser un CredentialAccessBoundary avec un AccessBoundaryRule. Cette règle spécifie que le jeton à champ d'application restreint 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();

Modèle d'utilisation courant

Le modèle d'utilisation courant implique un courtier de jetons avec un accès élevé. Cet agent génère des identifiants à champ d'application limité à partir d'identifiants sources d'accès de niveau supérieur. Il transmet ensuite les jetons d'accès éphémères à champ d'application restreint à 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 à champ d'application restreint

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

  • Côté serveur (à l'aide de DownscopedCredentials) : le client appelle le service de jetons de sécurité (STS) chaque fois qu'un jeton à champ d'application restreint est nécessaire. Cette approche est adaptée aux applications dans lesquelles les règles de limite d'accès aux identifiants changent rarement ou dans lesquelles vous réutilisez plusieurs fois un même identifiant à champ d'application restreint. Un point clé 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 facilite l'intégration. Il s'agit d'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 une fois les données cryptographiques, puis génère plusieurs jetons à champ d'application limité localement. Cela réduit les appels au STS et est plus efficace lorsque les règles de limite 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 à champ d'application restreint. Cette approche est disponible dans le module google-auth-library-cab-token-generator. Toutefois, ce module est associé à son propre ensemble de dépendances. Ces dépendances peuvent ajouter de la complexité à 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 produire un jeton d'accès à niveau d'accès réduit à 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, le 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 d'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 à niveau d'accès réduit

Vous pouvez configurer un agent 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 pour obtenir des jetons à champ d'application restreint. 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 éphémères à champ d'application limité. Il transmet ensuite ces jetons au consommateur de jetons.

Ces jetons d'accès limités peuvent être utilisés par le consommateur de jetons à l'aide de OAuth2Credentials ou de 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 HTTP de Google 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();

Vérifier les jetons JWT (fonctionnalité bêta)

Pour valider un jeton JWT, utilisez la classe TokenVerifier.

Valider une signature

Pour valider une signature, utilisez la commande TokenVerifier par défaut :

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 l'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 découvrir d'autres options, consultez la documentation de 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 : interface du rappel qui reçoit le résultat de l'Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) asynchrone.
  • ServiceAccountSigner : il s'agit de l'interface d'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 s'exécutant sur 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 de générer côté client des jetons d'accès restreint pour Cloud Storage à l'aide de 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 limite d'accès aux identifiants ou la génération de nombreux jetons uniques à champ d'application limité, car elle réduit les appels au service de jeton 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. Déterminez 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.