Vault PKI : générer des certificats TLS automatiquement

Vault peut agir comme autorité de certification (CA) interne pour émettre des certificats TLS à la demande. Plus de certificats manuels, plus d'oublis de renouvellement : chaque service demande son certificat quand il en a besoin.

Ce guide couvre la création d'une PKI avec CA intermédiaire dans Vault, les méthodes d'émission (issue vs sign), et le cycle de vie des certificats.

Root CA hors de Vault en production

Ce guide montre une Root CA générée dans Vault pour l'apprentissage.

En production, la recommandation HashiCorp est de maintenir la Root CA hors de Vault, sur une machine déconnectée ou un HSM, et de n'importer dans Vault qu'une CA intermédiaire signée par cette Root externe.

Avantages :

• La Root n'est jamais exposée au réseau
• Compromission de Vault ≠ compromission de la Root
• Révocation et rotation de l'intermédiaire sans toucher à la Root

Si vous suivez ce guide pour la prod, sautez l'étape 1 et commencez par importer une intermédiaire signée par votre Root externe.

Prérequis

Introduction Vault Concepts et architecture

Policies Contrôler l'accès à l'émission

• Vault installé et démarré
• Accès admin pour configurer le moteur PKI

Architecture PKI recommandée

Une PKI bien conçue utilise deux niveaux de CA minimum :

Niveau	Durée typique	Localisation	Usage
Root CA	10-20 ans	Hors Vault (offline)	Signe uniquement les intermédiaires
Intermediate CA	1-5 ans	Dans Vault (pki_int)	Émet les certificats services
Certificats leaf	30-90 jours	Services	mTLS, HTTPS, API

Glissez pour voir

Pourquoi une intermédiaire ?

Si la CA intermédiaire est compromise, vous pouvez la révoquer et en créer une nouvelle sans modifier la Root CA. Les clients font confiance à la Root, qui reste intacte.

Étape 1 : créer la Root CA (démo uniquement)

Production

En production, cette étape se fait hors de Vault : vous générez la Root sur une machine air-gapped, puis vous signez la CSR de l'intermédiaire avec cette Root externe. Passez directement à l'étape 2 si vous avez déjà une Root externe.

Activer le moteur PKI pour la Root

vault secrets enable -path=pki pki

Configurer la durée maximale

vault secrets tune -max-lease-ttl=87600h pki

87600h = 10 ans. La Root CA doit avoir une longue durée de vie.

Générer le certificat Root

vault write -field=certificate pki/root/generate/internal \
    common_name="My Organization Root CA" \
    issuer_name="root-2026" \
    ttl=87600h > root_ca.crt

Configurer les URLs de publication

vault write pki/config/urls \
    issuing_certificates="$VAULT_ADDR/v1/pki/ca" \
    crl_distribution_points="$VAULT_ADDR/v1/pki/crl"

URLs accessibles

Ces URLs doivent être réellement accessibles par tous les clients qui valident les certificats. Si $VAULT_ADDR est une IP interne, les clients externes ne pourront pas vérifier la chaîne ni la CRL.

En production, utilisez des noms DNS publics ou internes accessibles depuis tous les environnements concernés.

Étape 2 : créer la CA intermédiaire

Activer un second moteur PKI

vault secrets enable -path=pki_int pki

Configurer la durée

vault secrets tune -max-lease-ttl=43800h pki_int

43800h = 5 ans maximum pour les certificats émis par cette CA.

Générer une CSR (Certificate Signing Request)

vault write -format=json pki_int/intermediate/generate/internal \
    common_name="My Organization Intermediate CA" \
    issuer_name="intermediate-2026" \
    | jq -r '.data.csr' > intermediate.csr

Signer la CSR avec la Root CA

Root dans Vault (démo)

vault write -format=json pki/root/sign-intermediate \
    issuer_ref="root-2026" \
    csr=@intermediate.csr \
    format=pem_bundle \
    ttl=43800h \
    | jq -r '.data.certificate' > intermediate.crt

