Vault : authentification userpass et AppRole

Avant d'accéder à un secret dans Vault, un client doit prouver son identité. Vault propose plusieurs méthodes d'authentification selon le contexte : utilisateurs humains, applications, pipelines CI/CD, workloads cloud.

Ce guide couvre les deux méthodes les plus courantes :

• userpass : authentification par identifiant/mot de passe (utilisateurs)
• AppRole : authentification pour applications et CI/CD

Ce que vous allez apprendre

• Activer une méthode d'authentification et créer un compte userpass
• Configurer un rôle AppRole avec role_id et secret_id à usage unique
• Intégrer l'authentification dans un pipeline CI/CD sans exposer de secret durable
• Protéger la distribution du secret_id avec le response wrapping
• Diagnostiquer les refus d'authentification les plus courants

Prérequis

Installer Vault Installation et premier démarrage

Policies Comprendre les policies d'accès

• Vault installé et démarré
• Accès admin (root token ou policy admin)

Userpass : pour les utilisateurs humains

La méthode userpass est simple : identifiant + mot de passe. Elle convient aux développeurs qui accèdent à Vault via la CLI ou l'UI.

Activer userpass

Aucune méthode d'authentification n'est active à l'installation, à l'exception de la méthode token. Activer userpass monte un nouveau backend sur le chemin auth/userpass/ : c'est ce chemin, et non le nom de la méthode, que vous retrouverez dans toutes les commandes et dans les policies. Retenez-le, la plupart des erreurs request path is not valid viennent d'un chemin mal recopié.

vault auth enable userpass

Sortie :

Success! Enabled userpass auth method at: userpass/

Créer un utilisateur

La création d'un compte est une simple écriture sous auth/userpass/users/, le dernier segment du chemin devenant le nom d'utilisateur. Deux réflexes dès maintenant : ne tapez jamais le mot de passe en clair dans l'historique du shell (préférez une variable d'environnement ou l'entrée interactive), et attribuez toujours une policy explicite, faute de quoi le compte n'héritera que de default et ne pourra lire aucun secret métier.

vault write auth/userpass/users/alice \
    password="SecurePassword123!" \
    policies="dev-policy"

Policies

Chaque utilisateur est associé à une ou plusieurs policies qui définissent ses permissions. Consultez le guide Policies.

Se connecter

L'utilisateur alice peut maintenant se connecter :

vault login -method=userpass \
    username=alice \
    password="SecurePassword123!"

Sortie :

Success! You are now authenticated.

Key                    Value
---                    -----
token                  hvs.CAESICpTptPYxzwJISnFYQQRZzz7ftYL...
token_accessor         ORgCVUVANPcCkzgF8oKs9ZRc
token_duration         768h
token_renewable        true
token_policies         ["default" "dev-policy"]
identity_policies      []
policies               ["default" "dev-policy"]
token_meta_username    alice

Le token retourné est automatiquement stocké dans ~/.vault-token pour les commandes suivantes.

Gérer les utilisateurs

Ces quatre commandes couvrent le cycle de vie complet d'un compte. Un piège mérite d'être signalé : vault write remplace les champs fournis sans toucher aux autres, donc réécrire les policies ne change pas le mot de passe, et inversement. Sachez enfin que supprimer un utilisateur ne révoque pas les tokens déjà émis en son nom ; pour couper l'accès immédiatement, il faut révoquer les tokens via leur accessor ou révoquer le chemin d'authentification.

# Lister les utilisateurs
vault list auth/userpass/users/

# Modifier le mot de passe
vault write auth/userpass/users/alice password="NewPassword456!"

# Modifier les policies
vault write auth/userpass/users/alice policies="dev-policy,staging-readonly"

# Supprimer un utilisateur
vault delete auth/userpass/users/alice

Configuration du token

Vous pouvez personnaliser la durée de vie et le comportement des tokens :

vault write auth/userpass/users/bob \
    password="BobPassword123!" \
    policies="dev-policy" \
    token_ttl="8h" \
    token_max_ttl="24h" \
    token_bound_cidrs="10.0.0.0/8"

Paramètre	Description
token_ttl	Durée de vie initiale du token
token_max_ttl	Durée maximale (même après renouvellement)
token_bound_cidrs	IPs autorisées à utiliser le token

Glissez pour voir

AppRole : pour les applications et CI/CD

AppRole est la méthode recommandée pour les applications et pipelines. Elle utilise deux éléments :

