ssh-agent et ssh-add, en pratique : arrêtez de taper votre phrase secrète

25 août 2026 · mis à jour 24 oct. 2026 · Termalin Team sshssh-agentssh-keystutorial

ssh-agent est un programme en arrière-plan qui garde vos clés privées déverrouillées en mémoire et signe les défis d’authentification avec elles, de sorte que vous saisissez la phrase secrète d’une clé une fois par session au lieu d’une fois par connexion. ssh-add est la commande qui y charge les clés.

Vous avez bien fait les choses et mis une phrase secrète sur votre clé SSH — et vous voilà à la taper pour la cinquième fois avant le déjeuner. La solution existe depuis des décennies : l’agent SSH. Déverrouillez la clé une fois, et chaque connexion ensuite s’authentifie en silence. Le hic, c’est que ce « une fois » ne fonctionne que si l’agent tourne vraiment, que votre shell sait le trouver, et que la clé est chargée — trois choses distinctes, chacune avec sa propre manière d’échouer. Voici le guide pratique : démarrer l’agent sur chaque système, le piloter avec ssh-add, tout rendre automatique, et décoder les deux erreurs qui expliquent la quasi-totalité des ennuis d’agent.

Ce qu’est l’agent, en un paragraphe

ssh-agent est un petit processus en arrière-plan qui garde vos clés privées déchiffrées en mémoire — jamais sur le disque. Quand un serveur vous envoie un défi, ssh le transmet à l’agent, l’agent le signe avec la clé en mémoire, et seule la signature revient — la clé elle-même ne quitte jamais l’agent, ne passe jamais sur le réseau, et reste chiffrée sur le disque. Une invite de phrase secrète pour charger la clé, puis chaque connexion ultérieure est servie depuis la mémoire. C’est tout le modèle mental : l’agent est un service de signature, pas un coffre à clés que l’on peut lire — il garde le secret et ne distribue jamais que des signatures. (Cette propriété est aussi le piège de sécurité, et elle a sa propre section à la fin.)

Sous Windows ? Lisez d’abord le guide Windows

Si vous arrivez ici depuis error connecting to agent: No such file or directory, ce message est propre à Windows : il vient du ssh de Git Bash / MSYS2, tout comme ses correctifs — le service OpenSSH Authentication Agent, l’agent propre à Git Bash, et l’erreur 1058. Tout cela se trouve dans ssh-agent sous Windows. Tout ce qui suit est le flux de travail ssh-agent et ssh-add multiplateforme, et les erreurs qu’il décode sont celles du client OpenSSH lui-même : Could not open a connection to your authentication agent et The agent has no identities.

Démarrer l’agent, selon le système

Linux — `eval "$(ssh-agent -s)"`

Sur une session de bureau, vous avez presque certainement déjà un agent — soit un service utilisateur systemd, soit GNOME Keyring qui en joue le rôle — avec SSH_AUTH_SOCK exporté pour toute votre session. Testez avec ssh-add -l. Si rien ne répond (fréquent sur une connexion SSH nue, dans des conteneurs, ou sur des serveurs minimaux), démarrez-en un à la main :

eval "$(ssh-agent -s)"

Le eval a son importance. ssh-agent -s ne fait qu’afficher les variables SSH_AUTH_SOCK et SSH_AGENT_PID ; c’est le eval qui les définit dans votre shell courant pour que ssh trouve le socket. Lancer ssh-agent tout nu en se demandant pourquoi rien n’a changé est la façon la plus répandue de « démarrer » un agent qu’aucun outil ne voit.

macOS — launchd le lance pour vous

launchd lance un agent pour vous dès l’ouverture de session — il n’y a rien à démarrer. L’avantage propre à macOS est l’intégration au trousseau (Keychain), décrite plus bas.

Démarrer ssh-agent sous Windows

Windows récent embarque un service OpenSSH Authentication Agent, mais il est en démarrage manuel et ne tourne pas par défaut. Activez-le une fois, depuis un PowerShell en mode administrateur :

Set-Service ssh-agent -StartupType Automatic
Start-Service ssh-agent

Ensuite, ssh-add fonctionne dans n’importe quel terminal — PowerShell, cmd, ou le client OpenSSH de Windows sous Git Bash — et l’agent survit aux redémarrages. Un piège : Git pour Windows embarque ses propres ssh et ssh-agent, et dans Git Bash, le ssh de votre PATH peut être celui-là, qui dialogue avec un agent distinct. Si ssh-add -l donne des résultats divergents entre Git Bash et PowerShell, pointez Git vers le client système pour qu’ils partagent un seul agent :

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

Le tutoriel complet — le service, Git Bash, et le chargement des clés à l’ouverture de session — se trouve dans ssh-agent sous Windows.

Le piloter avec ssh-add

Charger une clé : `ssh-add ~/.ssh/id_ed25519`

ssh-add                          # load the default keys (id_ed25519, id_rsa, …)
ssh-add ~/.ssh/id_ed25519        # load a specific key (prompts for the passphrase once)

Sans chemin, ssh-add charge les noms de clés par défaut depuis ~/.ssh ; donnez-lui un chemin pour charger une clé précise. Dans les deux cas, il demande la phrase secrète une fois, puis garde la clé déchiffrée en mémoire.

Lister ce qui est chargé : `ssh-add -l`

ssh-add -l                       # list fingerprints of loaded keys
ssh-add -L                       # print the full public keys
ssh-add -d ~/.ssh/id_ed25519     # remove one key
ssh-add -D                       # remove all keys

ssh-add -l est le premier diagnostic de tout problème d’authentification : si la clé attendue n’est pas dans cette liste, l’agent ne peut pas signer avec elle, quoi que tout le reste laisse croire.

