Obtenir des identifiants éphémères avec la fédération d'identité

Ce guide explique comment obtenir des identifiants éphémères en utilisant un pool d'identités de charges de travail et un fournisseur, en procédant comme suit :

  1. Obtenez des identifiants auprès du fournisseur d'identité approuvé.
  2. Échangez les identifiants contre un jeton du service de jetons de sécurité.
  3. Utilisez le jeton du service de jetons de sécurité pour emprunter l'identité d'un compte de service et obtenir un jeton d'accès Google éphémère.

À l'aide des jetons d'accès Google éphémères, vous pouvez ensuite accéder à toutes les ressources Google Cloud auxquelles le compte de service a été autorisé à accéder.

Avant de commencer

  1. Activer les API IAM, Security Token Service, and Service Account Credentials.

    Activer les API

  2. Fédérez avec un fournisseur d'identité externe en créant un pool et un fournisseur d'identité de charge de travail

  3. Créez un compte de service pour lequel vous souhaitez que les identités externes empruntent l'identité.

  4. Accordez au compte de service l'accès aux ressources auxquelles vous souhaitez que les identités externes accèdent.

Accorder aux identités externes l'autorisation d'emprunter l'identité d'un compte de service

Pour autoriser les identités externes à emprunter l'identité d'un compte de service, vous devez leur accorder le rôle d'utilisateur Workload Identity (roles/iam.workloadIdentityUser) sur le compte de service. Vous pouvez accorder le rôle à une identité externe spécifique ou à plusieurs identités externes :

  • Pour une identité externe spécifique, écrivez une condition d'attribut qui vérifie l'attribut google.subject.
  • Pour un groupe d'identités externes, créez une condition d'attribut qui vérifie l'attribut google.groups ou un attribut personnalisé attribute.NAME.
  • Pour toutes les identités externes du pool d'identités de charge de travail, vous n'utilisez pas de condition d'attribut.

Console

  1. Dans Cloud Console, accédez à la page Pools d'identités de charge de travail.

    Accéder aux pools d'identité de charge de travail

  2. Recherchez le pool d'identités de charge de travail que vous souhaitez mettre à jour, puis cliquez dessus.

  3. Cliquez sur Accorder l'accès.

  4. Dans la liste déroulante Compte de service, sélectionnez le compte de service dont les identités externes seront empruntées.

  5. Choisissez les identités du pool qui peuvent emprunter l'identité du compte de service :

    • Pour n'autoriser que les identités spécifiques du pool d'identités de charge de travail à emprunter l'identité du compte de service, sélectionnez Uniquement les identités correspondant au filtre.

      Dans la liste déroulante Nom de l'attribut, sélectionnez l'attribut sur lequel vous souhaitez appliquer le filtre.

      Dans le champ Valeur de l'attribut, saisissez la valeur attendue de l'attribut.

      Par exemple, si vous utilisez un mappage d'attributs google.subject=assertion.sub, définissez le nom de l'attribut sur subject et la valeur d'attributsur la valeur de la revendication sub dans les jetons émis par votre fournisseur d'identité externe.

    • Pour autoriser toutes les identités externes du pool d'identités de charge de travail à emprunter l'identité du compte de service, sélectionnez Toutes les identités du pool.

  6. Cliquez sur Enregistrer.

  7. Cliquez sur Ignorer.

gcloud

  1. Créez un identifiant pour les identités externes :

    • Une identité externe spécifique :

      principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
      
    • Un groupe d'identités externes :

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
      
    • Toutes les identités externes ayant un certain attribut :

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
      
    • Toutes les identités externes d'un pool d'identités de charge de travail :

      principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
      

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID de pool du pool d'identités de charge de travail
    • SUBJECT : valeur attendue pour l'attribut que vous avez mappé sur google.subject.
    • GROUP : valeur attendue pour l'attribut que vous avez mappé sur google.groups.
    • ATTRIBUTE_NAME : nom d'un attribut personnalisé dans votre mappage d'attributs

    Pour obtenir le numéro de projet de votre projet actuel, vous pouvez utiliser la commande suivante :

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
    
  2. Attribuez le rôle Utilisateur Workload Identity (roles/iam.workloadIdentityUser) au compte de service :

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
        --role=roles/iam.workloadIdentityUser \
        --member="MEMBER_ID"
    

    Remplacez les valeurs suivantes :

    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • MEMBER_ID : identifiant de membre que vous avez identifié à l'étape précédente

S'authentifier à l'aide de bibliothèques clientes, de la CLI gcloud ou de Terraform