• role_id : identité de l'application (stable, comme un username)
• secret_id : credential éphémère (comme un mot de passe temporaire)

Pourquoi AppRole ?

La différence n'est pas une question de robustesse du mot de passe, mais de durée de vie du credential. Un mot de passe userpass reste valable tant que personne ne le change, donc une fuite dans un log de build reste exploitable des mois plus tard. Un secret_id expire au bout de quelques minutes et peut être limité à une seule utilisation, ce qui réduit la fenêtre d'exploitation à presque rien.

Userpass	AppRole
Mot de passe stable	secret_id éphémère et usage unique possible
Difficile à automatiser	Conçu pour l'automatisation
Pas de restriction d'usage	Limites sur nombre d'utilisations, TTL, CIDR

Glissez pour voir

Activer AppRole

Comme pour userpass, la méthode se monte sur son propre chemin, auth/approle/. Elle peut cohabiter sans conflit avec les autres méthodes déjà activées : Vault autorise plusieurs backends d'authentification en parallèle, chacun émettant ses propres tokens avec ses propres policies.

vault auth enable approle

Créer un rôle

Un rôle AppRole décrit une application, pas une personne : il fixe à l'avance les policies attribuées et les limites de durée. Les paramètres préfixés secret_id_ gouvernent le credential, ceux préfixés token_ gouvernent le token obtenu après connexion. Le champ policies accepté ci-dessous est un alias historique de token_policies, que Vault renvoie sous les deux noms lors d'un vault read auth/approle/role/my-webapp.

vault write auth/approle/role/my-webapp \
    secret_id_ttl=10m \
    token_num_uses=10 \
    token_ttl=20m \
    token_max_ttl=30m \
    secret_id_num_uses=1 \
    policies="webapp-policy"

Paramètre	Description	Valeur recommandée
secret_id_ttl	Durée de validité du secret_id	10-30 minutes
secret_id_num_uses	Nombre d'utilisations du secret_id	1 (usage unique)
token_ttl	Durée de vie du token obtenu	Selon besoin applicatif
token_num_uses	Nombre d'utilisations du token	0 (illimité) ou selon besoin

Glissez pour voir

secret_id_num_uses=1

En production, utilisez secret_id_num_uses=1. Chaque secret_id ne sert qu'une fois, ce qui limite l'impact en cas de fuite.

Obtenir les credentials

Récupérer le role_id

Le role_id est stable et peut être stocké dans la configuration de l'application :

vault read auth/approle/role/my-webapp/role-id

Sortie :

Key        Value
---        -----
role_id    d922482a-36c8-45fa-df77-c793b2980f51

Générer un secret_id

Le secret_id est éphémère et doit être généré à chaque déploiement :

vault write -f auth/approle/role/my-webapp/secret-id

Sortie :

Key                   Value
---                   -----
secret_id             aab71b03-aeeb-6965-dd97-73d5f9e30f38
secret_id_accessor    67eabeab-e4b4-12f3-8fde-4ab79b5c7027
secret_id_num_uses    1
secret_id_ttl         10m

Se connecter avec AppRole

L'application utilise role_id + secret_id pour obtenir un token :

vault write auth/approle/login \
    role_id="d922482a-36c8-45fa-df77-c793b2980f51" \
    secret_id="aab71b03-aeeb-6965-dd97-73d5f9e30f38"

Sortie :

Key                     Value
---                     -----
token                   hvs.CAESIG...
token_accessor          ABC123...
token_duration          20m
token_renewable         true
token_policies          ["default" "webapp-policy"]

Workflow CI/CD recommandé

Voici comment intégrer AppRole dans un pipeline CI/CD :

1. Pré-déploiement : un administrateur génère le secret_id et le passe au pipeline (variable secrète CI/CD)

2. Pipeline : récupère le role_id (stocké en config) et le secret_id (variable secrète)

3. Login : le pipeline fait vault write auth/approle/login pour obtenir un token

4. Accès secrets : le pipeline utilise le token pour lire les secrets nécessaires

5. Fin : le token expire automatiquement

Le script ci-dessous matérialise les étapes 3 et 4. Trois précautions y sont volontaires : set -euo pipefail interrompt le job dès qu'une commande échoue plutôt que de continuer avec un token vide, -field=token évite d'imprimer la réponse complète de Vault dans les logs, et le token n'est jamais écrit sur disque. Pensez également à désactiver l'écho de commandes du runner (set +x) si votre CI l'active par défaut.

#!/bin/bash
set -euo pipefail