Root externe (production)

Sur votre machine air-gapped avec la Root CA :

# Copier intermediate.csr sur la machine air-gapped
# Signer avec openssl ou cfssl selon votre setup

openssl ca -config /path/to/root-ca.conf \
    -extensions v3_intermediate_ca \
    -days 1825 -notext -md sha256 \
    -in intermediate.csr \
    -out intermediate.crt

# Copier intermediate.crt de retour vers Vault

Importer le certificat signé

vault write pki_int/intermediate/set-signed certificate=@intermediate.crt

Configurer les URLs de l'intermédiaire

vault write pki_int/config/urls \
    issuing_certificates="$VAULT_ADDR/v1/pki_int/ca" \
    crl_distribution_points="$VAULT_ADDR/v1/pki_int/crl"

Multi-issuer et rotation d'autorité

Depuis Vault 1.11+, un même mount PKI peut gérer plusieurs issuers (plusieurs CA). Cela permet :

• Rotation d'autorité : créer un nouvel issuer avant d'expirer l'ancien
• Période de transition : les deux issuers coexistent pendant le sunset
• Révocation par issuer : révoquer un issuer sans toucher aux autres

Lister les issuers

vault list pki_int/issuers

Définir l'issuer par défaut

vault write pki_int/config/issuers default="intermediate-2026"

Rotation d'issuer (aperçu)

1. Générer une nouvelle CSR : pki_int/intermediate/generate/internal
2. La faire signer par la Root
3. Importer : pki_int/intermediate/set-signed
4. Mettre à jour le défaut : pki_int/config/issuers
5. Laisser l'ancien issuer le temps que ses certificats expirent
6. Supprimer l'ancien issuer si besoin

CRL partagée

Les issuers d'un même mount partagent la même CRL. Chaque issuer peut avoir sa propre AIA (Authority Information Access), mais la CRL est commune.

Étape 3 : créer un rôle d'émission

Un rôle définit les paramètres des certificats émis : domaines autorisés, durée, type de clé.

vault write pki_int/roles/webserver \
    allowed_domains="example.com" \
    allow_subdomains=true \
    allow_bare_domains=false \
    max_ttl=2160h \
    ttl=720h \
    key_type="rsa" \
    key_bits=2048 \
    require_cn=true \
    allow_ip_sans=false \
    allow_localhost=false \
    enforce_hostnames=true

Paramètre	Description	Valeur sécurisée
allowed_domains	Domaines autorisés	Un seul domaine par rôle
allow_subdomains	*.example.com autorisé	Selon besoin
allow_bare_domains	example.com sans sous-domaine	false en général
allow_ip_sans	Autoriser les IPs dans SAN	false sauf besoin explicite
allow_localhost	Autoriser localhost	false en prod
enforce_hostnames	Valider le format hostname	true toujours

Glissez pour voir

Éviter les rôles trop larges

Anti-pattern : un rôle unique all-domains avec allowed_domains="*".

Bonne pratique : un rôle par domaine ou par équipe/usage :

• webserver-frontend : allowed_domains="frontend.example.com"
• mtls-backend : allowed_domains="*.internal.svc"
• api-external : allowed_domains="api.example.com"

Chaque rôle a sa policy, chaque équipe ne peut émettre que pour ses domaines.

Rôle pour mTLS interne (TTL court)

vault write pki_int/roles/mtls-internal \
    allowed_domains="service.internal" \
    allow_subdomains=true \
    max_ttl=168h \
    ttl=72h \
    key_type="ec" \
    key_bits=256 \
    client_flag=true \
    server_flag=true \
    require_cn=true \
    enforce_hostnames=true

issue vs sign : quelle méthode choisir ?

Vault PKI propose deux endpoints pour obtenir un certificat :

