Obtenir des jetons de courte durée pour la fédération d'identité de personnel

Ce guide explique comment utiliser un pool d'identités des employés et un fournisseur de pools d'identités des employés pour obtenir des jetons de courte durée auprès de Security Token Service. Vous pouvez utiliser les jetons pour accéder aux ressources Google Cloud compatibles avec la fédération des identités des employés auxquelles vous avez été autorisé.

Les méthodes décrites dans ce guide peuvent être utilisées sur des machines sans interface graphique.

Pour obtenir des jetons de courte durée, procédez comme suit:

  1. Obtenez des identifiants auprès du fournisseur d'identité approuvé.
  2. Échangez les identifiants contre un jeton Security Token Service.

Avant de commencer

  1. Configurez la fédération d'identité de personnel ou, pour obtenir des instructions spécifiques à votre fournisseur d'identité, consultez les guides suivants :

    Notez l'ID de votre pool d'identités de personnel et l'ID de votre fournisseur de pool d'identités de personnel.

  2. Assurez-vous de disposer de l'autorisation IAM (Identity and Access Management) serviceusage.services.use. Le rôle le moins privilégié qui contient cette autorisation est "Consommateur Service Usage" (roles/serviceusage.serviceUsageConsumer).

  3. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  4. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

Échanger des identifiants externes contre un jeton d'accès Google Cloud

Cette section explique comment utiliser Security Token Service pour échanger des identifiants externes contre un jeton d'accès accordant l'accès à Google Cloud. Pour ce faire, utilisez gcloud CLI, l'API REST et les bibliothèques clientes Cloud, comme décrit plus loin dans le présent guide.

Si vous avez besoin d'un accès de longue durée, vous pouvez configurer un processus de longue durée pour actualiser en permanence les identifiants sur cette machine. Vous pouvez également exécuter un serveur local en arrière-plan avec un point de terminaison qui renvoie les identifiants.

Connexion via le navigateur avec gcloud CLI

Cette section explique comment configurer gcloud CLI pour utiliser un flux de connexion via le navigateur. Pour ce faire, vous devez créer un fichier de configuration de connexion, puis y faire référence dans les appels à gcloud auth login ou l'activer afin qu'il soit utilisé par défaut.

Créer le fichier de configuration de connexion

Pour créer le fichier de configuration de connexion, exécutez la commande suivante. Vous pouvez éventuellement définir par défaut l'activation du fichier pour gcloud CLI à l'aide de l'option --activate. 

gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID: ID du fournisseur de pools d'identités des employés
  • LOGIN_CONFIG_FILE: chemin d'accès au fichier de configuration de connexion que vous spécifiez, par exemple login.json

Le fichier contient les points de terminaison utilisés par gcloud CLI pour activer le flux d'authentification via le navigateur et définir l'audience sur le fournisseur d'identité configuré dans le fournisseur de pool d'identités de personnel. Votre fichier ne contient aucune information confidentielle.

La sortie ressemble à ceci :

{
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect",
}

Se connecter à l'aide d'une authentification basée sur le navigateur

Pour vous authentifier à l'aide de l'authentification de connexion basée sur le navigateur, vous pouvez utiliser l'une des méthodes suivantes :

  • Si vous avez utilisé l'option --activate lors de la création du fichier de configuration ou si vous avez activé le fichier de configuration avec la commande gcloud config set auth/login_config_file, gcloud CLI va utiliser automatiquement votre fichier de configuration : 

    gcloud auth login

  • Pour vous connecter en spécifiant l'emplacement du fichier de configuration, exécutez la commande suivante : 

    gcloud auth login --login-config=LOGIN_CONFIG_FILE
  • Pour utiliser une variable d'environnement afin de spécifier l'emplacement du fichier de configuration, définissez CLOUDSDK_AUTH_LOGIN_CONFIG_FILE sur le chemin d'accès de la configuration.

Désactiver la connexion via le navigateur

Pour arrêter d'utiliser le fichier de configuration de connexion, procédez comme suit :

  • Si vous avez utilisé l'option --activate lors de la création du fichier de configuration ou si vous avez activé le fichier de configuration avec la commande gcloud config set auth/login_config_file, vous devez exécuter la commande suivante pour le désactiver : 

    gcloud config unset auth/login_config_file
  • Si elle est définie, effacez la variable d'environnement CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