Définir un délai pour ssh-agent : `ssh-add -t`

Deux options méritent de devenir des habitudes :

-t fixe une durée de vie. ssh-add -t 3600 ~/.ssh/id_ed25519 charge la clé pour une heure ; ensuite, l’agent l’oublie et l’usage suivant redemande la phrase secrète. Une clé qui reste déverrouillée en mémoire pendant trois semaines d’uptime est une clé utilisable longtemps après que vous avez cessé d’y penser.
-c exige une confirmation. Chaque demande de signature fait apparaître une invite locale avant que l’agent ne réponde. Un peu agaçant, exactement ce qu’il faut pour les clés à forte valeur.

Le rendre automatique : AddKeysToAgent

Le rituel manuel de ssh-add disparaît avec une ligne dans ~/.ssh/config (en anglais) :

Host *
    AddKeysToAgent yes

Désormais, le premier ssh qui a besoin d’une clé demande la phrase secrète une seule fois et charge la clé dans l’agent par effet de bord. Aucune commande séparée à retenir — l’invite cesse simplement de se répéter. Vous pouvez aussi lui donner une durée de vie (AddKeysToAgent 1h) pour obtenir le comportement de -t sans l’option.

macOS : survivre aux redémarrages avec le trousseau. Par défaut, l’agent oublie les clés quand il redémarre. macOS peut stocker la phrase secrète dans votre trousseau de session pour que les clés se rechargent sans ressaisie :

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

et dans ~/.ssh/config :

Host *
    AddKeysToAgent yes
    UseKeychain yes

Ensuite, la question de la phrase secrète trouve sa réponse dans le trousseau à l’ouverture de session et vous ne la revoyez plus — tandis que le fichier de clé sur le disque reste chiffré.

Les deux erreurs que tout le monde rencontre

Could not open a connection to your authentication agent — ssh-add ne trouve aucun agent. Soit aucun ne tourne, soit un tourne mais ce shell n’a pas SSH_AUTH_SOCK défini. Le correctif est le démarrage par système ci-dessus : la ligne eval "$(ssh-agent -s)" sous Linux (vérifiez d’abord si votre session de bureau en fournit déjà un — démarrer un second agent par terminal ne fait qu’éparpiller les clés chargées entre les processus), le démarrage du service sous Windows. Vous rencontrerez aussi cette erreur dans les tâches cron et en CI, où aucune session de connexion n’a jamais exporté la variable.

The agent has no identities. — le problème inverse : l’agent va bien, mais rien n’est chargé. Faites un ssh-add de votre clé. Si elle était chargée et a disparu, c’est qu’une durée de vie -t a expiré ou que l’agent a redémarré — c’est précisément à cela que servent AddKeysToAgent yes et le trousseau de macOS.

Et le troisième cas : l’agent semble parfait — ssh-add -l affiche la clé — mais le serveur répond toujours Permission denied (publickey). Ce n’est plus un problème d’agent ; déroulez la liste de contrôle publickey — mauvais utilisateur, mauvaise clé proposée, permissions d’authorized_keys.

Un agent déverrouillé est un identifiant actif

L’agent ne divulgue jamais la clé — mais le socket est un oracle de signature : il signe pour quiconque peut l’atteindre, et ne demande jamais qui le sollicite. Sur votre propre machine, c’est sans danger — le socket se trouve dans un répertoire privé par utilisateur que vous seul pouvez lire. Le danger, c’est la forme du député confus : quand le socket devient accessible à quelque chose que vous n’aviez pas prévu — un agent transféré sur un bastion partagé, ou un processus tournant sous votre utilisateur en qui vous n’avez pas confiance — cette chose peut s’authentifier en votre nom auprès de chaque serveur que vos clés atteignent, sans jamais voir la clé. Que la clé ne fuite jamais n’est que la moitié de la garantie ; contrôler qui peut l’utiliser est l’autre moitié, et c’est pourquoi une bonne hygiène d’agent vaut le petit effort.

Donnez une durée de vie aux clés (-t, ou une durée de vie sur AddKeysToAgent) pour qu’un agent inactif se refroidisse de lui-même.
Verrouillez l’agent quand vous vous éloignez : ssh-add -x le verrouille derrière un mot de passe, ssh-add -X le déverrouille ; ssh-add -D supprime simplement tout.
Utilisez -c pour les clés qui atteignent la production.
Ne transférez pas l’agent par défaut. ssh -A — le transfert d’agent SSH — expose l’usage en direct de vos clés sur l’hôte distant, si bien que quiconque y est root peut signer en votre nom pendant toute la durée de votre session. Celle-là mérite sa propre lecture : le transfert d’agent SSH, pratique et dangereux (en anglais).

Comment Termalin gère cela

Termalin intègre tout ce flux de travail, les angles vifs limés. Son agent de clés déverrouille vos clés une seule fois et signe à votre place — aucun service du système à activer, aucune ligne eval, aucun socket par shell à perdre. La mise en cache de la phrase secrète s’accompagne d’un délai de reverrouillage par défaut, c’est-à-dire l’habitude du ssh-add -t appliquée pour vous plutôt que confiée à votre mémoire. Et comme il parle le protocole ssh-agent standard, git et vos outils en ligne de commande habituels signent à travers lui sans rien changer — il remplace le rituel, pas votre chaîne d’outils.

Termalin est un client SSH gratuit et multiplateforme dont l’agent intégré déverrouille vos clés une fois et les reverrouille sur minuterie — téléchargez-le, ou lisez comment il gère vos clés en toute sécurité.