Les bibliothèques clientes Cloud, gcloud CLI et Terraform peuvent obtenir automatiquement des identifiants externes et les utiliser pour emprunter l'identité d'un compte de service. Pour permettre aux bibliothèques et aux outils de mener ce processus à son terme, vous devez fournir un fichier de configuration des identifiants. Ce fichier définit les éléments suivants :

  • Où obtenir des identifiants externes
  • Quel pool d'identités de charge de travail et quel fournisseur utiliser
  • À quel compte de service emprunter l'identité

La manière dont les bibliothèques clientes utilisent les fichiers de configuration des identifiants dépend de votre fournisseur d'identité externe :

AWS

Les bibliothèques clientes obtiennent automatiquement des identifiants temporaires à partir des métadonnées d'instance EC2.

Azure

Les bibliothèques clientes obtiennent automatiquement des jetons d'accès à partir du service de métadonnées d'instance Azure (IMDS).

GitHub Actions

Étant donné que les paramètres requis pour obtenir un jeton d'ID GitHub varient pour chaque exécution de workflow, vous ne pouvez pas utiliser de fichier de configuration des identifiants statique dans un workflow GitHub Actions.

Utilisez l'action google-github-actions/auth pour générer automatiquement un fichier de configuration d'identifiants pendant l'exécution du workflow. Les bibliothèques clientes et les outils tels que terraform peuvent ensuite utiliser ce fichier de configuration des identifiants pour obtenir automatiquement des identifiants Google.

OIDC

Les bibliothèques clientes obtiennent des identifiants à partir d'un fichier local ou d'une URL HTTP :

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

OIDC (AD FS)

Les bibliothèques clientes peuvent obtenir des identifiants à partir d'un fichier local ou d'une URL HTTP, mais ne sont pas directement compatibles avec l'authentification Windows intégrée (IWA). Pour obtenir un jeton d'accès pour l'utilisateur connecté et le stocker dans un fichier local, exécutez la commande PowerShell suivante :

(Invoke-RestMethod `
    -Uri "https://ADFS_DOMAIN/adfs/oauth2/token/" `
    -Method POST `
    -Body @{
        client_id = 'CLIENT_ID'
        grant_type = 'client_credentials'
        scope = 'openid'
        resource = 'RELYING_PARTY_ID'
        use_windows_client_authentication = 'true'
        } `
    -UseDefaultCredentials).access_token | Out-File -Encoding ASCII TOKEN_FILEPATH

Remplacez les valeurs suivantes :

  • ADFS_DOMAIN : nom de domaine public du serveur AD FS de la ferme.
  • CLIENT_ID : ID client de l'enregistrement de l'application dans AD FS.
  • RELYING_PARTY_ID : identifiant de partie de confiance que vous avez utilisé lors de la création d'une application d'API Web pour le pool de d'identité de charge de travail dans AD FS.
  • TOKEN_FILEPATH : chemin d'accès à un fichier temporaire dans lequel enregistrer le jeton AD FS. Assurez-vous que le fichier est stocké dans un emplacement où seuls les utilisateurs autorisés peuvent lire le contenu.

Étant donné que les identifiants Google de courte durée ne sont valides que pendant une durée limitée (une heure par défaut), vous devez réexécuter régulièrement cette commande.

SAML

Les bibliothèques clientes obtiennent des identifiants à partir d'un fichier local ou d'une URL HTTP :

  • Identifiants basés sur un 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.
  • Identifiants basés sur une 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 une assertion SAML encodée en base64.