Utiliser des fichiers de configuration pour la connexion

Plutôt que de se connecter via un navigateur, cette section décrit différentes manières d'utiliser les fichiers de configuration des identifiants pour autoriser l'accès aux actions authentifiées de Google Cloud. Le paramétrage des fichiers de configuration ne suppose pas que vous soyez connecté à gcloud CLI.

La façon dont vous paramétrez votre fichier de configuration varie selon que votre fournisseur d'identité utilise OIDC ou SAML.

OIDC

Les identifiants que vous utilisez pour paramétrer votre fichier de configuration peuvent être obtenus comme suit :

Identifiants d'origine du fichier

Lorsque vous utilisez des identifiants basés sur un fichier, les jetons sont chargés à partir d'un fichier. Un autre processus doit actualiser ce fichier avec un nouveau jeton OIDC avant l'expiration de l'ancien. Par exemple, si le jeton a une durée de vie d'une heure, vous devez actualiser le fichier avant qu'il soit obsolète.

Pour générer le fichier de configuration avec un identifiant basé sur un fichier, exécutez la commande suivante :

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-file=PATH_TO_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés
  • PATH_TO_OIDC_TOKEN : chemin d'accès au fichier d'identifiants du fournisseur d'identité OIDC
  • WORKFORCE_POOL_USER_PROJECT : numéro ou ID du projet associé au projet utilisateur des pools d'employés.

Le compte principal doit disposer de l'autorisation serviceusage.services.use sur ce projet.

L'exécution de la commande génère un fichier de configuration de fournisseur d'identité OIDC semblable à celui-ci :

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

Identifiants provenant d'URL

Lorsque vous utilisez des identifiants basés sur une URL, les jetons sont chargés à partir d'un serveur local avec un point de terminaison qui répond aux requêtes HTTP GET. La réponse doit être un jeton d'identification OIDC, au format texte brut ou au format JSON.

Pour générer un fichier de configuration avec un identifiant basé sur une URL, exécutez la commande suivante:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token \
    --credential-source-url=URL_TO_RETURN_OIDC_ID_TOKEN \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file=config.json

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés
  • URL_TO_RETURN_OIDC_ID_TOKEN : URL à appeler pour récupérer les identifiants OIDC, tels qu'un jeton d'ID OIDC, par exemple : http://localhost:5000/token.
  • WORKFORCE_POOL_USER_PROJECT : numéro de projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation serviceusage.services.use permission sur ce projet.

L'exécution de la commande génère un fichier de configuration de fournisseur d'identité OIDC semblable à celui-ci :

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "url": "URL_TO_RETURN_OIDC_ID_TOKEN"
  }
}

Identifiants exécutables non interactifs

Lorsque vous utilisez des identifiants exécutables non interactifs, les jetons sont chargés depuis un fichier exécutable local. L'exécutable doit fournir un jeton d'ID OIDC valide et non expiré au format JSON à stdout:

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

Ces champs sont obligatoires pour que la réponse aboutisse, à l'exception de expiration_time. Le champ expiration_time n'est requis que lorsqu'un fichier de sortie a été spécifié dans la configuration des identifiants.

L'exécutable doit rapporter toutes les erreurs dans stdout au format JSON suivant :

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

Ces champs sont tous obligatoires pour une réponse d'erreur. Les champs de code et de message sont utilisés par les bibliothèques clientes lors de la génération de l'erreur appropriée.

La commande peut renvoyer les champs suivants :

  • version : version de la sortie JSON. Seule la version 1 est compatible.

  • success : état de la réponse. Lorsque l'état est true, l'exécutable doit se fermer avec le code de sortie 0 et la réponse doit contenir les champs suivants:

    • token_type : id_token
    • Champ expiration_time si un fichier de sortie est spécifié dans la configuration des identifiants.

    Lorsque l'état est false, l'exécutable doit se fermer avec une valeur non nulle et la réponse doit contenir les champs suivants:

    • code
    • message

  • token_type : type de jeton d'objet tiers, qui doit être urn:ietf:params:oauth:token-type:id_token.

  • id_token : jeton OIDC tiers.

  • expiration_time : délai d'expiration du jeton OIDC tiers en secondes (epoch Unix).

  • code : chaîne du code d'erreur.

  • message : message d'erreur.

