Configurer la fédération d'identité de charge de travail avec des certificats X.509

Ce guide explique comment utiliser la fédération d'identité de charge de travail avec des certificats X.509 émis par votre autorité de certification (CA) pour vous authentifier auprès de Trusted Cloud et accéder aux ressources Trusted Cloud .

Si vos charges de travail possèdent un certificat client mTLS, vous pouvez vous authentifier auprès deTrusted Cloud en enregistrant une ou plusieurs autorités de certification auprès de la fédération d'identité de charge de travail en tant qu'ancres de confiance. Vous pouvez également enregistrer des CA intermédiaires.

En utilisant la fédération d'identité de charge de travail, vous pouvez autoriser ces charges de travail à obtenir des identifiants Trusted Cloud de courte durée via une connexion TLS mutuel (mTLS). Les charges de travail peuvent utiliser ces identifiants éphémères pour accéder aux APITrusted Cloud .

Concepts

Les concepts de fédération basés sur les certificats X.509 incluent les éléments suivants :

• Une ancre de confiance est un certificat d'autorité de certification considéré comme la racine de confiance. Toutes les chaînes de certificats client doivent être chaînées à l'une des ancres de confiance.

• Une autorité de certification intermédiaire est un certificat d'autorité de certification facultatif qui permet de créer la chaîne de certificats client.

• Un magasin de confiance contient les certificats d'ancrage de confiance et les certificats d'autorité de certification intermédiaire utilisés pour valider la chaîne de certificats client. Une autorité de certification émet des certificats de confiance pour le client.

  Vous pouvez importer les types de certificats clients suivants dans le magasin de confiance :

  • Certificats émis par des autorités de certification tierces de votre choix
  • Certificats émis par vos autorités de certification privées
  • Les certificats signés, comme décrit dans la section Créer des certificats autosignés

Avant de commencer

Pour commencer à configurer la fédération d'identité de charge de travail, procédez comme suit :

1. In the Trusted Cloud console, on the project selector page, select or create a Trusted Cloud project.

   Go to project selector

Nous vous recommandons d' utiliser un projet dédié pour gérer les pools d'identités de charge de travail et les fournisseurs.

2. Verify that billing is enabled for your Trusted Cloud project.

3. Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

   Enable the APIs

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer la fédération d'identité de charge de travail, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le projet :

• Administrateur de pools Workload Identity (roles/iam.workloadIdentityPoolAdmin)
• Administrateur de compte de service (roles/iam.serviceAccountAdmin)

Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Le rôle de base IAM "Propriétaire" (roles/owner) inclut également des autorisations permettant de configurer la fédération d'identité. Les rôles de base ne doivent pas être attribués dans un environnement de production, mais ils peuvent être attribués dans un environnement de développement ou de test.

Créer un truststore

Cette section explique comment créer un magasin de confiance. Voici les grandes étapes à suivre :

• Générer des certificats autosignés
• Mettre en forme les certificats
• Créer le truststore

Générer des certificats autosignés

Cette section explique comment générer des clés et créer des certificats signés. Si vous avez déjà créé des certificats, vous pouvez ignorer cette section et passer à Mettre en forme les certificats.

Cette section utilise les commandes openssl pour créer un certificat racine et un certificat intermédiaire.

Pour générer un certificat racine et un certificat intermédiaire signé avec des champs keyUsage et extendedKeyUsage valides, procédez comme suit :

1. Créez un fichier de configuration openssl pour créer vos certificats de signature. Le fichier ressemble au minimum à ce qui suit, mais vous pouvez définir des champs supplémentaires si nécessaire.

   cat > example.cnf << EOF
   [req]
   distinguished_name = empty_distinguished_name
   [empty_distinguished_name]
   # Kept empty to allow setting via -subj command-line argument.
   [ca_exts]
   basicConstraints=critical,CA:TRUE
   keyUsage=keyCertSign
   extendedKeyUsage=clientAuth
   [leaf_exts]
   keyUsage=critical,Digital Signature, Key Encipherment
   basicConstraints=critical, CA:FALSE
   EOF
   

2. Créez le certificat racine.

   openssl req -x509 \
       -new -sha256 -newkey rsa:2048 -nodes \
       -days 3650 -subj '/CN=root' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout root.key -out root.cert
   

3. Créez la requête de signature pour le certificat intermédiaire.

   openssl req \
       -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=int' \
       -config example.cnf \
       -extensions ca_exts \
       -keyout int.key -out int.req
   