Suivez ces étapes pour permettre aux bibliothèques clientes ou à Terraform d'utiliser la fédération d'identité de charge de travail pour l'authentification :

  1. Créez un fichier de configuration des identifiants :

    Console

    Téléchargez un fichier de configuration des identifiants dans Cloud Console :

    1. Dans Cloud Console, accédez à la page Pools d'identités de charge de travail.

      Accéder aux pools d'identité de charge de travail

    2. Recherchez le pool d'identités de charge de travail contenant le fournisseur d'identité que vous souhaitez utiliser, puis cliquez dessus.

    3. Sélectionnez Comptes de service connectés.

    4. Recherchez le compte de service que vous souhaitez utiliser, puis cliquez sur Télécharger.

    5. Dans la boîte de dialogue Configurer votre application, sélectionnez le fournisseur qui contient les identités externes qui emprunteront l'identité du compte de service.

    6. Spécifiez les paramètres supplémentaires suivants :

      AWS

      Aucun paramètre supplémentaire n'est requis.

      Azure

      Chemin d'accès à la ressource : URI d'ID application de l'application Azure

      OIDC

      Chemin d'accès au jeton OIDC : chemin d'accès au fichier local ou URL à partir de laquelle obtenir les identifiants.

      Type de format : format du fichier ou de la réponse d'URL à partir duquel le jeton d'ID est récupéré.

      Nom du champ de jeton d'objet : champ de la réponse contenant le jeton (si le type de format est json).

      SAML

      Chemin d'accès à l'assertion SAML : chemin d'accès au fichier local ou URL à partir de laquelle obtenir les identifiants.

      Type de format : format du fichier ou de la réponse d'URL à partir duquel l'assertion est récupérée.

      Nom du champ d'assertion : champ de la réponse contenant l'assertion (si le type de format est json).

    7. Sélectionnez Télécharger la configuration pour télécharger le fichier de configuration des identifiants, puis cliquez sur Fermer.

    gcloud

    Créez un fichier de configuration des identifiants à l'aide de gcloud iam workload-identity-pools create-cred-config :

    AWS

    Créez un fichier de configuration des identifiants autorisant la bibliothèque à obtenir un jeton d'accès à partir des métadonnées d'instance EC2 :

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --aws \
        --output-file=FILEPATH.json
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • FILEPATH : fichier dans lequel enregistrer la configuration

    Azure

    Créez un fichier de configuration des identifiants autorisant la bibliothèque à obtenir un jeton d'accès à partir du service de métadonnées d'instance Azure (IMDS) :

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --azure \
        --app-id-uri APPLICATION_ID_URI \
        --output-file=FILEPATH.json
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • APPLICATION_ID_URI : URI d'ID application de l'application Azure
    • FILEPATH : fichier dans lequel enregistrer la configuration

    OIDC

    Pour utiliser les identifiants provenant d'un fichier, utilisez l'option --credential-source-file :

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --output-file=FILEPATH.json \
        --credential-source-file=TOKEN_FILEPATH \
        --credential-source-type=SOURCE_TYPE \
        --credential-source-field-name=FIELD_NAME
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • FILEPATH : fichier dans lequel enregistrer la configuration
    • TOKEN_FILEPATH : chemin d'accès à l'emplacement où sont stockés les jetons d'ID OIDC
    • SOURCE_TYPE : format du fichier de jeton d'ID OIDC, défini sur text (par défaut) ou json
    • FIELD_NAME : champ dans le fichier texte contenant le jeton (si SOURCE_TYPE est json)

    Pour utiliser des identifiants provenant d'une URL, utilisez l'option --credential-source-url :

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --output-file=FILEPATH.json \
        --credential-source-url="TOKEN_URL" \
        --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
        --credential-source-type=source_type \
        --credential-source-field-name=field_name
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • FILEPATH : fichier dans lequel enregistrer la configuration
    • TOKEN_URL : URL à partir de laquelle récupérer le jeton d'ID OIDC
    • KEY_n, VALUE_n : en-têtes personnalisés à inclure dans la requête HTTP vers TOKEN_URL
    • SOURCE_TYPE : format du fichier de jeton d'ID OIDC, défini sur text (par défaut) ou json
    • FIELD_NAME : champ dans le fichier texte contenant le jeton (si SOURCE_TYPE est json)

    OIDC (AD FS)

    Créez un fichier de configuration des identifiants qui permet à la bibliothèque de lire le jeton d'accès AD FS à partir du fichier temporaire :

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --output-file=FILEPATH.json \
        --credential-source-file=TOKEN_FILEPATH \
        --credential-source-type=text
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • FILEPATH : fichier dans lequel enregistrer la configuration
    • TOKEN_FILEPATH : chemin d'accès au fichier temporaire contenant le jeton AD FS

    SAML

    Pour utiliser les identifiants provenant d'un fichier, utilisez l'option --credential-source-file :

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --output-file=FILEPATH.json \
        --credential-source-file=TOKEN_FILEPATH \
        --credential-source-type=SOURCE_TYPE \
        --credential-source-field-name=FIELD_NAME \
        --subject-token-type=urn:ietf:params:oauth:token-type:saml2
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • FILEPATH : fichier dans lequel enregistrer la configuration
    • TOKEN_FILEPATH : chemin d'accès à l'emplacement où sont stockées les assertions SAML
    • SOURCE_TYPE : format du fichier d'assertion SAML, défini sur text (par défaut) ou json
    • FIELD_NAME : champ dans le fichier texte contenant l'assertion (si SOURCE_TYPE est json)

    Pour utiliser des identifiants provenant d'une URL, utilisez l'option --credential-source-url :

    gcloud iam workload-identity-pools create-cred-config \
        projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
        --service-account=SERVICE_ACCOUNT_EMAIL \
        --output-file=FILEPATH.json \
        --credential-source-url="TOKEN_URL" \
        --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
        --credential-source-type=source_type \
        --credential-source-field-name=field_name
        --subject-token-type=urn:ietf:params:oauth:token-type:saml2
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service
    • FILEPATH : fichier dans lequel enregistrer la configuration
    • TOKEN_URL : URL à partir de laquelle récupérer l'assertion SAML
    • KEY_n, VALUE_n : en-têtes personnalisés à inclure dans la requête HTTP vers TOKEN_URL
    • SOURCE_TYPE : format du fichier d'assertion SAML, défini sur text (par défaut) ou json
    • FIELD_NAME : champ dans le fichier texte contenant l'assertion (si SOURCE_TYPE est json)

    GitHub Actions

    Modifiez votre fichier YAML GitHub Actions et ajoutez les éléments suivants :

    • Autorisez la tâche à récupérer un jeton d'ID GitHub en ajoutant la configuration suivante :

      permissions:
        id-token: write
        contents: read
      
    • Ajoutez une étape pour créer un fichier de configuration des identifiants :

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v0.3.1'
        with:
          create_credentials_file: true
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'
      

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service

    Exemple :

    jobs:
      build:
        # Allow the job to fetch a GitHub ID token
        permissions:
          id-token: write
          contents: read
    
        runs-on: ubuntu-latest
    
        steps:
          - uses: actions/checkout@v2
    
          - id: 'auth'
            name: 'Authenticate to Google Cloud'
            uses: 'google-github-actions/auth@v0.3.1'
            with:
              create_credentials_file: true
              workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
              service_account: 'SERVICE_ACCOUNT_EMAIL'
    
  2. Initialisez une variable d'environnement GOOGLE_APPLICATION_CREDENTIALS et pointez-la vers le fichier de configuration des identifiants :

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
      
    FILEPATH est le chemin d'accès relatif au fichier de configuration des identifiants.

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
      
    FILEPATH est le chemin d'accès relatif au fichier de configuration des identifiants.

    Fichier YAML GitHub Actions

    L'action google-github-actions/auth initialise automatiquement GOOGLE_APPLICATION_CREDENTIALS.
  3. Utilisez une bibliothèque cliente compatible avec la fédération d'identité de charge de travail et capable de trouver automatiquement les identifiants :

    C++

    La plupart des bibliothèques clientes Google Cloud pour C++ sont compatibles avec la fédération d'identité à 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.36.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és.

    Go

    Les bibliothèques clientes pour Go sont compatibles avec la fédération d'identité si elles utilisent la version 0.0.0-20210218202405-ba52d332ba99 ou une version ultérieure du module golang.org/x/oauth2.

    Pour vérifier quelle version de ce module est utilisée par votre bibliothèque cliente, exécutez les commandes suivantes :

    cd $GOPATH/src/cloud.google.com/go
    go list -m golang.org/x/oauth2
    

    Java

    Les bibliothèques clientes pour Java sont compatibles avec la fédération d'identité si elles utilisent la version 0.24.0 ou une version ultérieure de l'artefact com.google.auth:google-auth-library-oauth2-http.

    Pour vérifier la version de cet artefact utilisée par votre bibliothèque cliente, exécutez la commande Maven suivante dans le répertoire de votre application :

    mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
    

    Node.js

    Les bibliothèques clientes pour Node.js sont compatibles avec la fédération d'identité si elles utilisent la version 7.0.2 ou ultérieure du package google-auth-library.

    Pour vérifier la version de ce package utilisée par votre bibliothèque cliente, exécutez la commande suivante dans le répertoire de votre application :

    npm list google-auth-library
    

    Lorsque vous créez un objet GoogleAuth, vous pouvez spécifier un ID de projet ou autoriser GoogleAuth à le trouver automatiquement. Pour trouver automatiquement l'ID du projet, le compte de service dans le fichier de configuration doit disposer du rôle de visiteur (roles/browser) ou d'un rôle avec des autorisations équivalentes sur votre projet. Pour en savoir plus, consultez la section README du package google-auth-library.

    Python

    Les bibliothèques clientes pour Python sont compatibles avec la fédération d'identité si elles utilisent la version 1.27.0 ou ultérieure du package google-auth.

    Pour vérifier la version de ce package utilisée par votre bibliothèque cliente, exécutez la commande suivante dans l'environnement dans lequel le package est installé :

    pip show google-auth
    

    Pour spécifier un ID de projet pour le client d'authentification, vous pouvez définir la variable d'environnement GOOGLE_CLOUD_PROJECT ou autoriser le client à trouver automatiquement l'ID du projet. Pour trouver automatiquement l'ID du projet, le compte de service dans le fichier de configuration doit disposer du rôle de visiteur (roles/browser) ou d'un rôle avec des autorisations équivalentes sur votre projet. Pour en savoir plus, consultez le guide de l'utilisateur du package google-auth.

    gcloud

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

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

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

    La fédération d'identité de charge de travail est disponible dans les versions 363.0.0 et ultérieures de Google Cloud CLI.

    Terraform

    Le fournisseur Google Cloud est compatible avec la fédération d'identité de charge de travail si vous utilisez la version 3.61.0 ou ultérieure :

    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = "~> 3.61.0"
        }
      }
    }
    

    gsutil

    Pour vous authentifier à l'aide de la fédération d'identité de charge de travail, 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.

