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 et auxquelles on vous a accordé l'accès.

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 :

  2. Vous devez connaître l'ID de votre pool de personnel ou l'ID de votre fournisseur.

  3. 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).

  4. Enable the IAM and Security Token Service APIs.

    Enable the APIs

  5. 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/PROVIDER_ID \
    --output-file=LOGIN_CONFIG_FILE

Remplacez les éléments suivants :

  • WORKFORCE_POOL_ID : ID du pool de personnel
  • PROVIDER_ID : ID du fournisseur
  • LOGIN_CONFIG_FILE : chemin d'accès au fichier de configuration 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 que vous avez créé précédemment dans ce guide. 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/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

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/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 de personnel
  • PROVIDER_ID : ID du fournisseur
  • 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/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

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 le 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/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 de personnel.
  • PROVIDER_ID : ID du fournisseur.
  • 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/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

Les jetons sont chargés à partir d'un 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 une réponse positive, à 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 renseignent 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. Toujours présent.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE : type de jeton d'objet attendu. Toujours présent.
  • 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/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 de personnel.
  • PROVIDER_ID : ID du fournisseur.
  • 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/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

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, que ce soit pour des identifiants exécutables interactifs ou non.

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

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/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 de personnel.
  • PROVIDER_ID : ID du fournisseur.
  • 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 : (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/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",
    }
  }
}

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/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 de personnel.
  • PROVIDER_ID : ID du fournisseur.
  • 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 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 :

gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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 de personnel.
  • PROVIDER_ID : ID du fournisseur.
  • 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 permission 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 une réponse positive, à 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 renseignent 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. Toujours présent.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE : type de jeton d'objet attendu. Toujours présent.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE : emplacement du fichier de sortie issu de la configuration des identifiants. Présent uniquement s'il est spécifié 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/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 de personnel.
  • PROVIDER_ID : ID du fournisseur.
  • 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 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 3PI 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 son existence avant d'exécuter le fichier 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/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

Un exécutable interagit avec l'utilisateur via la ligne de commande.

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

  • EXECUTABLE_OUTPUT_FILE : (obligatoire) chemin d'accès au fichier qui fournit les identifiants générés par l'exécutable.
  • EXECUTABLE_TIMEOUT : (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. L'absence de l'élément expiration_time sera traitée comme le signal que l'exécutable sera de toute façon exécuté.

L'exécutable doit rapporter toutes les erreurs dans executable-output-file 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.

Les champs de retour de la commande d'une exécution réussie sont exactement les mêmes avec les résultats d'identifiants exécutables standards ci-dessus.

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

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/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 de personnel.
  • PROVIDER_ID : ID du fournisseur.
  • 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 : (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 a défini 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>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 les CLI (gcloud, bq, gsutil) ne sont actuellement pas compatibles avec les types d'identifiants basés sur un exécutable.

Pour les flux sans interface graphique, gcloud utilise automatiquement le champ d'application suivant : https://www.googleapis.com/auth/cloud-platform. gcloud 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 :

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 au fichier de configuration des identifiants.

La fédération d'identité de personnel dans bq est disponible dans les versions 390.0.0 et ultérieures de la 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.

La bibliothèque cliente Cloud Storage pour C++ utilise l'API REST, et non gRPC. Elle n'est donc pas compatible 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

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

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

Go

Les bibliothèques clientes pour Go sont compatibles avec la fédération d'identité de personnel si elles utilisent 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)
}

gsutil

Pour vous authentifier à l'aide de la fédération d'identité de personnel, appliquez l'une des méthodes suivantes :

Lorsque vous utilisez gsutil conjointement avec gcloud, connectez-vous comme d'habitude :

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

Si vous utilisez gsutil en tant qu'application de ligne de commande autonome, modifiez le fichier .boto pour inclure la section suivante :

[Credentials]
gs_external_account_file = FILEPATH

FILEPATH dans les deux cas est le chemin d'accès au fichier de configuration des identifiants.

La fédération d'identité de personnel dans gsutil est disponible dans les versions 379.0.0 et ultérieures de Google Cloud CLI.

Java

Les bibliothèques clientes pour Java sont compatibles avec la fédération d'identité de personnel si elles utilisent 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 pour Node.js sont compatibles avec la fédération d'identité de personnel. Vous devez utiliser 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é 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 plus d'informations, 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 pour Python sont compatibles avec la fédération d'identité de personnel si elles utilisent 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 ci-dessus, la valeur project peut être None si la bibliothèque ne parvient pas à la détecter automatiquement. Vous pouvez la transmettre explicitement lorsque vous utilisez une instance de service (comme dans l'exemple du client de stockage) ou la définir 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.

curl https://sts.googleapis.com/v1/token \
    --data-urlencode "audience=//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/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.
  • PROVIDER_ID : ID du fournisseur

  • 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é. Remarque : Si vous utilisez OIDC, le jeton est 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 gcloud à 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 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, gcloud 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