4. Créez le certificat intermédiaire.

   openssl x509 -req \
       -CAkey root.key -CA root.cert \
       -set_serial 1 \
       -days 3650 \
       -extfile example.cnf \
       -extensions ca_exts \
       -in int.req -out int.cert
   

5. Créez la requête de signature pour le certificat de feuille.

   openssl req -new -sha256 -newkey rsa:2048 -nodes \
       -subj '/CN=example' \
       -config example.cnf \
       -extensions leaf_exts \
       -keyout leaf.key -out leaf.req
   

6. Créez le certificat de feuille émis par l'intermédiaire.

   openssl x509 -req \
       -CAkey int.key -CA int.cert \
       -set_serial 1 -days 3650 \
       -extfile example.cnf \
       -extensions leaf_exts \
       -in leaf.req -out leaf.cert
   

Mettre en forme les certificats

Pour inclure de nouveaux certificats ou des certificats existants dans un truststore, définissez une mise en forme de ces certificats sur une seule ligne et stockez-les dans des variables d'environnement. Les certificats doivent être au format PEM. Pour mettre en forme les certificats et les stocker dans des variables d'environnement, procédez comme suit :

1. Enregistrez le certificat racine sous forme de chaîne sur une seule ligne.

   export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

2. Enregistrez un certificat intermédiaire sous forme de chaîne sur une seule ligne.

   export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')
   

Créer le truststore

Dans cette section, vous allez créer un truststore à l'aide d'un fichier au format YAML contenant vos ancres de confiance et vos autorités de certification intermédiaires.

Ce fichier contient le contenu du certificat à partir des variables d'environnement que vous avez créées dans Mettre en forme les certificats. Pour ajouter d'autres ancres de confiance, ajoutez d'autres entrées trustAnchors sous trustStore. Pour ajouter d'autres certificats d'autorité de certification intermédiaire, ajoutez d'autres entrées intermediateCas sous trustStore.

Pour créer le fichier du magasin de confiance, exécutez la commande suivante :

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

Définir un mappage et une condition d'attribut

Le certificat X.509 du client peut contenir plusieurs attributs. Vous devez sélectionner l'attribut que vous souhaitez utiliser comme identifiant de sujet en mappant google.subject dans Trusted Cloud à l'attribut de votre certificat. Par exemple, si l'attribut du certificat est le nom commun du sujet, le mappage se présente comme suit : google.subject=assertion.subject.dn.cn

Vous pouvez éventuellement mapper d'autres attributs. Vous pouvez ensuite faire référence à ces attributs lorsque vous autorisez l'accès aux ressources.

Vos mappages d'attributs peuvent utiliser les attributs du certificat client, y compris les suivants :

• serialNumberHex : numéro de série
• subject.dn.cn : nom commun du sujet
• subject.dn.o : nom de l'organisation concernée
• subject.dn.ou : dernière unité organisationnelle du sujet
• issuer.dn.cn : nom commun de l'émetteur
• issuer.dn.o : nom de l'organisation émettrice
• issuer.dn.ou : dernière unité organisationnelle de l'émetteur
• san.dns : premier nom DNS de l'autre nom de l'objet
• san.uri : premier URI du nom alternatif du sujet
• sha256Fingerprint : hachage SHA256 du certificat de feuille (Base64)

Vous devez mapper l'un de ces attributs sur google.subject pour identifier le sujet de manière unique. Pour vous protéger contre les menaces de spoofing, choisissez un attribut avec une valeur unique ne pouvant pas être modifiée. Par défaut, l'identifiant google.subject est défini sur le nom commun de l'objet du certificat client, assertion.subject.dn.cn.

Vous pouvez également définir une condition d'attribut. Les conditions d'attribut sont des expressions CEL qui peuvent vérifier les attributs d'assertion et les attributs cibles. Si la condition d'attribut renvoie true pour un identifiant donné, celui-ci est accepté. Dans le cas contraire, l'identifiant est rejeté.

Vous pouvez utiliser une condition d'attribut pour limiter les clients pouvant utiliser la fédération d'identité de charge de travail afin d'obtenir des jetons Trusted Cloudde courte durée.

Par exemple, la condition suivante restreint l'accès aux certificats client contenant l'ID SPIFFE spiffe://example/path :

assertion.san.uri=="spiffe://example/path"

Configurer la fédération d'identité de charge de travail