Les bibliothèques clientes définissent les variables d'environnement suivantes lors de l'exécution de l'exécutable:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE : champ d'audience de la configuration des identifiants. Cette variable est toujours définie.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE : type de jeton d'objet attendu. Cette variable est toujours définie.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE : emplacement du fichier de sortie issu de la configuration des identifiants. Cette variable n'est présente que si elle est spécifiée 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.

Pour activer cette méthode d'approvisionnement en identifiants avec les bibliothèques clientes, vous devez définir la variable d'environnement GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES sur 1.

Pour générer le fichier de configuration avec un identifiant basé sur un exécutable, exécutez la commande suivante:

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés
  • EXECUTABLE_COMMAND : commande complète, comprenant les arguments, à exécuter pour récupérer le jeton d'objet, tel qu'un jeton d'ID OIDC, au format suivant : --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT : facultatif. Durée d'attente, en millisecondes, de l'exécution de l'exécutable (par défaut, 30 s).
  • EXECUTABLE_OUTPUT_FILE : facultatif. Chemin d'accès aux identifiants tiers générés par l'exécutable. Cela s'avère utile pour mettre en cache les identifiants. Les bibliothèques Auth vérifient d'abord ce chemin avant d'exécuter l'exécutable.
  • WORKFORCE_POOL_USER_PROJECT : numéro ou ID du projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation serviceusage.services.use sur ce projet.

L'exécution de la commande génère un fichier de configuration de fournisseur d'identité OIDC semblable à celui-ci :

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Identifiants exécutables interactifs

Lorsque vous utilisez des identifiants exécutables interactifs, vous pouvez fournir un exécutable qui interagit avec l'utilisateur via stdin et stdout. Si l'utilisateur s'est connecté, l'exécutable écrit un identifiant valide et non expiré dans le fichier spécifié.

Pour utiliser ce mode, vous devez spécifier les options suivantes :

  • --executable-output-file : fichier dans lequel l'exécutable écrit les informations d'identification.
  • --exeutable-interactive-timeout-millis : valeur non nulle qui indique le mode interactif et définit le délai avant expiration, par exemple 6000 pour un délai de 60 secondes.

Les champs suivants sont obligatoires pour une réponse positive, à l'exception de expiration_time :

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

L'exécutable doit écrire toutes les erreurs dans le fichier spécifié dans --executable-output-file au format JSON suivant : Les champs suivants sont tous obligatoires lors du renvoi d'une réponse d'erreur.

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

Les champs code et message doivent indiquer l'erreur appropriée. Ces champs sont utilisés par les bibliothèques clientes lors de la génération de l'erreur.

Une fois l'exécution terminée, la commande renvoie les mêmes champs pour les identifiants exécutables interactifs et non interactifs.

Les variables d'environnement sont également les mêmes pour les identifiants exécutables interactifs et non interactifs.

Pour générer un identifiant exécutable interactif, ajoutez le paramètre --executable-interactive-timeout-millis et le paramètre --executable-output-file.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés
  • EXECUTABLE_COMMAND : commande complète, comprenant les arguments, à exécuter pour récupérer le jeton d'objet, au format suivant : --executable-command="/path/to/command --arg1=val1 --arg2=val2"
  • EXECUTABLE_INTERACTIVE_TIMEOUT : durée d'attente, en millisecondes, de l'exécution de l'exécutable.
  • EXECUTABLE_OUTPUT_FILE: chemin d'accès aux identifiants tiers générés par l'exécutable. Cela s'avère utile pour mettre en cache les identifiants. Les bibliothèques d'authentification vérifient d'abord ce chemin avant d'exécuter l'exécutable.
  • WORKFORCE_POOL_USER_PROJECT : numéro ou ID du projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation serviceusage.services.use sur ce projet.

L'exécution de la commande génère un fichier de configuration de fournisseur d'identité OIDC semblable à celui-ci :

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "interactive_timeout_millis": "EXECUTABLE_INTERACTIVE_TIMEOUT",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE",
    }
  }
}

Le champ timeout_millis est renvoyé, car un exécutable interactif peut également s'exécuter en mode non interactif. En mode interactif, la commande renvoie un délai d'expiration par défaut.

SAML

Les identifiants que vous utilisez pour paramétrer votre fichier de configuration peuvent être obtenus comme suit :

Identifiants d'origine du fichier