S'authentifier à l'aide de l'API REST

Si vous ne pouvez pas utiliser les bibliothèques clientes, vous pouvez suivre les étapes ci-dessous pour permettre à une identité externe d'obtenir un jeton d'accès éphémère à l'aide de l'API REST :

  1. Obtenez des identifiants auprès de votre fournisseur d'identité externe :

    AWS

    Créez un document JSON contenant les informations que vous devez normalement inclure dans une requête adressée au point de terminaison GetCallerIdentity() AWS, y compris une signature de requête valide.

    La fédération d'identité de charge de travail fait référence à ce document JSON sous la forme d'un jeton GetCallerIdentity. Le jeton permet à la fédération d'identité de charge de travail de valider l'identité sans révéler la clé d'accès secrète AWS.

    Un jeton GetCallerIdentity ressemble à ce qui suit :

    {
      "url": "https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
      "method": "POST",
      "headers": [
        {
          "key": "Authorization",
          "value" : "AWS4-HMAC-SHA256 Credential=AKIASOZTBDV4D7ABCDEDF/20200228/us-east-1/sts/aws4_request, SignedHeaders=host;x-amz-date,Signature=abcedefdfedfd"
        },
        {
          "key": "host",
          "value": "sts.amazonaws.com"
        },
        {
          "key": "x-amz-date",
          "value": "20200228T225005Z"
        },
        {
          "key": "x-goog-cloud-target-resource",
          "value": "//iam.googleapis.com/projects/12345678/locations/global/workloadIdentityPools/my-pool/providers/my-aws-provider"
        },
        {
          "key": "x-amz-security-token",
          "value": "GizFWJTqYX...xJ55YoJ8E9HNU="
        }
      ]
    }
    

    Le jeton contient les champs suivants :

    • url : URL du point de terminaison AWS STS pour GetCallerIdentity(), avec le corps d'une requête GetCallerIdentity() standard ajoutée en tant que paramètres de requête. Par exemple, https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15. Les points de terminaison régionaux sont également acceptés.
    • method : méthode de requête HTTP : POST.
    • headers : en-têtes de requête HTTP, qui doivent inclure les éléments suivants :
      • Authorization : signature de la requête.
      • host : nom d'hôte du champ url, par exemple sts.amazonaws.com.
      • x-amz-date : heure d'envoi de la requête, formatée en tant que chaîne ISO 8601 au format de base. Cette valeur est généralement définie sur l'heure actuelle et permet d'éviter les attaques de répétitions.
      • x-goog-cloud-target-resource : nom complet de la ressource du fournisseur d'identité sans préfixe https:. Exemple :
        //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
        
      • x-amz-security-token : jeton de session Requis uniquement si vous utilisez des identifiants de sécurité temporaires.

    L'exemple suivant crée un jeton GetCallerIdentity encodé au format URL. Extrayez le jeton encodé au format URL pour une utilisation ultérieure. Il crée également un jeton lisible à titre indicatif :

    import json
    import urllib
    
    import boto3
    from botocore.auth import SigV4Auth
    from botocore.awsrequest import AWSRequest
    
    def create_token_aws(project_number: str, pool_id: str, provider_id: str) -> None:
        # Prepare a GetCallerIdentity request.
        request = AWSRequest(
            method="POST",
            url="https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15",
            headers={
                "Host": "sts.amazonaws.com",
                "x-goog-cloud-target-resource": f"//iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/providers/{provider_id}"
            })
    
        # Set the session credentials and Sign the request.
        # get_credentials loads the required credentials as environment variables.
        # Refer:
        # https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
        SigV4Auth(boto3.Session().get_credentials(), "sts", "us-east-1").add_auth(request)
    
        # Create token from signed request.
        token = {
            "url": request.url,
            "method": request.method,
            "headers": []
        }
        for key, value in request.headers.items():
            token["headers"].append({"key": key, "value": value})
    
        # The token lets workload identity federation verify the identity without revealing the AWS secret access key.
        print("Token:\n%s" % json.dumps(token, indent=2, sort_keys=True))
        print("URL encoded token:\n%s" % urllib.parse.quote(json.dumps(token)))
    
    def main():
        # TODO(Developer): Replace the below credentials.
        # project_number: Google Project number (not the project id)
        project_number = "my-project-number"
        pool_id = "my-pool-id"
        provider_id = "my-provider-id"
    
        create_token_aws(project_number, pool_id, provider_id)
    
    if __name__ == "__main__":
        main()

    Initialisez les variables suivantes :

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:aws:token-type:aws4_request"
    SUBJECT_TOKEN=TOKEN
    

    PowerShell

    $SubjectTokenType = "urn:ietf:params:aws:token-type:aws4_request"
    $SubjectToken = "TOKEN"
    

    TOKEN correspond au jeton GetCallerIdentity encodé au format URL qui a été généré par le script ci-dessus.

    Azure

    Connectez-vous à une VM Azure dotée d'une identité gérée assignée et obtenez un jeton d'accès auprès du service de métadonnées d'instance Azure (IMDS) :

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:jwt"
    SUBJECT_TOKEN=$(curl \
      "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
      -H "Metadata: true" | jq -r .access_token)
    echo $SUBJECT_TOKEN
    

    Cette commande utilise l'outil jq. jq est disponible par défaut dans Cloud Shell.

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = (Invoke-RestMethod `
      -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
      -Headers @{Metadata="true"}).access_token
    Write-Host $SubjectToken
    

    APP_ID_URI est l'URI d'ID application de l'application que vous avez configurée pour la fédération d'identité de charge de travail.

    GitHub Actions

    Utilisez google-github-actions/auth pour obtenir un jeton d'ID GitHub et l'échanger contre un jeton d'accès de courte durée :

    • Autorisez la tâche à récupérer un jeton d'ID GitHub en ajoutant la configuration suivante :

      permissions:
        id-token: write
        contents: read
      
    • Ajoutez une étape pour générer un jeton d'accès et le rendre disponible dans une variable ${{ steps.auth.outputs.access_token }} :

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v0.3.1'
        with:
          token_format: 'access_token'
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'
      

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
    • SERVICE_ACCOUNT_EMAIL : adresse e-mail du compte de service

    Exemple :

    jobs:
      build:
        # Allow the job to fetch a GitHub ID token
        permissions:
          id-token: write
          contents: read
    
        runs-on: ubuntu-latest
    
        steps:
          - uses: actions/checkout@v2
    
          - id: 'auth'
            name: 'Authenticate to Google Cloud'
            uses: 'google-github-actions/auth@v0.3.1'
            with:
              token_format: 'access_token'
              workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
              service_account: 'SERVICE_ACCOUNT_EMAIL'
    

    Ignorez les étapes suivantes.

    OIDC

    Obtenez un jeton de votre fournisseur d'identité externe et initialisez les variables suivantes :

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:jwt"
    SUBJECT_TOKEN=TOKEN
    

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = "TOKEN"
    

    TOKEN est le jeton émis par votre fournisseur d'identité externe.

    OIDC (AD FS)

    Exécutez les commandes PowerShell suivantes pour vous authentifier auprès d'AD FS à l'aide de l'authentification Windows intégrée et obtenir un jeton d'accès :

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = (Invoke-RestMethod `
        -Uri "https://ADFS_DOMAIN/adfs/oauth2/token/" `
        -Method POST `
        -Body @{
            client_id = 'CLIENT_ID'
            grant_type = 'client_credentials'
            scope = 'openid'
            resource = 'RELYING_PARTY_ID'
            use_windows_client_authentication = 'true'
            } `
        -Credential USER).access_token
    

    Remplacez les valeurs suivantes :

    • ADFS_DOMAIN : nom de domaine public du serveur ou de la ferme AD FS.
    • CLIENT_ID : ID client de l'enregistrement de l'application dans AD FS.
    • RELYING_PARTY_ID : identifiant de partie de confiance que vous avez utilisé lors de la création d'une application d'API Web pour le pool de d'identité de charge de travail dans AD FS. Vous n'avez besoin de ce paramètre que si vous utilisez un identifiant de partie de confiance personnalisé.
    • USER : utilisateur Active Directory à utiliser pour l'authentification Windows intégrée. Vous pouvez également remplacer -Credential par -UseDefaultCredentials pour utiliser vos identifiants actuels.

    SAML

    Obtenez une assertion auprès de votre fournisseur d'identité externe et initialisez une variable :

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:saml2"
    SUBJECT_TOKEN=ASSERTION
    

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:saml2"
    $SubjectToken = "ASSERTION"
    

    ASSERTION est l'assertion encodée en base64 émise par votre fournisseur d'identité externe.

  2. Utilisez l'API Security Token Service pour échanger l'identifiant contre un jeton d'accès éphémère :

    Bash

    STS_TOKEN=$(curl -0 -X POST https://sts.googleapis.com/v1/token \
        -H 'Content-Type: text/json; charset=utf-8' \
        -d @- <<EOF | jq -r .access_token
        {
            "audience"           : "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
            "grantType"          : "urn:ietf:params:oauth:grant-type:token-exchange",
            "requestedTokenType" : "urn:ietf:params:oauth:token-type:access_token",
            "scope"              : "https://www.googleapis.com/auth/cloud-platform",
            "subjectTokenType"   : "$SUBJECT_TOKEN_TYPE",
            "subjectToken"       : "$SUBJECT_TOKEN"
        }
    EOF)
    echo $STS_TOKEN
    

    PowerShell

    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
    $StsToken = (Invoke-RestMethod `
        -Method POST `
        -Uri "https://sts.googleapis.com/v1/token" `
        -ContentType "application/json" `
        -Body (@{
            "audience"           = "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID"
            "grantType"          = "urn:ietf:params:oauth:grant-type:token-exchange"
            "requestedTokenType" = "urn:ietf:params:oauth:token-type:access_token"
            "scope"              = "https://www.googleapis.com/auth/cloud-platform"
            "subjectTokenType"   = $SubjectTokenType
            "subjectToken"       = $SubjectToken
        } | ConvertTo-Json)).access_token
    Write-Host $StsToken
    

    Remplacez les valeurs suivantes :

    • PROJECT_NUMBER : numéro de projet du projet contenant le pool d'identités de charge de travail
    • POOL_ID : ID du pool d'identités de charge de travail
    • PROVIDER_ID : ID du fournisseur du pool d'identités de charge de travail
  3. Utilisez le jeton du service de jetons de sécurité pour appeler la méthode generateAccessToken de l'API Service Account Credentials IAM afin d'obtenir un jeton d'accès :

    Bash

    ACCESS_TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken \
        -H "Content-Type: text/json; charset=utf-8" \
        -H "Authorization: Bearer $STS_TOKEN" \
        -d @- <<EOF | jq -r .accessToken
        {
            "scope": [ "https://www.googleapis.com/auth/cloud-platform" ]
        }
    EOF)
    echo $ACCESS_TOKEN
    

    PowerShell

    $AccessToken = (Invoke-RestMethod `
        -Method POST `
        -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken" `
        -Headers @{ "Authorization" = "Bearer $StsToken" } `
        -ContentType "application/json" `
        -Body (@{
            "scope" = , "https://www.googleapis.com/auth/cloud-platform"
        } | ConvertTo-Json)).accessToken
    Write-Host $AccessToken
    

    Remplacez SERVICE_ACCOUNT_EMAIL par l'adresse e-mail du compte de service.