Cette section explique comment configurer un pool d'identités de charge de travail et un fournisseur de pools d'identités de charge de travail. Vous n'avez besoin de suivre cette procédure qu'une seule fois pour chaque magasin de confiance. Vous pouvez ensuite utiliser le même pool d'identités de charge de travail et le même fournisseur pour plusieurs charges de travail et sur plusieurs projets Trusted Cloud .

Créer le pool d'identités de charge de travail

1. Pour créer un pool d'identités de charge de travail, exécutez la commande suivante :

   gcloud iam workload-identity-pools create POOL_ID \
       --location="global" \
       --description="DESCRIPTION" \
       --display-name="DISPLAY_NAME"
   

   Remplacez les éléments suivants :

   • POOL_ID : ID unique du pool.
   • DISPLAY_NAME : nom du pool.
   • DESCRIPTION : description du pool que vous choisissez. Cette description apparaît lorsque vous accordez l'accès aux identités du pool.

Créer le fournisseur de pools d'identités de charge de travail

1. Pour ajouter un fournisseur de pools d'identités de charge de travail X.509, exécutez la commande suivante :

   gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
       --location=global \
       --workload-identity-pool="POOL_ID" \
       --trust-store-config-path="TRUST_STORE_CONFIG" \
       --attribute-mapping="MAPPINGS" \
       --attribute-condition="CONDITIONS"
   

   Remplacez les éléments suivants :

   • PROVIDER_ID : ID unique de fournisseur de pools d'identités de charge de travail de votre choix.
   • POOL_ID : ID du pool d'identités de charge de travail que vous avez créé précédemment.
   • TRUST_STORE_CONFIG : fichier YAML du magasin de confiance.
   • MAPPINGS : liste de mappages d'attributs séparés par des virgules que vous avez créés précédemment dans ce guide Par exemple, google.subject=assertion.subject.dn.cn.
   • CONDITIONS : facultatif. Condition d'attribut que vous avez créée précédemment dans ce guide. Supprimez le paramètre si vous n'avez pas de condition d'attribut.

Authentifier une charge de travail

Vous devez effectuer ces étapes une fois pour chaque charge de travail.

Autoriser votre charge de travail externe à accéder aux ressources Trusted Cloud

Pour autoriser votre charge de travail à accéder aux ressources Trusted Cloud , nous vous recommandons d'accorder un accès direct aux ressources au compte principal. Dans ce cas, le compte principal est l'utilisateur fédéré. Certains produits Trusted Cloud sont soumis à des limites d'API Google Cloud. Si votre charge de travail appelle un point de terminaison d'API présentant une limite, vous pouvez emprunter l'identité d'un compte de service. Dans ce cas, le compte principal est le compte de serviceTrusted Cloud , qui agit en tant qu'identité. Vous accordez l'accès au compte de service sur la ressource.

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"

Télécharger ou créer une configuration d'identifiants

Les bibliothèques clientes Cloud et gcloud CLI 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 fournit les informations suivantes :

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

De plus, un fichier de configuration de certificat est requis pour la fédération de certificats X.509. Ce fichier contient les chemins d'accès au certificat client X.509 et aux fichiers de clé privée.

Créez des fichiers de configuration d'identifiants et de certificats qui permettent à la bibliothèque d'obtenir des jetons d'accès à l'aide de certificats X.509.

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_PRIVATE_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

gcloud iam workload-identity-pools create-cred-config \
  projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --credential-cert-path=CLIENT_CERT_PATH \
    --credential-cert-private-key-path=CLIENT_KEY_PATH \
    --credential-cert-trust-chain-path=TRUST_CHAIN_PATH \
    --output-file=FILEPATH.json

Utiliser la configuration des identifiants pour accéder à Trusted Cloud

Pour permettre aux outils et aux bibliothèques clientes d'utiliser votre configuration d'identifiants, procédez comme suit. Pour en savoir plus sur les Identifiants par défaut de l'application, consultez Fonctionnement des Identifiants par défaut de l'application'application.

1. Initialisez une variable d'environnement GOOGLE_APPLICATION_CREDENTIALS et définissez-la sur le fichier de configuration des identifiants :

   Bash

     export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
     

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

   PowerShell

     $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
     

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

2. Assurez-vous que la bibliothèque cliente peut trouver le fichier de configuration du certificat. Le fichier de configuration du certificat se trouve à l'un des emplacements suivants :

   • Chemin d'accès par défaut de gcloud CLI :

     • Linux et macOS : ~/.config/gcloud/certificate_config.json

     • Windows : %APPDATA%\gcloud\certificate_config.json

   • Chemin d'accès défini dans la variable d'environnement GOOGLE_API_CERTIFICATE_CONFIG.