Endpoint	Clé privée	Cas d'usage
/issue/<role>	Générée par Vault	Scripts, automation, services simples
/sign/<role>	Fournie par le client (CSR)	HSM, exigences de conformité, contrôle total

Glissez pour voir

Méthode issue : Vault génère tout

vault write pki_int/issue/webserver \
    common_name="api.example.com" \
    ttl=720h

Vault génère la clé privée et le certificat. La clé privée est retournée dans la réponse.

Avantages : simple, tout-en-un. Inconvénients : la clé privée transite par Vault et le réseau.

Méthode sign : le client génère la clé

# 1. Générer une clé et une CSR côté client
openssl genrsa -out backend.key 2048
openssl req -new -key backend.key -out backend.csr \
    -subj "/CN=backend.example.com"

# 2. Demander à Vault de signer la CSR
vault write -format=json pki_int/sign/webserver \
    csr=@backend.csr \
    ttl=720h | jq -r '.data.certificate' > backend.crt

Avantages : la clé privée ne quitte jamais le serveur cible. Inconvénients : plus complexe, nécessite un workflow de distribution de CSR.

Quand utiliser `sign` ?

• La clé privée doit rester sur un HSM
• Conformité exige que la clé ne soit jamais exposée
• Vous avez déjà un système de génération de clés (cert-manager, etc.)

Dans tous les autres cas, issue est plus simple.

Étape 4 : émettre des certificats

Certificat simple

vault write pki_int/issue/webserver \
    common_name="api.example.com" \
    ttl=720h

Sortie :

Key                 Value
---                 -----
ca_chain            [-----BEGIN CERTIFICATE-----...]
certificate         -----BEGIN CERTIFICATE-----...
expiration          1747389600
issuing_ca          -----BEGIN CERTIFICATE-----...
private_key         -----BEGIN RSA PRIVATE KEY-----...
private_key_type    rsa
serial_number       5a:c2:1b:4d:7f...

Certificat avec SAN multiples

vault write pki_int/issue/webserver \
    common_name="frontend.example.com" \
    alt_names="www.example.com,cdn.example.com" \
    ttl=720h

IP SAN

Pour autoriser les IPs dans les SAN, le rôle doit avoir allow_ip_sans=true. Évitez en production sauf besoin explicite (mTLS interne, legacy).

Enregistrer dans des fichiers

vault write -format=json pki_int/issue/webserver \
    common_name="backend.example.com" \
    ttl=720h | tee \
    >(jq -r '.data.certificate' > backend.crt) \
    >(jq -r '.data.private_key' > backend.key) \
    >(jq -r '.data.ca_chain[]' > ca-chain.crt) \
    > /dev/null

chmod 600 backend.key
chmod 644 backend.crt ca-chain.crt

Policy pour l'émission

Limitez qui peut émettre des certificats par rôle :

pki-webserver-policy.hcl

# Émettre via issue (Vault génère la clé)
path "pki_int/issue/webserver" {
  capabilities = ["create", "update"]
}

# Signer une CSR (client génère la clé)
path "pki_int/sign/webserver" {
  capabilities = ["create", "update"]
}

# Lire les infos de la CA
path "pki_int/cert/ca" {
  capabilities = ["read"]
}

vault policy write pki-webserver pki-webserver-policy.hcl

CRL et URLs de publication

La qualité de votre PKI dépend de la distribution réelle des URLs, pas seulement de leur configuration dans Vault.

Ce que Vault configure

vault write pki_int/config/urls \
    issuing_certificates="https://vault.example.com/v1/pki_int/ca" \
    crl_distribution_points="https://vault.example.com/v1/pki_int/crl"

Ce que vous devez garantir

1. Accessibilité : les URLs doivent être joignables par tous les clients qui valident les certificats (navigateurs, services, reverse proxies)

2. Résolution DNS : le nom vault.example.com doit résoudre correctement dans tous les environnements

3. TLS valide : ironie, le endpoint doit avoir un certificat valide (bootstrap problem à résoudre)