Les assertions sont chargées à partir d'un fichier. Un autre processus doit actualiser ce fichier avec une nouvelle assertion SAML encodée en base64 avant l'expiration de l'ancienne assertion. Par exemple, si l'assertion a une durée de vie d'une heure, vous devez actualiser le fichier dans l'heure qui suit sa création.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=federation_config.json \
    --credential-source-file=CREDENTIAL_FILE \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés
  • CREDENTIAL_FILE : chemin d'accès au fichier d'identifiants généré par le fournisseur d'identité.
  • WORKFORCE_POOL_USER_PROJECT : numéro ou ID du projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation serviceusage.services.use permission sur ce projet.

Identifiants provenant d'URL

Les assertions sont chargées à partir d'un serveur local avec un point de terminaison qui répond aux requêtes HTTP "GET". La réponse doit être une assertion SAML [encodée en base64](https://toolbox.googleapps.com/apps/encode_decode/) ou un fichier JSON contenant une assertion SAML encodée en base64. Pour utiliser des identifiants provenant d'une URL, utilisez l'option `--credential-source-url` : ```sh gcloud iam workforce-pools create-cred-config \ locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \ --output-file=federation_config.json \ --credential-source-url=CREDENTIAL_URL \ --subject-token-type=urn:ietf:params:oauth:token-type:saml2 \ --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT ``` Remplacez les éléments suivants : * WORKFORCE_POOL_ID: ID du pool d'identité de la main-d'œuvre. * WORKFORCE_PROVIDER_ID: ID du fournisseur de pools d'identités des employés * CREDENTIAL_URL: URL du point de terminaison du serveur local. * WORKFORCE_POOL_USER_PROJECT: numéro ou ID du projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation "serviceusage.services.use" sur ce projet.

Identifiants exécutables

Les assertions sont chargées à partir d'un exécutable local. L'exécutable doit fournir à stdout une assertion SAML au format JSON, valide et non expirée.

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

Ces champs sont obligatoires pour que la réponse aboutisse, à l'exception de expiration_time. Le champ expiration_time n'est requis que lorsqu'un fichier de sortie est spécifié dans la configuration des identifiants.

Si une erreur se produit, elle doit être présentée par l'exécutable au format JSON suivant à stdout:

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

Ces champs sont tous obligatoires pour une réponse d'erreur. Les champs de code et de message sont utilisés par les bibliothèques clientes lors de la génération de l'erreur appropriée.

La commande peut renvoyer les champs suivants :

  • version : version de la sortie JSON. Seule la version 1 est compatible.

  • success : état de la réponse. Lorsque l'état est true, l'exécutable doit se fermer avec le code de sortie 0 et la réponse doit contenir les champs suivants :

    • token_type : saml_response
    • Champ expiration_time si un fichier de sortie est spécifié dans la configuration des identifiants.

    Lorsque l'état est false, l'exécutable doit se fermer avec une valeur non nulle et la réponse doit contenir les champs suivants : + code + message

  • token_type : type de jeton d'objet tiers, qui doit être urn:ietf:params:oauth:token-type:saml2.

  • saml_response : réponse SAML tierce.

  • expiration_time : délai d'expiration de la réponse SAML tierce en secondes (epoch Unix).

  • code : chaîne du code d'erreur.

  • message : message d'erreur.

Les bibliothèques clientes définissent les variables d'environnement suivantes lors de l'exécution de l'exécutable:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE : champ d'audience de la configuration des identifiants. Cette variable est toujours définie.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE : type de jeton d'objet attendu. Cette variable est toujours définie.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE : emplacement du fichier de sortie issu de la configuration des identifiants. Cette variable n'est présente que si elle est spécifiée dans la configuration des identifiants.

Pour activer cette méthode d'approvisionnement en identifiants avec les bibliothèques clientes, définissez la variable d'environnement GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES sur 1.

Pour générer le fichier de configuration avec un identifiant basé sur un exécutable, exécutez la commande suivante :

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés
  • EXECUTABLE_COMMAND : commande complète, comprenant les arguments, à exécuter pour récupérer le jeton d'objet, au format suivant : --executable-command="/path/to/command --foo=bar".
  • EXECUTABLE_TIMEOUT : facultatif. Durée en millisecondes d'attente pour l'exécution de l'exécutable (par défaut, 30 s).
  • EXECUTABLE_OUTPUT_FILE : facultatif. Chemin d'accès aux identifiants d'identité tierce (3PI) générés par l'exécutable. Cela s'avère utile pour mettre en cache les identifiants. Les bibliothèques d'autorisation vérifient son existence avant d'exécuter l'exécutable.
  • WORKFORCE_POOL_USER_PROJECT : numéro de projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation serviceusage.services.use sur ce projet.

