Vault SSH : accès sécurisé aux serveurs

Vault SSH secrets engine permet de signer des certificats SSH ou de générer des OTP pour l'accès aux serveurs. Plus de clés permanentes à distribuer : chaque accès est temporaire et traçable.

Ce guide couvre le mode signed certificates (recommandé) et le mode OTP (cas spécifiques).

Pourquoi Vault pour l'accès SSH

Le modèle classique dépose une clé publique dans le fichier authorized_keys de chaque compte, sur chaque serveur. Le problème n'est pas cryptographique, il est organisationnel : rien ne relie durablement une clé à une identité, et retirer un accès suppose de repasser sur toutes les machines. Vault remplace cette distribution par une autorité de certification (CA, l'entité qui signe et dont la signature fait foi) dont la clé publique n'est déposée qu'une seule fois par serveur.

Clés SSH classiques	Avec Vault SSH
Clé permanente sur le poste	Certificat valide quelques heures
authorized_keys à maintenir	CA trusted, pas de liste à gérer
Révocation = supprimer la clé partout	TTL courts ; révocation SSH moins intégrée que TLS
Audit : "quelle clé ?"	Audit : "quel user Vault, quand"
Rotation = redistribution	Rotation = nouveau certificat

Glissez pour voir

Le vrai gain

Avec les certificats SSH signés, vous n'avez plus besoin de maintenir authorized_keys sur chaque serveur. Le serveur fait confiance à la CA Vault, tout certificat signé par cette CA est accepté.

Modes supportés : signed certificates vs OTP

Le moteur SSH expose deux modes qui ne reposent pas sur le même mécanisme de vérification. Les certificats signés sont validés localement par OpenSSH, sans appel réseau. Les OTP (One-Time Password, mot de passe à usage unique) exigent un composant supplémentaire installé sur chaque serveur. Le mode se choisit au niveau du rôle, via le paramètre key_type.

Mode	Comment ça marche	Recommandation
Signed certificates	Vault signe la clé publique de l'utilisateur	Recommandé
OTP	Vault génère un mot de passe à usage unique	Cas spécifiques (vieux SSH, contraintes sshd)

Glissez pour voir

Mode déprécié : dynamic keys

Le mode dynamic keys (Vault génère une paire de clés et la déploie sur le serveur) a été retiré depuis Vault 1.13. Si vous l'utilisez encore, migrez vers les certificats signés.

Prérequis

Secrets dynamiques Concepts lease, TTL, révocation

Policies Contrôler l'accès SSH

• Vault installé et démarré
• Accès admin pour configurer le moteur
• Serveurs SSH accessibles avec droits root/sudo pour la configuration

Mode signed certificates

Dans ce mode, Vault tient le rôle d'autorité de certification SSH. La clé privée de l'utilisateur ne quitte jamais son poste : Vault reçoit uniquement la clé publique, la signe, et retourne un certificat de courte durée. Les cinq étapes qui suivent s'exécutent dans l'ordre : les trois premières se font côté Vault et une seule fois, les deux dernières concernent l'utilisateur et le serveur cible.

Architecture

Le schéma résume les trois échanges : l'utilisateur demande la signature de sa clé publique, Vault renvoie un certificat horodaté, et le serveur le valide hors ligne à partir de la clé publique de la CA qu'il détient déjà.

Étape 1 : activer le moteur SSH

Le moteur est monté sur un chemin explicite, ssh-client-signer. Ce chemin apparaît ensuite dans toutes les policies et dans les commandes de signature : le fixer maintenant évite de tout réécrire plus tard.

vault secrets enable -path=ssh-client-signer ssh

Étape 2 : générer la CA SSH

generate_signing_key=true demande à Vault de créer lui-même la paire de clés de la CA. La clé privée reste dans Vault et n'est jamais exposée ; seule la partie publique est lisible.

vault write ssh-client-signer/config/ca generate_signing_key=true

Récupérer la clé publique de la CA :

vault read -field=public_key ssh-client-signer/config/ca > vault-ca.pub

Clé publique à distribuer

Le fichier vault-ca.pub doit être copié sur tous les serveurs SSH qui doivent faire confiance à Vault. C'est la seule distribution nécessaire.

Étape 3 : créer un rôle de signature

Le rôle définit ce qu'un porteur de token a le droit de faire signer : quels comptes Unix, quelles extensions SSH, et pour combien de temps. C'est le point de contrôle principal côté Vault.

Syntaxe CLI pour les maps