4. Haute disponibilité : si Vault est down, les validations CRL échouent (selon la politique du client)

Configuration de la CRL

# Fréquence de mise à jour de la CRL
vault write pki_int/config/crl expiry="72h"

Consulter la CRL

curl -s "https://vault.example.com/v1/pki_int/crl" | \
    openssl crl -inform DER -text -noout

Cycle de vie des certificats

Lister les certificats émis

vault list pki_int/certs

Voir un certificat spécifique

vault read pki_int/cert/<serial_number>

Révoquer un certificat

vault write pki_int/revoke serial_number="5a:c2:1b:4d:7f:..."

Supprimer les certificats expirés (tidy)

Vault stocke les métadonnées des certificats émis. Pour nettoyer :

vault write pki_int/tidy \
    tidy_cert_store=true \
    tidy_revoked_certs=true \
    tidy_revoked_cert_issuer_associations=true \
    safety_buffer="72h"

Paramètre	Description
tidy_cert_store	Supprimer les métadonnées des certificats expirés
tidy_revoked_certs	Supprimer les métadonnées des certificats révoqués expirés
safety_buffer	Ne pas toucher aux certificats expirés depuis moins de X

Glissez pour voir

Automatisation du tidy

En production, planifiez un tidy périodique (hebdomadaire) pour éviter l'accumulation de métadonnées. Ce n'est pas critique pour le fonctionnement, mais ça évite que le stockage grossisse indéfiniment.

Renouvellement automatique

Option 1 : cert-manager (Kubernetes)

Pour les workloads Kubernetes, cert-manager avec le provider Vault est la solution recommandée :

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: vault-issuer
spec:
  vault:
    # Pour issue (Vault génère la clé) : path "pki_int/issue/webserver"
    # Pour sign (CSR) : path "pki_int/sign/webserver"
    path: pki_int/sign/webserver
    server: https://vault.example.com
    auth:
      kubernetes:
        role: cert-manager
        mountPath: auth/kubernetes

issue vs sign avec cert-manager

cert-manager génère ses propres clés privées et envoie une CSR à Vault. Utilisez donc /sign/<role>, pas /issue/<role>.

Option 2 : Vault Agent (VM/bare metal)

Vault Agent peut gérer le renouvellement automatique :

agent-config.hcl

template {
  source      = "/etc/vault-agent/cert.tpl"
  destination = "/etc/ssl/certs/myapp/cert.pem"
  perms       = "0644"
  command     = "systemctl reload nginx"
}

template {
  source      = "/etc/vault-agent/key.tpl"
  destination = "/etc/ssl/certs/myapp/key.pem"
  perms       = "0600"
}

Option 3 : script cron (solution simple)

Pour les environnements simples sans Vault Agent :

#!/bin/bash
set -e

SERVICE_NAME="myapp"
CERT_DIR="/etc/ssl/certs/$SERVICE_NAME"
ROLE="webserver"
CN="$SERVICE_NAME.example.com"
TTL="720h"

mkdir -p "$CERT_DIR"

vault write -format=json "pki_int/issue/$ROLE" \
    common_name="$CN" \
    ttl="$TTL" | tee \
    >(jq -r '.data.certificate' > "$CERT_DIR/cert.pem") \
    >(jq -r '.data.private_key' > "$CERT_DIR/key.pem") \
    >(jq -r '.data.ca_chain[]' > "$CERT_DIR/ca.pem") \
    > /dev/null

chmod 600 "$CERT_DIR/key.pem"
systemctl reload nginx

echo "$(date): Certificate renewed for $CN" >> /var/log/cert-renewal.log

# Renouveler tous les 25 jours (TTL 30 jours)
0 3 */25 * * /opt/scripts/renew-cert.sh >> /var/log/cert-renewal.log 2>&1

Cron = solution simple

Le cron fonctionne mais n'est pas la solution la plus robuste :