L'exécution de la commande génère un fichier de configuration de fournisseur d'identité SAML semblable à celui-ci :

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "executable": {
      "command": "EXECUTABLE_COMMAND",
      "timeout_millis": "EXECUTABLE_TIMEOUT",
      "output_file": "EXECUTABLE_OUTPUT_FILE"
    }
  }
}

Identifiants exécutables pour le mode interactif de gcloud

Lorsque vous utilisez des identifiants issus d'un exécutable pour le mode interactif de gcloud, un exécutable interagit avec l'utilisateur via l'interface de ligne de commande.

Dans la commande ci-dessus, remplacez les éléments suivants :

  • EXECUTABLE_OUTPUT_FILE : valeur obligatoire. Chemin d'accès au fichier qui fournit les identifiants générés par l'exécutable.
  • EXECUTABLE_TIMEOUT : valeur obligatoire. Une valeur de délai avant expiration non nulle indique également la commande d'utiliser le mode interactif.
    {
      "version": 1,
      "success": true,
      "token_type": "urn:ietf:params:oauth:token-type:saml2",
      "saml_response": "...",
      "expiration_time": 1620499962
    }

Ces champs sont obligatoires pour que la réponse aboutisse, à l'exception de expiration_time. Lorsque expiration_time est omis, l'exécutable est toujours exécuté.

L'exécutable doit signaler toutes les erreurs dans executable-output-file au format JSON suivant. Lorsque l'exécutable signale une erreur, tous ces champs sont obligatoires. Les champs de code et de message sont utilisés par les bibliothèques clientes lors de la génération de l'erreur appropriée.

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

Une exécution de commande réussie renvoie les mêmes champs que les identifiants exécutables non interactifs.

Les variables d'environnement sont également les mêmes que les identifiants exécutables non interactifs.

Pour générer un identifiant exécutable interactif, ajoutez le paramètre --executable-interactive-timeout-millis.

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2  \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-interactive-timeout-millis=EXECUTABLE_INTERACTIVE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE \
    --workforce-pool-user-project=WORKFORCE_POOL_USER_PROJECT \
    --output-file /path/to/generated/config.json

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés
  • EXECUTABLE_COMMAND : commande complète, comprenant les arguments, à exécuter pour récupérer le jeton d'objet, au format suivant : --executable-command="/path/to/command --foo=bar").
  • EXECUTABLE_INTERACTIVE_TIMEOUT : durée d'attente, en millisecondes, de l'exécution de l'exécutable.
  • EXECUTABLE_OUTPUT_FILE: chemin d'accès aux identifiants tiers générés par l'exécutable. Cela s'avère utile pour mettre en cache les identifiants. Les bibliothèques d'authentification vérifient d'abord ce chemin avant d'exécuter l'exécutable.
  • WORKFORCE_POOL_USER_PROJECT : numéro ou ID du projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation serviceusage.services.use sur ce projet.

L'exécution de la commande génère un fichier de configuration de fournisseur d'identité SAML semblable à celui-ci :

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/<var>WORKFORCE_POOL_ID<var>/providers/<var>WORKFORCE_PROVIDER_ID</var>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "<var>WORKFORCE_POOL_USER_PROJECT</var>",
  "credential_source": {
    "executable": {
      "command": "<var>EXECUTABLE_COMMAND</var>",
      "interactive_timeout_millis": "<var>EXECUTABLE_INTERACTIVE_TIMEOUT</var>",
      "timeout_millis": "<var>EXECUTABLE_TIMEOUT</var>",
      "output_file": "<var>EXECUTABLE_OUTPUT_FILE</var>",
    }
  }
}

Pour vous connecter, exécutez la commande suivante :

gcloud auth login --cred-file=/path/to/config.json

Notez que ni la gcloud CLI, ni l'outil de ligne de commande bq ne sont compatibles avec les types d'identifiants basés sur un exécutable.