Le paramètre default_extensions attend un objet JSON. Le CLI Vault ne parse pas correctement '{"permit-pty": ""}' en ligne de commande. Utilisez l'API HTTP ou un fichier JSON :

# Via API (recommandé pour les maps)
curl -X POST "$VAULT_ADDR/v1/ssh-client-signer/roles/admin" \
  -H "X-Vault-Token: $VAULT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_type": "ca",
    "allowed_users": "*",
    "allow_user_certificates": true,
    "allowed_extensions": "permit-pty,permit-port-forwarding",
    "default_extensions": {"permit-pty": ""},
    "ttl": "30m",
    "max_ttl": "24h"
  }'

Alternative CLI (sans default_extensions, les extensions seront demandées à la signature) :

vault write ssh-client-signer/roles/admin \
    key_type="ca" \
    allowed_users="*" \
    allow_user_certificates=true \
    allowed_extensions="permit-pty,permit-port-forwarding" \
    ttl="30m" \
    max_ttl="24h"

Paramètre	Description	Exemple
key_type	Type de signature	ca pour certificats
allowed_users	Users Unix autorisés	ubuntu,ec2-user ou *
allowed_extensions	Extensions SSH autorisées	permit-pty,permit-agent-forwarding
default_extensions	Extensions par défaut (via API)	{"permit-pty": ""}
ttl	Durée de vie du certificat	30m, 4h
max_ttl	Durée maximale	24h

Glissez pour voir

allowed_users=* : à éviter en production

allowed_users="*" permet de se connecter en tant que n'importe quel user Unix. Bonnes pratiques :

• Un rôle par population : ssh-ops, ssh-dev, ssh-dba
• Un rôle par niveau de privilège : séparer accès root des accès applicatifs
• Lister explicitement les users : allowed_users="ubuntu,ec2-user"
• Limiter les extensions : pas de permit-agent-forwarding sans besoin

Exemples :

• ops-admin : allowed_users="root,admin"
• dev-access : allowed_users="ubuntu,ec2-user"

Rôle restrictif (exemple production)

Ce rôle dev énumère les comptes Unix autorisés au lieu du joker, et n'accorde que l'extension permit-pty, c'est-à-dire l'ouverture d'un terminal interactif, sans redirection de port ni transfert d'agent.

vault write ssh-client-signer/roles/dev \
    key_type="ca" \
    allowed_users="ubuntu,ec2-user" \
    allow_user_certificates=true \
    allowed_extensions="permit-pty" \
    default_extensions='{"permit-pty": ""}' \
    ttl="4h" \
    max_ttl="8h"

Étape 4 : signer une clé publique

L'utilisateur génère (ou utilise) sa paire de clés :

# Si pas de clé existante
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -N ""

Demander la signature à Vault :

vault write -field=signed_key ssh-client-signer/sign/dev \
    public_key=@$HOME/.ssh/id_ed25519.pub \
    valid_principals="ubuntu" \
    > ~/.ssh/id_ed25519-cert.pub

sign vs issue

Ici on utilise /sign : l'utilisateur fournit sa clé publique existante et Vault la signe. C'est le cas d'usage standard.

Certaines intégrations (comme Boundary) utilisent /issue où Vault génère lui-même la paire de clés. Consultez la doc de votre workflow.

Vérifier le certificat :

ssh-keygen -L -f ~/.ssh/id_ed25519-cert.pub

Sortie :

/home/user/.ssh/id_ed25519-cert.pub:
        Type: ssh-ed25519-cert-v01@openssh.com user certificate
        Public key: ED25519-CERT SHA256:abc123...
        Signing CA: ED25519 SHA256:xyz789...
        Key ID: "vault-token-abc123"
        Serial: 1234567890
        Valid: from 2026-03-16T10:00:00 to 2026-03-16T14:00:00
        Principals:
                ubuntu
        Critical Options: (none)
        Extensions:
                permit-pty

Étape 5 : configurer le serveur SSH

Sur chaque serveur cible :

# Copier la CA publique
sudo cp vault-ca.pub /etc/ssh/vault-ca.pub

# Configurer sshd
echo "TrustedUserCAKeys /etc/ssh/vault-ca.pub" | sudo tee -a /etc/ssh/sshd_config

# Redémarrer sshd
sudo systemctl restart sshd

AuthorizedPrincipalsFile

Pour plus de contrôle, utilisez AuthorizedPrincipalsFile pour limiter quels principals sont autorisés par user Unix :

/etc/ssh/sshd_config

