doc-locale/fr-fr/ci/secrets/convert-to-id-tokens.md
{{< details >}}
{{< /details >}}
[!note] À partir de Vault 1.17, la connexion JWT auth nécessite des audiences liées sur le rôle lorsque le JWT contient une revendication
aud. La revendicationaudpeut être une chaîne unique ou une liste de chaînes.
Ce tutoriel montre comment convertir votre configuration de secrets CI/CD existante pour utiliser les jetons d'ID.
Les variables CI/CD CI_JOB_JWT sont dépréciées, mais la mise à jour vers les jetons d'ID nécessite des modifications de configuration importantes pour fonctionner avec Vault. Si vous avez plus d'une poignée de jobs, tout convertir en une seule fois est une tâche intimidante.
Il n'existe pas de méthode standard unique pour migrer vers les jetons d'ID, c'est pourquoi ce tutoriel présente deux variantes pour convertir vos secrets CI/CD existants. Choisissez la méthode la plus adaptée à votre cas d'utilisation :
iss vers les rôles pour la fenêtre de migration
Ce tutoriel suppose que vous êtes familier avec GitLab CI/CD et Vault.
Pour suivre ce tutoriel, vous devez disposer des éléments suivants :
CI_JOB_JWT.Dans les exemples suivants, remplacez :
vault.example.com par l'URL de votre serveur Vault.gitlab.example.com par l'URL de votre instance GitLab.jwt ou jwt_v2 par vos noms de méthodes d'authentification.Cette méthode crée une seconde méthode d'authentification JWT en parallèle de celle existante en cours d'utilisation. Ensuite, tous les rôles Vault utilisés pour l'intégration GitLab sont recréés dans cette nouvelle méthode d'authentification.
Dans le cadre de la transition de CI_JOB_JWT vers les jetons d'ID, vous devez mettre à jour bound_issuer dans Vault pour inclure https:// :
$ vault write auth/jwt/config \
oidc_discovery_url="https://gitlab.example.com" \
bound_issuer="https://gitlab.example.com"
Après avoir effectué cette modification, les jobs qui utilisent CI_JOB_JWT commencent à échouer.
Vous pouvez créer plusieurs chemins d'authentification dans Vault, ce qui vous permet de passer aux jetons d'ID par projet et par job sans interruption.
Configurez un nouveau chemin d'authentification avec le nom jwt_v2, exécutez :
vault auth enable -path jwt_v2 jwt
Vous pouvez choisir un nom différent, mais le reste de ces exemples suppose que vous avez utilisé jwt_v2, donc mettez à jour les exemples selon vos besoins.
Configurez le nouveau chemin d'authentification pour votre instance :
$ vault write auth/jwt_v2/config \
oidc_discovery_url="https://gitlab.example.com" \
bound_issuer="https://gitlab.example.com"
Les rôles sont liés à un chemin d'authentification spécifique, vous devez donc ajouter de nouveaux rôles pour chaque job. Le paramètre bound_audiences pour le rôle est obligatoire si le JWT contient une audience et doit correspondre à au moins une des revendications aud associées du JWT.
Recréez le rôle pour l'environnement de staging nommé myproject-staging :
$ vault write auth/jwt_v2/role/myproject-staging - <<EOF
{
"role_type": "jwt",
"policies": ["myproject-staging"],
"token_explicit_max_ttl": 60,
"user_claim": "user_email",
"bound_audiences": ["https://vault.example.com"],
"bound_claims": {
"project_id": "22",
"ref": "master",
"ref_type": "branch"
}
}
EOF
Recréez le rôle pour la production nommé myproject-production :
$ vault write auth/jwt_v2/role/myproject-production - <<EOF
{
"role_type": "jwt",
"policies": ["myproject-production"],
"token_explicit_max_ttl": 60,
"user_claim": "user_email",
"bound_audiences": ["https://vault.example.com"],
"bound_claims_type": "glob",
"bound_claims": {
"project_id": "22",
"ref_protected": "true",
"ref_type": "branch",
"ref": "auto-deploy-*"
}
}
EOF
Vous devez uniquement mettre à jour jwt en jwt_v2 dans la commande vault, ne modifiez pas role_type à l'intérieur du rôle.
iss vers les rôles pour la fenêtre de migration {#method-b-move-iss-claim-to-roles-for-migration-window}Cette méthode ne nécessite pas que les administrateurs Vault créent une seconde méthode d'authentification JWT et recréent tous les rôles liés à GitLab.
bound_issuers à chaque rôle {#add-bound_issuers-claim-map-to-each-role}Vault n'autorise pas plusieurs revendications iss au niveau de la méthode d'authentification JWT, car la directive bound_issuer à ce niveau n'accepte qu'une seule valeur. Cependant, plusieurs revendications peuvent être configurées au niveau du rôle en utilisant la directive de configuration de carte bound_claims.
Avec cette méthode, vous pouvez fournir à Vault plusieurs options pour la validation de la revendication iss. Cela prend en charge la revendication de nom d'hôte de l'instance GitLab préfixée par https:// qui accompagne les id_tokens, ainsi que l'ancienne revendication sans préfixe.
Pour ajouter la configuration bound_claims aux rôles requis, exécutez :
$ vault write auth/jwt/role/myproject-staging - <<EOF
{
"role_type": "jwt",
"policies": ["myproject-staging"],
"token_explicit_max_ttl": 60,
"user_claim": "user_email",
"bound_audiences": ["https://vault.example.com"],
"bound_claims": {
"iss": [
"https://gitlab.example.com",
"gitlab.example.com"
],
"project_id": "22",
"ref": "master",
"ref_type": "branch"
}
}
EOF
Vous n'avez pas besoin de modifier les configurations de rôles existantes, à l'exception de la section bound_claims. Veillez à ajouter la configuration iss comme indiqué précédemment, pour garantir que Vault accepte la revendication iss avec et sans préfixe pour ce rôle.
Vous devez appliquer cette modification à tous les rôles JWT utilisés pour l'intégration GitLab avant de passer à l'étape suivante.
Vous pouvez annuler la migration de la validation de la revendication iss depuis la méthode d'authentification vers les rôles si vous le souhaitez, une fois que tous les projets ont été migrés et que vous n'avez plus besoin d'une prise en charge parallèle de CI_JOB_JWT et des jetons d'ID.
bound_issuers de la méthode d'authentification {#remove-bound_issuers-claim-from-auth-method}Une fois que tous les rôles ont été mis à jour avec les revendications bound_claims.iss, vous pouvez supprimer la configuration au niveau de la méthode d'authentification pour cette validation :
$ vault write auth/jwt/config \
oidc_discovery_url="https://gitlab.example.com" \
bound_issuer=""
Définir la directive bound_issuer sur une chaîne vide supprime la validation de l'émetteur au niveau de la méthode d'authentification. Cependant, étant donné que cette validation se situe désormais au niveau du rôle, la configuration reste sécurisée.
Vault dispose de deux moteurs de secrets KV différents et la version que vous utilisez a un impact sur la manière dont vous définissez les secrets en CI/CD.
Consultez l'article Which Version is my Vault KV Mount? sur le portail d'assistance de HashiCorp pour vérifier votre serveur Vault.
De plus, si nécessaire, vous pouvez consulter la documentation CI/CD pour :
Les exemples suivants montrent comment obtenir le mot de passe de la base de données de staging écrit dans le champ password dans secret/myproject/staging/db.
La valeur de la variable CI/CD VAULT_AUTH_PATH dépend de la méthode de migration que vous avez utilisée :
jwt_v2.iss vers les rôles pour la fenêtre de migration) : Utilisez jwt.Le mot-clé secrets:vault utilise par défaut la version v2 du montage KV, vous devez donc configurer explicitement le job pour utiliser le moteur v1 :
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://vault.example.com
secrets:
PASSWORD:
vault:
engine:
name: kv-v1
path: secret
field: password
path: myproject/staging/db
file: false
VAULT_SERVER_URL et VAULT_AUTH_PATH peuvent être définis en tant que variables CI/CD de projet ou de groupe, si vous le préférez.
secrets:file est défini sur false car les jetons d'ID placent les secrets dans un fichier par défaut et il doit fonctionner comme une variable CI/CD ordinaire pour correspondre à l'ancien comportement.
Il existe deux formats que vous pouvez utiliser pour le moteur v2.
Format long :
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://vault.example.com
secrets:
PASSWORD:
vault:
engine:
name: kv-v2
path: secret
field: password
path: myproject/staging/db
file: false
Il s'agit du même exemple que pour le moteur v1, mais secrets:vault:engine:name: est défini sur kv-v2 pour correspondre au moteur.
Vous pouvez également utiliser un format court :
job:
variables:
VAULT_SERVER_URL: https://vault.example.com
VAULT_AUTH_PATH: jwt_v2 # or "jwt" if you used method B
VAULT_AUTH_ROLE: myproject-staging
id_tokens:
VAULT_ID_TOKEN:
aud: https://vault.example.com
secrets:
PASSWORD:
vault: myproject/staging/db/password@secret
file: false
Une fois que vous avez commité la configuration CI/CD mise à jour, vos jobs récupèrent les secrets avec des jetons d'ID. Félicitations !
Si vous avez migré tous les projets pour récupérer les secrets avec des jetons d'ID et utilisé la méthode B pour la migration, il est désormais possible de déplacer la validation de la revendication iss vers la configuration de la méthode d'authentification si vous le souhaitez.