Pour les flux sans interface graphique, gcloud CLI utilise automatiquement le champ d'application suivant: https://www.googleapis.com/auth/cloud-platform. La gcloud CLI publie ensuite de manière transparente vos identifiants sur le point de terminaison Security Token Service, où ils sont échangés contre des jetons d'accès Google Cloud temporaires.

Vous pouvez maintenant exécuter les commandes gcloud en utilisant gcloud CLI.

Utiliser les bibliothèques clientes Google Cloud

Si vous utilisez une bibliothèque cliente compatible, vous pouvez la configurer de sorte qu'elle génère automatiquement des identifiants Google. Lorsque cela est possible, nous vous recommandons de générer automatiquement les identifiants afin de ne pas avoir à mettre en œuvre vous-même le processus d'échange de jetons.

Des bibliothèques clientes Google Cloud compatibles avec les pools de personnel sont disponibles dans les langages suivants : Node.js, Java, Python, Go et C++ (gRPC).

Pour utiliser les bibliothèques clientes avec ces services ou langages, procédez comme suit :

Outil bq

Pour vous authentifier à l'aide de la fédération d'identité de personnel, utilisez la commande gcloud auth login :

gcloud auth login --cred-file=FILEPATH.json

où FILEPATH est le chemin d'accès relatif au fichier de configuration des identifiants.

La fédération d'identité de personnel dans l'outil bq est disponible dans les versions 390.0.0 et ultérieures de Google Cloud CLI.

C++

La plupart des bibliothèques clientes Google Cloud pour C++ sont compatibles avec la fédération d'identité de personnel à l'aide d'un objet ChannelCredentials, créé en appelant grpc::GoogleDefaultCredentials(). Pour initialiser cet identifiant, vous devez créer les bibliothèques clientes avec la version 1.42.0 ou ultérieure de gRPC.

Les bibliothèques clientes Cloud Storage pour C++ utilisent l'API REST, et non gRPC. Elles ne sont donc pas compatibles avec la fédération d'identité de personnel.

auto creds = grpc::GoogleDefaultCredentials();

// Create a channel, stub and make RPC calls (same as in the previous example)
auto channel = grpc::CreateChannel("greeter.googleapis.com", creds);
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response);

gcloud

Pour vous authentifier à l'aide de la fédération d'identité de personnel, utilisez la commande gcloud auth login :

gcloud auth login --cred-file=FILEPATH.json

Remplacez FILEPATH par le chemin d'accès au fichier de configuration des identifiants.

La fédération d'identité de personnel dans la gcloud CLI est disponible dans la version 392.0.0 et les versions ultérieures de Google Cloud CLI.

Go

Les bibliothèques clientes Cloud pour Go sont compatibles avec la fédération d'identité de personnel lorsque vous utilisez la version v0.0.0-20211005180243-6b3c2da341f1 ou une version ultérieure du module golang.org/x/oauth2.

import (
  "context"
  "fmt"
  "log"

  "cloud.google.com/go/storage"
  "google.golang.org/api/iterator"
  "google.golang.org/api/option"
  "io/ioutil"
)
ctx := context.Background()
client, err := storage.NewClient(ctx)
# Explicit initialization can also be used.
# var jsonPath = "/path/to/3p-credentials.json"
# client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
if err != nil {
  log.Fatal(err)
}
fmt.Println("Buckets:")
it := client.Buckets(ctx, projectID)
for {
  battrs, err := it.Next()
  if err == iterator.Done {
    break
  }
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(battrs.Name)
}

Java

Les bibliothèques clientes Cloud pour Java sont compatibles avec la fédération d'identité de personnel lorsque vous utilisez la version 1.2.0 ou une version ultérieure de l'artefact com.google.auth:google-auth-library-oauth2-http.