3. Utilisez les bibliothèques clientes Cloud suivantes compatibles avec la fédération d'identité de charge de travail avec des certificats X.509.

   Go

   Les bibliothèques clientes pour Go sont compatibles avec la fédération d'identité de charge de travail X.509 si elles utilisent la version 0.16.0 ou ultérieure du module cloud.google.com/go/auth et la version 0.189.0 du module google.golang.org/api.

   Pour vérifier quelle version de ces modules est utilisée par votre bibliothèque cliente, exécutez la commande suivante dans le répertoire contenant le fichier go.mod de votre module :

     go list -m cloud.google.com/go/auth
     go list -m cloud.google.com/api
   

   Python

   Les bibliothèques clientes pour Python sont compatibles avec la fédération d'identité de charge de travail X.509 si elles utilisent la version 2.39.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.

4. Si votre charge de travail s'exécute sur macOS, définissez CLOUDSDK_PYTHON_SITEPACKAGES=1 pour configurer gcloud CLI afin qu'elle utilise les bibliothèques Python en dehors de son répertoire d'installation.

5. Pour vous authentifier à l'aide de gcloud CLI, exécutez la commande suivante :

   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 charge de travail X.509 dans gcloud CLI est disponible dans les versions 519.0 et ultérieures de gcloud CLI.

Obtenir un jeton d'accès à l'aide d'une requête simple pour accéder à Trusted Cloud

Créer la chaîne de confiance

Cette étape vous explique comment créer la chaîne de confiance. Vous transmettez la chaîne de confiance dans le champ subject_token lorsque vous appelez le service de jetons de sécurité dans une requête simple.

Mettez en forme les certificats à inclure dans la chaîne sous forme de liste au format JSON, comme indiqué dans la RFC 7515. Le certificat de feuille utilisé pour le handshake mTLS doit être spécifié en premier. Chaque certificat du bundle doit être une chaîne encodée en base64.

1. Enregistrez le certificat de feuille et le certificat intermédiaire sous forme de chaînes encodées en base64.

   export LEAF_CERT=$(openssl x509 -in leaf.cert -out leaf.der -outform DER && cat leaf.der | openssl enc -base64 -A)
   

   export INTERMEDIATE_CERT=$(openssl x509 -in int.cert -out int.der -outform DER && cat int.der | openssl enc -base64 -A)
   

2. Créez une liste de chaînes au format JSON qui peut être transmise en tant que subject_token dans l'appel au service Security Token Service, plus loin dans ce document.

   export TRUST_CHAIN="[\\\"${LEAF_CERT}\\\", \\\"${INTERMEDIATE_CERT}\\\"]"
   

Obtenir un jeton d'accès

Pour obtenir le jeton d'accès, procédez comme suit :

1. Effectuez l'échange de jetons avec mTLS et le certificat client :

   curl --key CLIENT_CERT_KEY \
   --cert CLIENT_CERT \
   --request POST 'https://sts.mtls.s3nsapis.fr/v1/token' \
   --header "Content-Type: application/json" \
   --data-raw '{
       "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
       "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
       "audience": "WORKLOAD_IDENTITY_POOL_URI",
       "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
       "scope": "https://www.googleapis.com/auth/cloud-platform",
       "subject_token": "TRUST_CHAIN"
   }'
   

   Remplacez les éléments suivants :

   • CLIENT_CERT_KEY : clé privée du certificat client
   • CLIENT_CERT : certificat client.

   • WORKLOAD_IDENTITY_POOL_URI : URL du fournisseur du pool d'identités de charge de travail, au format suivant :

     //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

   • TRUST_CHAIN : la chaîne de confiance nécessaire pour valider le certificat d'entité finale doit au moins inclure CLIENT_CERT comme premier élément. Si vous avez suivi les instructions de la section Mise en forme des certificats, remplacez TRUST_CHAIN par '"${TRUST_CHAIN}"'.

2. Utilisez le jeton d'accès du porteur généré à l'étape précédente pour accéder aux ressourcesTrusted Cloud . Par exemple :

   curl -X GET 'https://storage.s3nsapis.fr/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
   

Limites

Le tableau suivant répertorie les limites.

Étapes suivantes

• Apprenez-en plus sur la fédération d'identité de charge de travail.
• Découvrez les bonnes pratiques d'utilisation de la fédération d'identité de charge de travail.
• Découvrez comment vous pouvez gérer les pools d'identités de charge de travail et les fournisseurs.