Validation des identifiants externes

L'API Security Token Service utilise les étapes suivantes pour valider les identifiants émis par un fournisseur d'identité externe.

AWS

  • Vérifiez les champs suivants dans le jeton GetCallerIdentity :

    • La valeur d'url doit être un URI HTTPS avec un nom d'hôte égal à sts.amazonaws.com (ou un sous-domaine régional) et aucun port. Les paramètres de requête exacts suivants sont présents :
      • action = getcalleridentity
      • version (valeur quelconque)
    • method est défini sur POST.
    • Les valeurs headers suivantes exactes sont présentes : x-amz-date, authorization, host, x-goog-cloud-target-resource, x-amz-security-token (facultatif)
      • La valeur de x-goog-cloud-target-resource est le nom de ressource du fournisseur de pools d'identité de charge de travail.
      • La valeur de x-amz-date ne peut pas être plus de 15 minutes dans le passé, et ne peut pas être dans l'avenir.
  • Exécutez la requête sur sts.amazonaws.com ou sur le sous-domaine régional approprié, puis vérifiez que le résultat aboutit et que l'ID de compte AWS correspond à l'ID de compte configuré pour le fournisseur de pools d'identités de charge de travail.

Azure

Les jetons Azure sont des jetons OIDC et sont validés de la même manière que les jetons OIDC.