TrustedUserCAKeys /etc/ssh/vault-ca.pub
AuthorizedPrincipalsFile /etc/ssh/auth_principals/%u

/etc/ssh/auth_principals/ubuntu

ubuntu
dev-team

Seuls les certificats avec principal ubuntu ou dev-team pourront se connecter en tant que ubuntu.

Connexion SSH

Aucune option supplémentaire n'est nécessaire : OpenSSH cherche automatiquement le fichier id_ed25519-cert.pub à côté de la clé privée passée à -i.

ssh -i ~/.ssh/id_ed25519 ubuntu@server.example.com

SSH présente automatiquement le certificat id_ed25519-cert.pub avec la clé privée id_ed25519.

Principals : le pivot de l'autorisation SSH

Le certificat signé ne dit pas seulement "cette clé est valide". Il embarque des principals qui déterminent en tant que quel user Unix le porteur peut se connecter.

Niveau de contrôle	Qui décide	Paramètre
Rôle Vault	Admin Vault	allowed_users
Demande de signature	Utilisateur	valid_principals
Serveur SSH	Admin système	AuthorizedPrincipalsFile

Glissez pour voir

Exemple de chaîne de validation

La séquence suivante montre où chaque filtre intervient, depuis la restriction posée dans le rôle Vault jusqu'à la décision finale du serveur.

1. Le rôle dev autorise allowed_users="ubuntu,ec2-user"
2. L'utilisateur demande un certificat avec valid_principals="ubuntu"
3. Le certificat contient Principals: ubuntu
4. Le serveur vérifie que ubuntu est dans /etc/ssh/auth_principals/ubuntu
5. Connexion autorisée

Double vérification

Le rôle Vault limite ce que l'utilisateur peut demander. AuthorizedPrincipalsFile limite ce que le serveur accepte. Les deux filtres s'additionnent.

Helper : vault ssh

Vault fournit une commande intégrée qui automatise tout :

vault ssh -role=dev -mode=ca ubuntu@server.example.com

Cette commande :

1. Signe votre clé publique locale
2. Lance ssh avec le certificat
3. Nettoie après déconnexion

Interactif vs automatisation

vault ssh est très pratique pour les accès interactifs : un admin qui se connecte ponctuellement à un serveur.

Pour des workflows automatisés (CI/CD, scripts), on utilise souvent directement l'API de signature ou des scripts personnalisés (meilleur contrôle des erreurs, intégration aux outils existants).

Quand choisir certificats signés ou OTP

La différence décisive tient à l'endroit où se fait la vérification. Avec un certificat signé, OpenSSH valide seul la signature : Vault peut être indisponible, les connexions continuent tant que les certificats en circulation n'ont pas expiré. Avec l'OTP, chaque connexion interroge Vault, ce qui en fait une dépendance de disponibilité au moment précis de l'authentification.

Critère	Certificats signés	OTP
Vérification	Locale (OpenSSH)	Réseau (Vault)
Dépendance Vault	À la signature	À chaque connexion
Prérequis serveur	TrustedUserCAKeys	vault-ssh-helper + PAM
Version OpenSSH	5.6+ (certificats)	Toutes
Cas d'usage	Défaut	Vieux SSH, contraintes sshd, migration

Glissez pour voir

Règle simple

• Certificats signés : choix par défaut
• OTP : uniquement si vous ne pouvez pas modifier sshd_config ou si OpenSSH ne supporte pas les certificats

Mode OTP (cas spécifiques)

Le mode OTP génère un mot de passe à usage unique. Le serveur doit exécuter un helper (vault-ssh-helper) qui valide l'OTP auprès de Vault.

Dépendance opérationnelle forte

Avec OTP, chaque connexion SSH dépend d'un appel réseau à Vault :

1. L'utilisateur obtient un OTP via vault write ssh/creds/...
2. À la connexion, vault-ssh-helper (via PAM) contacte Vault
3. Vault valide et détruit l'OTP (usage unique)
4. Si Vault est injoignable = connexion impossible

Contrairement aux certificats signés (vérification locale par OpenSSH), le mode OTP introduit une dépendance réseau et de disponibilité Vault au moment précis de l'authentification.

Quand utiliser OTP

Trois situations justifient encore ce mode, toutes liées à une contrainte sur le serveur plutôt qu'à un choix d'architecture.

• Serveurs sans support certificats (très vieux OpenSSH)
• Environnements où vous ne pouvez pas modifier sshd_config
• Transition depuis des mots de passe classiques

Complexité supplémentaire