• Pas de retry automatique en cas d'échec
• Pas de monitoring intégré
• Le script doit gérer l'authentification à Vault

En production, préférez Vault Agent ou cert-manager.

Ce que Vault PKI ne fait pas tout seul

Responsabilité	Vault PKI	Vous
Générer des certificats	✅	—
Stocker la clé privée après émission	❌	✅
Distribuer les certificats aux services	❌	✅
Recharger les services (reload nginx, etc.)	❌	✅
Installer la Root CA dans les trust stores	❌	✅
Monitorer les expirations	❌*	✅
Garantir la qualité du design PKI	❌	✅

Glissez pour voir

*Vault expose des métriques, mais le monitoring est à votre charge.

Distribution de confiance

Vos clients (navigateurs, OS, services) doivent faire confiance à votre Root CA. Cela implique de distribuer root_ca.crt dans les trust stores :

• /etc/ssl/certs/ sur Linux
• Keychain sur macOS
• Certificat store sur Windows
• ConfigMaps Kubernetes pour les pods

Cette distribution est hors scope de Vault.

Dépannage

Symptôme	Cause probable	Solution
domain not allowed	CN non autorisé par le rôle	Vérifier allowed_domains du rôle
TTL exceeds max	TTL demandé > max_ttl du rôle	Réduire le TTL ou augmenter max_ttl
certificate has expired	Certificat non renouvelé	Vérifier le cron/automation
unknown authority	CA chain incomplète	Inclure la chaîne complète côté client
permission denied	Policy manquante	Vérifier les capabilities issue/sign
unable to fetch CRL	URL CRL inaccessible	Vérifier réseau et DNS

Glissez pour voir

Debug du certificat

Pour lire la chaîne, le SNI, les dates de validité et le code de vérification d'un certificat émis, le guide diagnostic TLS avec openssl détaille chaque commande openssl.

# Voir les dates d'expiration
openssl x509 -in cert.pem -noout -dates

# Voir le CN et SAN
openssl x509 -in cert.pem -noout -subject -ext subjectAltName

# Vérifier la chaîne de confiance
openssl verify -CAfile ca-chain.pem cert.pem

# Voir les URLs AIA et CRL
openssl x509 -in cert.pem -noout -text | grep -A2 "Authority Information Access"
openssl x509 -in cert.pem -noout -text | grep -A1 "CRL Distribution Points"

Bonnes pratiques

Architecture

1. Root CA hors de Vault : machine air-gapped ou HSM dédié
2. Un mount = un niveau : pki pour la root (si dans Vault), pki_int pour l'intermédiaire
3. Rotation d'issuer : préparer le nouvel issuer avant expiration de l'ancien

Rôles

1. Un rôle par usage : pas de rôle générique multi-domaines
2. TTL courts : 30-90 jours pour les services, 24-72h pour le mTLS
3. enforce_hostnames=true : toujours
4. allow_ip_sans=false : sauf besoin explicite documenté

Opérations

1. Tidy régulier : nettoyer les certificats expirés/révoqués
2. Monitoring : alerter sur les certificats proches de l'expiration
3. Audit : tracer toutes les émissions
4. Backup : la Root CA est critique, sauvegardez-la séparément

À retenir

1. Root CA hors de Vault en production, seule l'intermédiaire est dans Vault
2. issue : Vault génère clé + cert, simple mais clé en transit
3. sign : client envoie CSR, clé reste locale
4. Rôles stricts : un rôle par domaine/usage, pas de wildcard global
5. URLs accessibles : les CRL et AIA doivent être joignables par les clients
6. Multi-issuer : depuis 1.11+, rotation sans interruption possible
7. Tidy : nettoyez les métadonnées des certificats expirés
8. Vault ≠ distribution : vous restez responsable de l'installation des certificats sur les services

Prochaines étapes

Transit Encryption as a Service

Authentification Configurer AppRole pour les services

Introduction Vault Revenir aux concepts

×

📖 Voir la documentation →