import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
GoogleCredentials sourceCredentials = credentials
    .createScoped(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"));

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

Node.js

Les bibliothèques clientes Cloud pour Node.js sont compatibles avec la fédération d'identité de personnel lorsque vous utilisez la version 7.10.0 ou ultérieure du package google-auth-library.

Contrairement aux pools d'identités de charge de travail, les pools d'identités de personnel sont associés à une organisation et non à un projet Google Cloud. Lorsque vous créez un objet GoogleAuth, vous devez spécifier un ID de projet. Pour en savoir plus, consultez le fichier README du package google-auth-library.

const auth = new GoogleAuth({
  scopes: 'https://www.googleapis.com/auth/cloud-platform',
  // Specify a project ID.
  projectId: 'CLOUD_RESOURCE_PROJECT_ID',
});

# API request using Auth library.
const client = await auth.getClient();
const url =
    `https://storage.googleapis.com/storage/v1/b?projects=${projectId}`;
const res = await client.request({url});
console.log(res.data);

Python

Les bibliothèques clientes Cloud pour Python sont compatibles avec la fédération d'identité de personnel lorsque vous utilisez la version 2.3.0 ou ultérieure du package google-auth.

from google.cloud import storage
import google.auth

credentials, project = google.auth.default(
    scopes=['https://www.googleapis.com/auth/devstorage.read_only'])

client = storage.Client(
    project="project-id", credentials=credentials)

Dans l'exemple de code, la valeur project peut être None si la bibliothèque ne parvient pas à détecter automatiquement l'ID du projet. Vous pouvez transmettre l'ID de projet explicitement lorsque vous utilisez une instance de service, comme dans l'exemple du client de stockage, ou définir l'ID de projet via la variable d'environnement GOOGLE_CLOUD_PROJECT.

Pour en savoir plus, consultez le guide de l'utilisateur du package google-auth.

Utiliser l'API REST

Vous pouvez appeler l'API Google Cloud Security Token Service pour échanger vos identifiants externes contre des jetons d'accès Google Cloud en exécutant la commande suivante:

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID" \
    --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
    --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
    --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
    --data-urlencode "subject_token_type=SUBJECT_TOKEN_TYPE" \
    --data-urlencode "subject_token=EXTERNAL_SUBJECT_TOKEN"  \
    --data-urlencode "options={\"userProject\":\"BILLING_PROJECT_NUMBER\"}"

Remplacez les éléments suivants :

  • AUDIENCE : nom complet de la ressource du fournisseur qui émet le jeton d'objet.
  • WORKFORCE_POOL_ID : ID du pool d'identités de personnel
  • WORKFORCE_PROVIDER_ID : ID du fournisseur de pools d'identités des employés

  • SUBJECT_TOKEN_TYPE : définissez cette option sur l'une des valeurs suivantes :

    • urn:ietf:params:oauth:token-type:id_token pour les jetons d'ID OIDC
    • urn:ietf:params:oauth:token-type:saml2 pour les assertions SAML

  • EXTERNAL_SUBJECT_TOKEN: jeton émis par le fournisseur d'identité qui représente l'identité du compte principal pour lequel le jeton d'accès est demandé.

    Si vous avez configuré un fournisseur OIDC, le jeton doit être au format JWT.

  • BILLING_PROJECT_NUMBER : numéro ou ID du projet utilisé pour les quotas et la facturation. Le compte principal doit disposer de l'autorisation serviceusage.services.use sur ce projet.

La réponse est semblable à ce qui suit :

{
  "access_token": "ya29.dr.AaT61Tc6Ntv1ktbGkaQ9U_MQfiQw...",
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
  "token_type": "Bearer",
  "expires_in": 3600
}

Gérer les sessions à l'aide de gcloud CLI

Les jetons Google Cloud temporaires obtenus par la gcloud CLI à partir du point de terminaison Security Token Service expirent après un intervalle de temps spécifié. Lorsque le jeton est sur le point d'expirer, gcloud CLI inspecte le fichier d'identifiants que vous avez fourni, puis inspecte la validité des identifiants que vous avez reçus de votre fournisseur d'identité. Si vos identifiants sont toujours valides, la gcloud CLI obtient de manière transparente un nouveau jeton d'accès Google Cloud et votre session actuelle se poursuit sans interruption.

Si vos identifiants ont expiré, aucun nouveau jeton Google Cloud n'est émis et les appels que vous effectuez avec ces identifiants échouent. À ce stade, vous devez vous authentifier à nouveau.

Vous pouvez arrêter votre session en exécutant la commande suivante :

gcloud auth revoke

gcloud accepte plusieurs sessions utilisateur. Pour obtenir la liste des sessions, y compris la session actuellement active, exécutez la commande suivante:

gcloud auth list

La sortie de la commande ressemble à ceci :

Credentialed Accounts
ACTIVE    ACCOUNT
*         bola@example.com
          principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/kalani@example.com

Pour basculer vers une autre session et la définir comme active, exécutez la commande suivante :

gcloud config set account principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/SUBJECT_ID

Étape suivante