Le mode OTP nécessite vault-ssh-helper sur chaque serveur, configuré via PAM. C'est plus complexe à déployer et à maintenir que les certificats.

Préférez les certificats signés quand c'est possible.

Configuration basique OTP

Un rôle OTP ne signe rien : il déclare le compte Unix cible et la plage d'adresses (cidr_list) depuis laquelle les mots de passe générés seront acceptés.

# Activer le moteur
vault secrets enable -path=ssh ssh

# Créer un rôle OTP
vault write ssh/roles/otp-role \
    key_type=otp \
    default_user=ubuntu \
    cidr_list=10.0.0.0/8

Obtenir un OTP :

vault write ssh/creds/otp-role ip=10.0.1.50

Sortie :

Key                Value
---                -----
lease_id           ssh/creds/otp-role/abc123
key                3f4e-a2b1-c9d8-e7f6
username           ubuntu
ip                 10.0.1.50

Sur le serveur, configurez vault-ssh-helper (voir documentation HashiCorp pour le déploiement du helper PAM).

Policy pour l'accès SSH

Une policy Vault autorise des chemins, pas des rôles. Pour cantonner un utilisateur au rôle dev, on lui accorde l'écriture sur ssh-client-signer/sign/dev et rien d'autre : il ne pourra pas demander une signature avec un rôle plus permissif. La lecture de config/ca reste utile pour comparer l'empreinte de la CA depuis le poste client.

policy-ssh-dev.hcl

# Signer des certificats avec le rôle dev
path "ssh-client-signer/sign/dev" {
  capabilities = ["create", "update"]
}

# Lire la clé publique de la CA (pour vérification)
path "ssh-client-signer/config/ca" {
  capabilities = ["read"]
}

vault policy write ssh-dev policy-ssh-dev.hcl

Intégration : ssh-agent et renouvellement

Un certificat à TTL court doit être renouvelé, sinon la connexion échoue en pleine session de travail. Deux briques se complètent : ssh-agent, qui évite de ressaisir la passphrase de la clé privée, et un renouvellement déclenché avant l'expiration plutôt qu'après l'échec.

Avec ssh-agent

On ajoute la clé privée, pas le certificat : ssh-add charge automatiquement le fichier -cert.pub correspondant s'il se trouve dans le même répertoire.

# Ajouter la clé et le certificat à l'agent
ssh-add ~/.ssh/id_ed25519

# Le certificat est automatiquement utilisé
ssh ubuntu@server.example.com

Script de renouvellement automatique

Le script compare la date d'expiration du certificat courant à l'heure système et ne redemande une signature que s'il reste moins de dix minutes de validité, ce qui évite de solliciter Vault à chaque connexion.

Exemple pédagogique

