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 Cloud de Confiance by S3NS .
En suivant ce guide, vous apprendrez à :
- Ajoutez les dépendances nécessaires de la bibliothèque d'authentification Google à 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).
- Configurez 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-credentialscontient des classes de base et des interfaces pour les identifiants Google.google-auth-library-appenginecontient les identifiants App Engine et dépend du SDK App Engine.google-auth-library-oauth2-httpcontient 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 à champ d'application restreint.google-auth-library-cab-token-generatorfournit 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 deCloud de Confiance by S3NS peut compromettre la sécurité de vos systèmes et de vos données.
Pour en savoir plus, consultez Identifiants d'origine externe.
Importer la bibliothèque Google Auth
Pour importer la bibliothèque Google Auth, utilisez com.google.cloud:libraries-bom ou la nomenclature de la bibliothèque Google Auth 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 Google, utilisez libraries-bom, qui extraira les versions de la bibliothèque d'authentification Google compatibles avec cette bibliothèque cliente.
Par exemple, pour importer la bibliothèque Google 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 de la bibliothèque d'authentification Google 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 de la bibliothèque Google 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 de la bibliothèque d'authentification Google 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 Google 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 Google
La bibliothèque d'authentification Google pour 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 Google Auth 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 enregistrer 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 le remplacement recommandé.
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 :
Bibliothèques clientes Cloud : ces bibliothèques utilisent automatiquement les Identifiants par défaut de l'application (ADC). Vous n'avez donc pas besoin de fournir d'identifiants dans votre code.
Bibliothèques clientes des API Google : vous devez instancier
GoogleCredentialset les transmettre au client. Pour obtenir un exemple, consultez le guide du client Java des API Google.
Identifiants par défaut de l'application
La bibliothèque d'authentification Google pour Java fournit une implémentation des identifiants par défaut de l'application (ADC). 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 Cloud de Confiance.
Les ADC sont également compatibles avec la fédération d'identité de charge de travail, ce qui permet aux applications d'accéder aux ressources Cloud de Confiance à 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-Cloud de Confiance , 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 :
- Fichier d'identifiants pointé par la variable d'environnement
GOOGLE_APPLICATION_CREDENTIALS. - Identifiants fournis par la commande
gcloud auth application-default loginde Google Cloud SDK. - Identifiants intégrés de Google App Engine.
- Cloud de Confiance Identifiants intégrés à Shell.
- 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>.
- Ignorez cette vérification en définissant la variable d'environnement
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
IAMCredentialsdoit ê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 Creatorsur 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.s3ns.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);
}
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). Étant donné que 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 nouvellement actualisés 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. Seul 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éfinissezGOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=falsepour les agents qui utilisent l'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 Cloud de Confiancedepuis 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 Cloud de Confiance utilisent des clés de compte de service pour accéder aux ressources Cloud de Confiance . 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 Cloud de Confiance , 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 Cloud de Confiance à 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 de votre projet Cloud de Confiance .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 désormais utiliser la bibliothèque d'authentification Google pour Java afin d'appeler des ressourcesCloud de Confiance by S3NS depuis AWS.
Accéder aux ressources de Microsoft Azure
Pour accéder aux ressources Cloud de Confiance 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.
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 de votre projet Cloud de Confiance .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 désormais utiliser la bibliothèque d'authentification Google pour Java afin d'appeler des ressources Cloud de Confiancedepuis Azure.
Accéder aux ressources depuis un fournisseur d'identité OIDC
Pour accéder aux ressources Cloud de Confiance à 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 Google pour Java peut récupérer des jetons OIDC à partir de l'une des sources suivantes :
- Un fichier local (identifiants basés sur un fichier)
- Un serveur local (identifiants provenant d'URL)
- Un certificat X.509 et une clé privée (identifiants provenant d'un certificat X.509)
- Un fichier JSON local contenant à la fois un jeton d'objet et un jeton d'acteur pour la délégation d'acteur (avec liaison de certificat client X.509 facultative)
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 de votre projet Cloud de Confiance .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 de votre projet Cloud de Confiance .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_KEYetHEADER_VALUE: paires clé-valeur d'en-tête supplémentaires à transmettre à la requête GET àURL_TO_GET_OIDC_TOKEN, par exempleMetadata-Flavor=Google.
Vous pouvez désormais utiliser la bibliothèque d'authentification Google pour Java afin d'appeler des ressourcesCloud de Confiance à 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.
Comportement par défaut (recommandé)
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 Google 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 de votre projet Cloud de Confiance .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": truepour 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.jsonsous Linux et macOS, ou%APPDATA%\gcloud\certificate_config.jsonsous 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 désormais utiliser la bibliothèque d'authentification Google pour Java afin d'appeler des ressourcesCloud de Confiance by S3NS avec des identifiants provenant d'un certificat X.509.
Accéder aux ressources avec la délégation d'acteur
Pour les charges de travail qui utilisent la fédération d'identité de charge de travail OIDC avec délégation d'acteur (comme défini dans la RFC 8693 : OAuth 2.0 Token Exchange), la bibliothèque d'authentification Google pour Java échange un jeton d'objet tiers et un jeton d'acteur tiers à partir d'un fichier JSON local. Le jeton d'objet représente l'identité du compte principal pour la requête, et le jeton d'acteur représente la charge de travail ou le service agissant au nom de l'objet.
Vous pouvez utiliser la délégation d'acteur de deux manières :
- Délégation d'acteur standard (sans liaison de certificat) : la bibliothèque d'authentification Google échange le jeton d'objet et le jeton d'acteur via TLS standard avec le service de jeton de sécurité (
sts.googleapis.com) et, s'il est configuré, emprunte l'identité d'un compte de service aveciamcredentials.googleapis.com. - Jetons liés à un certificat avec délégation d'acteur (mTLS) : la bibliothèque d'authentification Google présente un certificat client X.509 via TLS mutuel (mTLS) lors de l'échange de jetons avec
sts.mtls.googleapis.com(et, si configuré, l'emprunt d'identité du compte de service aveciamcredentials.mtls.googleapis.com).Cloud de Confiance vérifie que l'empreinte du certificat SHA-256 dans la revendication de confirmation (cnf.x5t#S256) du jeton correspond au certificat client feuille présenté dans le handshake mTLS et émet un jeton d'accès de courte durée lié de manière cryptographique à ce certificat.
Avant de commencer
Avant de configurer la bibliothèque d'authentification Google pour Java, assurez-vous de disposer des éléments suivants :
- Un pool d'identités de charge de travail OIDC et un fournisseur configurés pour la délégation d'acteur (avec le nom complet de la ressource du fournisseur d'acteur autorisé dans la configuration
--actor-providersdu fournisseur de sujet) et, éventuellement, l'application des règles d'accès contextuel lors de l'utilisation de jetons liés à un certificat. Un processus en arrière-plan local qui actualise en continu un fichier JSON contenant à la fois le jeton d'objet et le jeton d'acteur avant expiration :
{ "subject_token": "<var>SUBJECT_JWT_TOKEN</var>", "actor_token": "<var>ACTOR_JWT_TOKEN</var>" }Assurez-vous que les jetons répondent aux exigences suivantes :
Jeton d'objet (revendication
may_act) : le jeton d'objet doit inclure une revendicationmay_actautorisant la revendicationsub(et éventuellementiss) de l'acteur :"may_act": { "sub": "<var>ACTOR_SUBJECT</var>", "iss": "<var>ACTOR_ISSUER</var>" } ```Jeton d'acteur (revendications
aud,subetiss) : la revendicationauddu jeton d'acteur doit être définie sur le nom complet de la ressource du fournisseur d'acteur (//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>ACTOR_PROVIDER_ID</var>), et sa revendicationsub(etiss) doit correspondre aux valeurs déclarées dans la revendicationmay_actdu jeton d'objet.Revendication de confirmation (
cnf) (pour les jetons liés à un certificat uniquement) : la charge utile JWT du jeton lié doit inclure une revendicationcnfcontenant l'empreinte du certificat SHA-256 encodée en base64url (x5t#S256) du certificat d'entité finale X.509 encodé en DER de la charge de travail. Si le jeton d'objet est lié à un certificat, le jeton d'acteur doit également être lié à un certificat, et le certificat client présenté lors du handshake mTLS doit correspondre à l'empreinte du certificatcnf.x5t#S256du jeton d'acteur :"cnf": { "x5t#S256": "<var>BASE64URL_SHA256_CERT_FINGERPRINT</var>" } ```
(Pour les jetons liés à un certificat uniquement) Un fichier de certificat d'entité finale X.509 encodé au format PEM et un fichier de clé privée PKCS#8 non chiffré correspondant sur le disque.
Générer des fichiers de configuration pour la délégation d'acteur
Vous pouvez générer les fichiers de configuration à l'aide de la commande gcloud iam workload-identity-pools create-cred-config.
Délégation d'acteur standard (sans liaison de certificat)
Pour générer un fichier de configuration d'identifiants (config.json) pour la délégation d'acteur standard sans liaison de certificat, exécutez la commande suivante :
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--output-file /path/to/config.json
Jetons liés à un certificat avec délégation d'acteur (mTLS)
Pour configurer des jetons liés à un certificat avec délégation d'acteur, la gcloud CLI génère deux fichiers distincts lorsque les options --credential-cert-path et --credential-cert-private-key-path sont spécifiées :
- Fichier de configuration des identifiants principaux (
config.json) : contient les métadonnées du pool d'identités de charge de travail, les points de terminaison.mtls.googleapis.com, le chemin d'accès au fichier de jeton JSON et les noms de champs pour les jetons d'objet et d'acteur, ainsi qu'une référence au fichier de configuration du certificat. - Fichier de configuration du certificat (
certificate_config.json) : spécifie les chemins d'accès au certificat d'entité finale X.509 et à la clé privée de la charge de travail.
Si vous omettez l'option --credential-cert-configuration-output-file (recommandé), gcloud crée certificate_config.json au niveau du chemin de configuration par défaut de Google Cloud CLI (~/.config/gcloud/certificate_config.json sous Linux et macOS, ou %APPDATA%\gcloud\certificate_config.json sous Windows) et définit "use_default_certificate_config": true dans config.json :
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--output-file /path/to/config.json
Si vous devez stocker le fichier de configuration du certificat dans un emplacement autre que celui par défaut, spécifiez l'option --credential-cert-configuration-output-file :
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_TOKENS_JSON</var>" \
--credential-source-type "json" \
--credential-source-field-name "<var>SUBJECT_TOKEN_FIELD_NAME</var>" \
--actor-token-field-name "<var>ACTOR_TOKEN_FIELD_NAME</var>" \
--actor-token-type "urn:ietf:params:oauth:token-type:jwt" \
--credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
--credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
--credential-cert-configuration-output-file "/custom/path/certificate_config.json" \
--output-file /path/to/config.json
Remplacez les éléments suivants :
PROJECT_NUMBER: numéro de votre projet Cloud de Confiance .POOL_ID: ID du pool d'identités de charge de travail.OIDC_PROVIDER_ID: ID du fournisseur de pool d'identités de charge de travail OIDC qui authentifie le jeton d'objet.SERVICE_ACCOUNT_EMAIL: facultatif. Adresse e-mail du compte de service dont l'identité doit être empruntée. Omettez--service-accountsi vous utilisez l'accès direct aux ressources.PATH_TO_TOKENS_JSON: chemin d'accès au fichier JSON local contenant à la fois le jeton d'objet et le jeton d'acteur.SUBJECT_TOKEN_FIELD_NAME: clé JSON dansPATH_TO_TOKENS_JSONqui contient le jeton d'objet (par exemple,subject_token).ACTOR_TOKEN_FIELD_NAME: clé JSON dansPATH_TO_TOKENS_JSONqui contient le jeton d'acteur (par exemple,actor_token). Cette clé doit être différente deSUBJECT_TOKEN_FIELD_NAME.PATH_TO_CERTIFICATE(jetons liés à un certificat uniquement) : chemin d'accès à votre certificat X.509 feuille encodé au format PEM.PATH_TO_PRIVATE_KEY(jetons liés à un certificat uniquement) : chemin d'accès à la clé privée correspondante encodée au format PEM.
Configurer les variables d'environnement et appeler les API Cloud de Confiance
Définissez
GOOGLE_APPLICATION_CREDENTIALSde sorte qu'il pointe vers votre fichier de configuration des identifiants :export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.jsonLorsque vous utilisez des jetons liés à un certificat, définissez également
GOOGLE_API_USE_CLIENT_CERTIFICATE=truepour activer le transport mTLS du certificat client dans les bibliothèques clientes Cloud :export GOOGLE_API_USE_CLIENT_CERTIFICATE=trueSi vous avez stocké
certificate_config.jsondans un emplacement personnalisé, définissezGOOGLE_API_CERTIFICATE_CONFIG:export GOOGLE_API_CERTIFICATE_CONFIG=/custom/path/certificate_config.jsonInitialisez une bibliothèque cliente Cloud de Confiance à l'aide des identifiants par défaut de l'application. La bibliothèque cliente utilise automatiquement
IdentityPoolCredentialspour échanger les jetons de sujet et d'acteur (et présente le certificat client de la charge de travail via mTLS lorsque la liaison de certificat est configurée) :import com.google.cloud.pubsub.v1.TopicAdminClient; import com.google.pubsub.v1.ProjectName; import com.google.pubsub.v1.Topic; public class ActorDelegationExample { public static void main(String[] args) throws Exception { String projectId = "your-project-id"; // TopicAdminClient automatically detects GOOGLE_APPLICATION_CREDENTIALS // and uses mTLS when GOOGLE_API_USE_CLIENT_CERTIFICATE=true is set. try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) { for (Topic topic : topicAdminClient.listTopics(ProjectName.of(projectId)).iterateAll()) { System.out.println(topic.getName()); } } } }
Rotation des jetons et des certificats
Lorsque votre processus en arrière-plan effectue la rotation des jetons (et, pour les jetons liés à un certificat, du certificat d'entité finale X.509 et de la clé privée de la charge de travail) sur le disque, tenez compte des comportements et exigences suivants :
- Mises à jour atomiques : la bibliothèque d'authentification Google lit à la fois le jeton d'objet et le jeton d'acteur du fichier de jeton JSON en une seule lecture par actualisation. Mettez à jour le fichier de jeton JSON de manière atomique (par exemple, en écrivant dans un fichier temporaire et en le renommant) afin que le jeton d'objet et le jeton d'acteur restent synchronisés. Lorsque vous utilisez des jetons liés à un certificat, mettez à jour le certificat, la clé privée et le fichier de jeton JSON de manière atomique afin que l'empreinte
cnf.x5t#S256du fichier de jeton reste synchronisée avec le certificat X.509 sur le disque. - Épinglage de certificat par cycle (jetons liés à un certificat) : lorsque
IdentityPoolCredentialsactualise un jeton d'accès via mTLS, il prend un instantané du keystore X.509 au début du cycle d'actualisation et utilise le même certificat client pour la requête Security Token ServiceexchangeTokenet (si configuré) la requête d'emprunt d'identité de l'API Service Account CredentialsgenerateAccessToken. - Actualisation automatique sur
401 Unauthorized(jetons liés à un certificat) : si le certificat effectue une rotation et qu'une requête mTLS renvoie401 Unauthorized, la bibliothèque d'authentification Google actualise automatiquement le certificat X.509 et la clé privée à partir du disque, puis tente d'actualiser le jeton une fois.
Résoudre les problèmes de délégation d'acteur
Le tableau suivant liste les erreurs courantes et les solutions pour la délégation d'acteur :
| Erreur ou exception | Cause | Solution |
|---|---|---|
IllegalArgumentException: Actor tokens are only supported for JSON-formatted credential sources. |
credential_source.format.type est manquant ou défini sur text, alors que actor_token_field_name est spécifié. |
Définissez credential_source.format.type sur "json", et spécifiez subject_token_field_name et actor_token_field_name. |
IllegalArgumentException: The actor_token_field_name must not be empty. |
actor_token_field_name dans credential_source.format est une chaîne vide (""). |
Indiquez un nom de champ JSON non vide pour actor_token_field_name ou supprimez le champ si la délégation d'acteur n'est pas utilisée. |
IllegalArgumentException: The actor_token_field_name must differ from the subject_token_field_name. |
actor_token_field_name et subject_token_field_name sont définis sur la même clé JSON. |
Utilisez des noms de champs JSON distincts pour le jeton d'objet et le jeton d'acteur dans votre fichier de jeton et config.json. |
IllegalArgumentException: An actorTokenType must be specified when an actorTokenSupplier is configured. (ou vice versa) |
Seul actor_token_type ou actor_token_field_name est présent dans config.json. |
Indiquez à la fois "actor_token_type": "urn:ietf:params:oauth:token-type:jwt" et credential_source.format.actor_token_field_name. |
IOException: Invalid token field name. No token was found for field: FIELD_NAME |
Le fichier JSON situé à l'emplacement credential_source.file ne contient pas la clé subject_token_field_name ou actor_token_field_name configurée, ou sa valeur est null. |
Vérifiez que votre processus d'actualisation des jetons écrit les deux clés dans le fichier JSON. |
IOException: Invalid token field value. Empty token was found for field: FIELD_NAME |
La clé subject_token_field_name ou actor_token_field_name configurée dans le fichier de jeton JSON est une chaîne vide ou ne contient que des espaces blancs. |
Vérifiez que votre processus d'actualisation des jetons renseigne les deux champs avec des chaînes JWT non vides. |
IOException: Token field value for FIELD_NAME must be a String... |
La valeur de subject_token_field_name ou actor_token_field_name dans le fichier de jeton JSON est un objet, un tableau, un nombre ou une valeur booléenne JSON au lieu d'une chaîne. |
Assurez-vous que les deux champs de jeton contiennent des chaînes JWT sérialisées ("eyJ..."). |
RuntimeException: Failed to initialize mTLS transport for file credential source due to certificate configuration error. |
Le SDK n'a pas pu charger ni analyser certificate_config.json, le certificat X.509 à l'emplacement cert_path ou la clé privée à l'emplacement key_path. |
Vérifiez que certificate_config.json existe dans le chemin d'accès par défaut (ou GOOGLE_API_CERTIFICATE_CONFIG) et que cert_path et key_path pointent vers des fichiers PEM valides et lisibles. |
400 Bad Request/invalid_request de sts.mtls.googleapis.com |
L'empreinte cnf.x5t#S256 du jeton ne correspond pas au certificat client présenté lors du handshake mTLS. |
Vérifiez que la valeur x5t#S256 est le hachage SHA-256 encodé en base64url du certificat d'entité finale encodé en DER dans certificate_config.json. |
401 Unauthorized ou 403 Forbidden lors de l'appel des API Cloud de Confiance après l'échange de jetons réussi |
La bibliothèque cliente en aval n'a pas établi de mTLS ou a utilisé un certificat différent de celui lié au jeton d'accès. | Vérifiez que export GOOGLE_API_USE_CLIENT_CERTIFICATE=true est défini et que (si vous utilisez un chemin d'accès de configuration de certificat personnalisé) GOOGLE_API_CERTIFICATE_CONFIG pointe vers le même fichier certificate_config.json référencé par config.json. |
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 de votre projet Cloud de Confiance .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 Google attendra la fin de l'exécutable. Si elle n'est pas fournie, elle est définie par défaut sur 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 et mis en cache existent, les bibliothèques les utilisent, ce qui évite les exécutions inutiles de l'exécutable.
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 Google Auth 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 désormais utiliser la bibliothèque d'authentification Google pour Java afin d'appeler des ressourcesCloud de Confiance by S3NS à 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 Cloud de Confiance . Le fournisseur doit renvoyer un jeton d'objet valide et non expiré lorsqu'il est appelé par l'identifiant Cloud de Confiance.
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 Cloud de Confiance 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 de votre projet Cloud de Confiance .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 compilateur en générant un fichier de configuration d'identifiants avec la 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èsCloud de Confiance . Le fournisseur doit renvoyer des identifiants de sécurité AWS valides et non expirés lorsqu'il est appelé par l'identifiant Cloud de Confiance .
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 Cloud de Confiance 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 de votre projet Cloud de Confiance .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 compilateur en générant un fichier de configuration d'identifiants avec la 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 de votre projet Cloud de Confiance .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 Google pourra 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 :
LOGIN_CONFIG: fichier de configuration de connexion généré avec la console Cloud de Confiance ou gcloud iam workforce-pools create-login-config
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 Google pour Java 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 servicesCloud de Confiance .
La durée de vie par défaut du jeton d'actualisation est d'une heure. Vous devez ensuite 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 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 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 agent de jeton 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 de courte durée à un consommateur de jetons via un canal authentifié sécurisé pour un accès limité aux ressources Cloud de ConfianceStorage.
Générer des jetons à champ d'application restreint
Il existe deux façons de générer des jetons à champ d'application restreint à 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 option est adaptée aux applications dans lesquelles les règles de limite d'accès aux identifiants changent rarement ou lorsque vous réutilisez plusieurs fois un même identifiant à champ d'application restreint. Un point clé à prendre en compte est que chaque modification de règle nécessite un nouvel appel au STS. Cette approche est disponible dans la bibliothèquegoogle-auth-library-oauth2-httpet 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 éléments cryptographiques, puis génère localement plusieurs jetons à champ d'application restreint. 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 modulegoogle-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 à champ d'application 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 à champ d'application réduit
Vous pouvez configurer un agent de jetons sur un serveur d'un réseau privé. Diverses 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 Cloud de Confiance 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 à champ d'application restreint 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 Cloud de Confianceà 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 servicesCloud de Confiance 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 d'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 à l'aide 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.