GitHub Actions

Les jetons GitHub sont des jetons OIDC et sont validés de la même manière que les jetons OIDC.

OIDC

Les jetons OIDC sont validés conformément à la spécification OIDC. Plus précisément, Security Token Service exécute les étapes suivantes :

  • Validation du document de découverte et de la signature :

    • Créez l'URI du point de terminaison de découverte en ajoutant /.well-known/openid-configuration à l'émetteur configuré dans le fournisseur de pools d'identités de charge de travail et récupérez le document de découverte OIDC.
    • Vérifiez que la revendication issuer du document de découverte est égale à l'émetteur configuré dans le fournisseur de pools d'identités de charge de travail. STS dispose d'une logique de validation personnalisée pour les émetteurs suivants qui ne sont pas conformes à la spécification OIDC :
      • Oracle Cloud (https://*.identity.oraclecloud.com)
      • Microsoft (https://login.microsoftonline.com/common/v2.0, https://login.microsoftonline.com/consumers/v2.0, https://login.microsoftonline.com/organizations/v2.0)
    • Récupérez le jeu de clés Web JSON (JWKS) à partir de jwks_uri répertorié dans le document de découverte.
    • Si une revendication kid est présente dans l'en-tête JWT, validez la signature JWT à l'aide de la clé des JWKS avec l'ID de clé correspondant, ou refusez le jeton si aucune clé correspondante n'est trouvée. Si aucune revendication kid n'est présente dans l'en-tête JWT, essayez de valider la signature JWT à l'aide de chaque clé répertoriée dans le JWKS. La signature est acceptée si une clé peut être utilisée pour la valider.
  • Validation de l'en-tête :

    • Une revendication alg doit être présente et être égale à RS256 ou ES256.
  • Validation de la charge utile :

    • Une revendication iss doit être présente et être égale à la revendication issuer du document de découverte. STS dispose d'une logique de validation personnalisée pour les émetteurs suivants qui ne sont pas conformes à la spécification OIDC :
      • Oracle Cloud (https://*.identity.oraclecloud.com)
      • Microsoft (https://login.microsoftonline.com/common/v2.0, https://login.microsoftonline.com/consumers/v2.0, https://login.microsoftonline.com/organizations/v2.0)
    • Une revendication aud doit être présente et être égale à https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID. Si des alternatives allowed_audiences sont configurées, la revendication aud doit alors être égale à l'une de ces valeurs.
    • Une revendication exp doit être présente et être dans l'avenir.
    • Une revendication iat doit être présente et être dans le passé.
    • La valeur de exp doit être supérieure de 24 heures au maximum à la valeur de iat.

SAML

  • Décodez en base64 et extrayez (unmarshal) les identifiants SAML dans un objet Response ou Assertion.
  • Si les identifiants SAML sont extraits (unmarshal) dans un objet Response, vérifiez les points suivants :

    • La valeur StatusCode de la réponse est égale à urn:oasis:names:tc:SAML:2.0:status:Success.
    • Une seule valeur Assertion est présente.
    • Au moins l'un des éléments Response ou Assertion est signé. Pour chaque signature, essayez de valider la signature à l'aide de chaque certificat X.509 configuré dans le fournisseur de pools d'identités de charge de travail. La signature est acceptée si l'un des certificats permet de la valider.
    • Si la réponse Response est signé, l'élément Issuer de la réponse Response doit être présent et égal à l'ID d'entité du fournisseur d'identité SAML configuré dans le fournisseur de pools d'identités de charge de travail. Vérifiez également que la valeur de Format est omise ou égale à urn:oasis:names:tc:SAML:2.0:nameid-format:entity.
  • Si les identifiants SAML sont extraits (unmarshal) dans un objet Assertion, vérifiez les points suivants :

    • L'Assertion est signée. Pour chaque signature, essayez de valider la signature à l'aide de chaque certificat X.509 configuré dans le fournisseur de pools d'identités de charge de travail. La signature est acceptée si l'un des certificats permet de la valider.
  • Que l'identifiant SAML ait été extrait (unmarshal) dans un objet Response ou Assertion, vérifiez que l'élément Assertion contient les attributs suivants :

    • Un Issuer doit être présent et correspondre à l'ID d'entité du fournisseur d'identité SAML configuré dans le fournisseur de pools d'identités de charge de travail. La valeur Format de l'Issuer est omise ou est égale à urn:oasis:names:tc:SAML:2.0:nameid-format:entity.
    • Un IssueInstant doit être présent et remonter à moins d'une heure dans le passé.
    • Un Subject doit être présent et contenir les attributs suivants :
      • L'élément NameID doit être présent.
      • Un seul élément SubjectConfirmation doit être présent et avoir une valeur Method égale à urn:oasis:names:tc:SAML:2.0:cm:bearer. Un NotOnOrAfter doit être présent dans l'élément SubjectConfirmationData et être dans l'avenir.
      • Aucun élément NotBefore n'est présent.
    • Un Conditions doit être présent et contenir les attributs suivants :
      • Si un NotBefore est présent, il doit être dans le passé.
      • Si un NotOnOrAfter est présent, il doit être dans l'avenir.
      • Au moins un AudienceRestriction doit être présent. Tous les AudienceRestriction doivent contenir un élément Audience dont la valeur est égale au nom de ressource du fournisseur de pools d'identités de charge de travail
    • Au moins un AuthnStatement doit être présent.
    • Si des valeurs SessionNotOnOrAfter sont présentes, elles doivent toutes être dans l'avenir.

Outre les étapes de validation spécifiques au protocole décrites ci-dessus, l'API Security Token Service vérifie également que la condition d'attribut est remplie.

Étape suivante