Ce script illustre le principe. En production, préférez un wrapper plus robuste avec gestion des erreurs réseau, retry, et logging, ou une intégration outillée (Ansible, scripts d'init).

#!/bin/bash
set -e

ROLE="dev"
PRINCIPAL="ubuntu"
KEY_PATH="$HOME/.ssh/id_ed25519"

# Vérifier si le certificat existe et est encore valide
if [[ -f "${KEY_PATH}-cert.pub" ]]; then
    EXPIRY=$(ssh-keygen -L -f "${KEY_PATH}-cert.pub" 2>/dev/null | grep "Valid:" | grep -oP 'to \K[^ ]+')
    if [[ -n "$EXPIRY" ]]; then
        EXPIRY_TS=$(date -d "$EXPIRY" +%s 2>/dev/null || echo 0)
        NOW_TS=$(date +%s)
        # Renouveler si expire dans moins de 10 minutes
        if (( EXPIRY_TS - NOW_TS > 600 )); then
            echo "Certificat encore valide jusqu'à $EXPIRY"
            exit 0
        fi
    fi
fi

# Obtenir un nouveau certificat
echo "Renouvellement du certificat SSH..."
vault write -field=signed_key "ssh-client-signer/sign/${ROLE}" \
    public_key=@"${KEY_PATH}.pub" \
    valid_principals="$PRINCIPAL" \
    > "${KEY_PATH}-cert.pub"

echo "Certificat renouvelé"
ssh-keygen -L -f "${KEY_PATH}-cert.pub" | grep "Valid:"

Dépannage

Les échecs d'authentification par certificat renvoient presque tous le même message côté client, Permission denied (publickey), quel que soit le motif réel : certificat expiré, CA inconnue du serveur ou principal refusé. Le tableau relie les symptômes observables aux causes probables, à confirmer avec les commandes de diagnostic qui suivent.

Symptôme	Cause probable	Solution
Permission denied (publickey)	Certificat expiré	Renouveler le certificat
no matching key	CA non trusted sur le serveur	Vérifier TrustedUserCAKeys
certificate not valid for user	Principal incorrect	Vérifier valid_principals
certificate has expired	TTL trop court	Augmenter le TTL ou renouveler
Connexion lente	OTP + latence réseau Vault	Passer aux certificats

Glissez pour voir

Debug côté serveur

Le journal de sshd indique si un certificat a été présenté et pour quelle raison il a été rejeté ; ssh-keygen -L relit son contenu en clair, principals et dates comprises.

# Logs sshd détaillés
sudo journalctl -u sshd -f

# Tester manuellement la validation du certificat
ssh-keygen -L -f /tmp/user-cert.pub

Debug côté client

Le mode verbeux liste les clés et certificats proposés au serveur, dans l'ordre, avant même la réponse de celui-ci.

# Connexion verbeuse
ssh -vvv ubuntu@server.example.com

# Vérifier que le certificat est présenté
# Chercher "Offering public key: ... cert" dans la sortie

Ce que le moteur SSH ne fait pas

Vault couvre l'émission des certificats et leur expiration. Tout ce qui relève de la distribution de la confiance et de la configuration de sshd reste à votre charge, et c'est précisément là que se concentrent les erreurs de mise en production. Le tableau ci-dessous partage explicitement les responsabilités.

Responsabilité	Vault	Vous
Signer des certificats	✅	Rien à faire
Gérer les TTL	✅	Rien à faire
Distribuer la CA publique	❌	✅
Configurer sshd	❌	✅
Gérer la clé privée utilisateur	❌	✅
Gérer les principals autorisés	✅ (rôles)	✅ (AuthorizedPrincipalsFile)
Révocation (CRL SSH)	⚠️ Limité	✅
Remplacer un bastion / PAM	❌	✅
Distribuer automatiquement la confiance OpenSSH	❌	✅

Glissez pour voir

Révocation SSH : modèle différent de TLS

SSH supporte les revoked keys via RevokedKeys dans sshd_config, mais la révocation n'est pas aussi intégrée qu'en TLS (pas de CRL/OCSP natif pour SSH).

La stratégie principale reste les TTL très courts (30 min - 4h) : un certificat compromis devient inutilisable rapidement sans intervention.

Vault n'est pas un bastion

Vault signe des certificats, mais ne remplace pas :

• un bastion SSH (comme Boundary, Teleport)
• une couche d'autorisation de session
• un enregistrement ou replay de session

Pour un accès privilégié complet, Vault SSH peut s'insérer dans une chaîne plus large (ex: HCP Boundary + Vault SSH).

CE vs Enterprise : CA SSH et HSM

Tout ce qui précède fonctionne en Community Edition : la génération de la CA, la signature de certificats et le mode OTP n'exigent aucune licence. Seule la délégation des opérations de signature à un matériel cryptographique externe relève de l'édition Enterprise.

Fonctionnalité	Community Edition	Enterprise
Générer une CA SSH dans Vault	✅	✅
Signer des certificats	✅	✅
Mode OTP	✅	✅
Managed keys (HSM/KMS externe)	❌	✅
Déléguer la signature à un HSM	❌	✅

Glissez pour voir

HSM et conformité

En Vault Enterprise, le moteur SSH peut s'appuyer sur des managed keys pour déléguer les opérations de signature à un HSM (Luna, YubiHSM) ou un KMS cloud. Utile pour les environnements soumis à des exigences de conformité (PCI-DSS, SOC2).

À retenir

1. Signed certificates : mode recommandé, pas d'authorized_keys à gérer
2. CA SSH : Vault génère et détient la CA, distribuer la clé publique
3. Principals : pivot de l'autorisation, à configurer côté Vault ET serveur
4. TTL courts : 30 min - 4h, meilleure stratégie de "révocation" pour SSH
5. TrustedUserCAKeys : configuration serveur pour faire confiance à Vault
6. OTP : cas spécifiques, introduit une dépendance réseau à chaque connexion
7. Enterprise : managed keys pour déléguer la signature à un HSM
8. Vault n'est pas un bastion : il signe, mais ne gère pas les sessions

Prochaines étapes

Identity broker Vault comme courtier d'identité

Database secrets Credentials PostgreSQL/MySQL dynamiques

Secrets dynamiques Concepts et comparaison

×

📖 Voir la documentation →