# Variables d'environnement (injectées par le CI/CD)
# VAULT_ADDR, VAULT_ROLE_ID, VAULT_SECRET_ID

# Obtenir le token
VAULT_TOKEN=$(vault write -field=token auth/approle/login \
    role_id="$VAULT_ROLE_ID" \
    secret_id="$VAULT_SECRET_ID")

export VAULT_TOKEN

# Lire les secrets
DB_PASSWORD=$(vault kv get -field=password secret/apps/webapp/database)

# Utiliser le secret : passé par l'environnement, il n'apparaît ni dans la
# ligne de commande visible par ps, ni dans l'historique du shell
export PGPASSWORD="$DB_PASSWORD"
psql -h db.internal -U webapp -d webapp -c 'SELECT 1'

echo "Deploying with DB access..."

Wrapped secret_id : sécurité renforcée

Pour éviter que le secret_id transite en clair, utilisez le response wrapping :

# Générer un secret_id wrappé (valide 5 minutes)
vault write -wrap-ttl=5m -f auth/approle/role/my-webapp/secret-id

Sortie :

Key                              Value
---                              -----
wrapping_token:                  hvs.CAESIOe9fg2saB1v44rzYlQfct_IGzpgk2n7ZvUUI--jao_m
wrapping_accessor:               IRSMBlNVmDshiL3JV3DXck9W
wrapping_token_ttl:              5m
wrapping_token_creation_time:    2026-03-16 14:30:00.413673165 +0000 UTC
wrapping_token_creation_path:    auth/approle/role/my-webapp/secret-id
wrapped_accessor:                1ead00ec-0101-5042-7c51-71d6fa953ab4

Le secret_id n'apparaît nulle part dans cette sortie : c'est tout l'intérêt. Notez aussi que les clés se terminent ici par un deux-points, contrairement aux autres réponses de Vault, parce que ce bloc décrit l'enveloppe et non la donnée elle-même.

Le CI/CD reçoit un wrapping_token au lieu du secret_id. Il doit le "unwrapper" :

VAULT_TOKEN="<wrapping_token>" vault unwrap

Avantage du wrapping

Si le wrapping_token est intercepté et utilisé par un attaquant, le secret_id n'est plus disponible pour l'application légitime → attaque détectée.

Comparatif des méthodes

Ces trois méthodes ne s'excluent pas, elles couvrent des populations différentes sur le même cluster Vault. La ligne à regarder en premier est Rotation : c'est elle qui détermine ce qu'un attaquant peut faire d'un credential récupéré dans un log ou une variable d'environnement. La colonne Token désigne ici l'usage direct d'un token émis à la main, pratique pour un dépannage ponctuel mais impossible à faire tourner proprement.

Aspect	Userpass	AppRole	Token
Cible	Humains	Applications	Automation simple
Facilité	Très simple	Moyen	Simple
Sécurité	Moyenne	Haute	Faible
Rotation	Manuelle	Automatisable	Manuelle
CI/CD	Non recommandé	Recommandé	Acceptable court-terme

Glissez pour voir

Dépannage

Les messages d'erreur de Vault restent volontairement vagues pour ne pas renseigner un attaquant sur ce qui existe côté serveur : invalid username or password est renvoyé aussi bien pour un compte inexistant que pour un mauvais mot de passe. Commencez donc toujours par vérifier le chemin de la méthode avec vault auth list, avant de suspecter le credential lui-même.

Symptôme	Cause probable	Solution
invalid username or password	Credentials incorrects	Vérifier username/password
invalid role_id	Rôle AppRole inexistant	vault read auth/approle/role/<nom>
secret_id is invalid	secret_id expiré ou déjà utilisé	Générer un nouveau secret_id
permission denied on login	Auth method non activée	vault auth enable <method>
request path is not valid	Path incorrect	Vérifier le path (auth/userpass/...)

Glissez pour voir

À retenir

1. userpass : simple, pour les utilisateurs humains (CLI, UI)
2. AppRole : sécurisé, pour applications et CI/CD
3. role_id = identité stable, secret_id = credential éphémère
4. En prod : secret_id_num_uses=1 pour usage unique
5. Response wrapping : protection supplémentaire pour les pipelines
6. Chaque utilisateur/application = policies spécifiques (moindre privilège)

Prochaines étapes

Policies Définir les permissions avec HCL

Secrets KV Stocker vos premiers secrets

Concepts Vault Architecture et vue d'ensemble

×

📖 Voir la documentation →