Utiliser l’authentification par clé SSH
Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019
Vous pouvez vous connecter à vos dépôts Git via SSH sur macOS, Linux ou Windows pour vous connecter en toute sécurité à Azure DevOps.
Important
Les URL SSH ont changé, mais les anciennes URL SSH continuent de fonctionner. Si vous avez déjà configuré SSH, mettez à jour vos URL distantes au nouveau format :
Les URL SSH à jour commencent par ssh.dev.azure.com
. Les URL précédentes utilisent vs-ssh.visualstudio.com
.
- Vérifiez quelles télécommandes utilisent SSH. Exécutez
git remote -v
dans votre shell ou utilisez plutôt un client GUI. - Visitez votre référentiel sur le Web et sélectionnez Cloner.
- Sélectionnez SSH et copiez la nouvelle URL SSH.
- Dans votre shell, exécutez
git remote set-url <remote name> <new SSH URL>
pour chaque distant d'un référentiel que vous souhaitez mettre à jour. Vous pouvez également utiliser un client GUI pour mettre à jour les URL distantes.
Fonctionnement de l’authentification par clé SSH
L’authentification par clé publique SSH fonctionne avec une paire asymétrique de clés de chiffrement générées. La clé publique est partagée avec Azure DevOps et utilisée pour vérifier la connexion SSH initiale. La clé privée est sécurisée sur votre système.
Configurer l’authentification par clé SSH
Les étapes suivantes couvrent la configuration de l'authentification par clé SSH sur les plates-formes suivantes à l'aide de la ligne de commande (également appelée shell
) :
- Linux
- macOS
- Systèmes Windows exécutant Git pour Windows
Remarque
Depuis Visual Studio 2017, SSH peut être utilisé pour se connecter aux référentiels Azure DevOps Git.
Conseil
Sur Windows, nous avons recommandé l’utilisation du Gestionnaire d’informations d’identification Git ou des jetons d’accès personnels.
Étape 1 : Créer vos clés SSH
Remarque
Si vous avez déjà créé des clés RSA SSH sur votre système, ignorez cette étape et configurez vos clés SSH.
Pour vérifier cela, accédez à votre répertoire personnel et examinez le dossier .ssh
(%UserProfile%\.ssh\
sous Windows ou ~/.ssh/
sous Linux, macOS et Windows avec Git Bash). Si vous voyez deux fichiers nommés id_rsa
et id_rsa.pub
respectivement, continuez la configuration de vos clés SSH.
Pour utiliser l’authentification par clé, vous devez d’abord générer des paires de clés publiques/privées pour votre client. ssh-keygen.exe est utilisé pour générer des fichiers de clés et les algorithmes DSA, RSA, ECDSA ou Ed25519 peuvent être spécifiés. Si aucun algorithme n’est spécifié, Ed25519 est utilisé.
Remarque
Le seul type de clé SSH pris en charge par Azure DevOps est RSA.
Pour générer des fichiers de clés en utilisant l’algorithme RSA pris en charge par Azure DevOps (soit RSA-SHA2-256 ou RSA-SHA2-512), exécutez l’une des commandes suivantes depuis un PowerShell ou un autre shell tel que bash
sur votre client :
ssh-keygen -t rsa-sha2-256
Or
ssh-keygen -t rsa-sha2-512
La sortie de la commande doit afficher la sortie suivante (où username
se trouve votre nom d’utilisateur) :
Generating public/private rsa key pair.
Enter file in which to save the key (C:\Users\username/.ssh/id_rsa):
Vous pouvez appuyer sur Entrée pour accepter la valeur par défaut ou indiquer un chemin et/ou un nom de fichier où vous aimeriez que vos clés soient générées. À ce stade, vous êtes invité à utiliser une phrase secrète pour chiffrer vos fichiers de clé privée. La phrase secrète peut être vide, mais pas recommandée. La phrase secrète fonctionne avec le fichier de clé pour fournir une authentification à deux facteurs.
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in C:\Users\username/.ssh/id_rsa.
Your public key has been saved in C:\Users\username/.ssh/id_rsa.pub.
The key fingerprint is:
SHA256:FHK6WjcUkcfQjdorarzlak1Ob/x7AmqQmmx5ryYYV+8 username@LOCAL-HOSTNAME
The key's randomart image is:
+---[RSA 3072]----+
| . ** o |
| +.o= . |
| . o+ |
| .+. . |
| .ooS . |
| . .oo.=.o |
| =.= O.= . |
| . B BoE + . . |
| . *+*o. .o+ |
+----[SHA256]-----+
Vous disposez désormais d’une paire de clés RSA publique/privée à l’emplacement spécifié. Les fichiers .pub sont des clés publiques, tandis que les fichiers sans extension sont des clés privées :
Mode LastWriteTime Length Name
---- ------------- ------ ----
-a---- 10/11/2022 6:29 PM 2610 id_rsa
-a---- 10/11/2022 6:29 PM 578 id_rsa.pub
Important
Ne partagez jamais le contenu de votre clé privée. Si la clé privée est compromise, les personnes malveillantes peuvent l’utiliser pour inciter les serveurs à penser que la connexion vient de vous. Les fichiers de clé privée sont l'équivalent d'un mot de passe et doivent être protégés de la même manière.
Étape 2 : Ajouter la clé publique à Azure DevOps
Associez la clé publique générée à l’étape précédente à votre ID d’utilisateur.
Remarque
Vous devez répéter cette opération pour chaque organisation à laquelle vous avez accès et avec laquelle vous souhaitez utiliser SSH.
Ouvrez vos paramètres de sécurité en accédant au portail Web et en sélectionnant l'icône à côté de l'avatar en haut à droite de l'interface utilisateur. Sélectionnez les clés publiques SSH dans le menu qui s’affiche.
Sélectionnez + Nouvelle clé.
Copiez le contenu de la clé publique (par exemple,
id_rsa.pub
) que vous avez générée dans le champ Données de clé publique.Important
Évitez d’ajouter des espaces ou de nouvelles lignes dans le champ Données clés, car ils pourraient amener Azure DevOps à utiliser une clé publique non valide. Lors du collage dans la clé, une nouvelle ligne est souvent ajoutée à la fin. Veillez à supprimer cette ligne si elle se produit.
Donnez à la clé une description utile (cette description est affichée sur la page des clés publiques SSH de votre profil) afin que vous puissiez vous en souvenir plus tard. Sélectionnez Enregistrer pour stocker la clé publique. Une fois enregistré, vous ne pouvez pas modifier la clé. Vous pouvez supprimer la clé ou créer une entrée pour une autre clé. Il n’existe aucune restriction quant au nombre de clés que vous pouvez ajouter à votre profil utilisateur. Notez également que les clés SSH stockées dans Azure DevOps expirent au bout d'un an. Si votre clé expire, vous pouvez charger une nouvelle clé ou la même pour continuer à accéder à Azure DevOps via SSH.
Sur la page de vue d’ensemble SSH Public Keys, les empreintes digitales du serveur sont affichées. Prenez note de l’empreinte digitale SHA256 à utiliser lors de votre première connexion à Azure DevOps via SSH.
Testez la connexion en exécutant la commande suivante :
ssh -T git@ssh.dev.azure.com
Si vous vous connectez pour la première fois, vous devriez recevoir la sortie suivante :
The authenticity of host 'ssh.dev.azure.com (<IP>)' can't be established. RSA key fingerprint is SHA256:ohD8VZEXGWo6Ez8GSEJQ9WpafgLFsOfLOtGGQCQo6Og. This key is not known by any other names Are you sure you want to continue connecting (yes/no/[fingerprint])?
Comparez l’empreinte digitale avec l’empreinte digitale SHA256 affichée sur la page SSH Public Keys mentionnée précédemment. Ne procédez que s'ils correspondent !
Entrez
yes
pour continuer. Si tout est configuré correctement, le résultat devrait ressembler à ceci :Warning: Permanently added 'ssh.dev.azure.com' (RSA) to the list of known hosts. remote: Shell access is not supported. shell request failed on channel 0
Sinon, consultez la section Questions et dépannage.
Étape 3 : Cloner le référentiel Git avec SSH
Remarque
Pour utiliser SSH avec un référentiel préalablement cloné via HTTPS, consultez mettre à jour vos télécommandes vers SSH.
Copiez l’URL du clone SSH à partir du portail web. Dans cet exemple, l'URL du clone SSH concerne un dépôt dans une organisation nommée fabrikam-fiber, comme l'indique la première partie de l'URL après
dev.azure.com
.Remarque
Avec Azure DevOps Services, le format de l’URL du projet est
dev.azure.com/{your organization}/{your project}
. Toutefois, le format précédent qui fait référence au formatvisualstudio.com
est toujours pris en charge. Pour plus d’informations, consultez Présentation d’Azure DevOps, Changer d’organisation existante pour utiliser la nouvelle URL de nom de domaine.Exécutez
git clone
à partir de l’invite de commandes.git clone git@ssh.dev.azure.com:v3/fabrikam-fiber/FabrikamFiber/FabrikamFiber
Si vous n’utilisez pas d’agent SSH, vous êtes invité à entrer votre phrase secrète :
Cloning into 'FabrikamFiber'... Enter passphrase for key '/c/Users/username/.ssh/id_rsa': remote: Azure Repos remote: Found 127 objects to send. (50 ms) Receiving objects: 100% (127/127), 56.67 KiB | 2.58 MiB/s, done. Resolving deltas: 100% (15/15), done.
Si vous êtes invité à vérifier une empreinte digitale, veuillez lire Étape 2 : Ajouter à nouveau la clé publique à Azure DevOps. Pour d’autres problèmes, lisez la section Questions et dépannage.
Conseil
Pour tirer le meilleur parti de SSH, il est courant d'utiliser un agent SSH pour gérer votre ou vos clés SSH. La configuration d’un agent dépasse cependant le cadre de cet article.
Questions et résolution des problèmes
Q : Je vois des avertissements liés à ssh-rsa. Que dois-je faire ?
R : vous êtes susceptibles de vois deux messages d’avertissement différents :
ssh-rsa is about to be deprecated and your request has been throttled. Please use rsa-sha2-256 or rsa-sha2-512 instead. Your session will continue automatically. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.
Or
You’re using ssh-rsa that is about to be deprecated and your request has been blocked intentionally. Any SSH session using ssh-rsa is subject to brown out (failure during random time periods). Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.
Si vous avez modifié votre configuration SSH pour rétrograder vos paramètres de sécurité pour Azure DevOps en ajoutant ce qui suit à votre fichier ~/.ssh/config
(%UserProfile%\.ssh\config
sous Windows) :
Host ssh.dev.azure.com vs-ssh.visualstudio.com
HostkeyAlgorithms +ssh-rsa
Supprimez ces lignes maintenant et assurez-vous que rsa-sha2-256
et/ou rsa-sha2-512
sont autorisés.
Pour plus d’informations, consultez le billet de blog.
Q : SSH ne parvient pas à établir une connexion. Que dois-je faire ?
R : Vous êtes susceptible de rencontrer plusieurs problèmes différents :
Utilisation de ssh-rsa non pris en charge
You’re using ssh-rsa that is unsupported. Please use rsa-sha2-256 or rsa-sha2-512 instead. For more details see https://devblogs.microsoft.com/devops/ssh-rsa-deprecation.
Si vous avez modifié votre configuration SSH pour rétrograder vos paramètres de sécurité pour Azure DevOps en ajoutant ce qui suit à votre fichier
~/.ssh/config
(%UserProfile%\.ssh\config
sous Windows) :Host ssh.dev.azure.com vs-ssh.visualstudio.com HostkeyAlgorithms +ssh-rsa
Supprimez ces lignes maintenant et assurez-vous que
rsa-sha2-256
et/oursa-sha2-512
sont autorisés.Pour plus d’informations, consultez le billet de blog.
Aucune clé hôte correspondante
Ce problème ne devrait pas se produire sur Azure DevOps Service ou sur des versions plus récentes d’Azure DevOps Server comme mentionné dans l’article de blog.
Unable to negotiate with <IP> port 22: no matching host key type found. Their offer: ssh-rsa
Modifiez votre configuration SSH pour rétrograder vos paramètres de sécurité pour Azure DevOps en ajoutant ce qui suit à votre fichier
~/.ssh/config
(%UserProfile%\.ssh\config
sous Windows) :Host ssh.dev.azure.com vs-ssh.visualstudio.com HostkeyAlgorithms +ssh-rsa
Important
OpenSSH a rendu obsolète l'algorithme de signature à clé publique
ssh-rsa
dans la version 8.2 et l'a désactivé par défaut dans la version 8.8.Aucun MAC correspondant
Unable to negotiate with <IP> port 22: no matching MAC found. Their offer: hmac-sha2-256,hmac-sha2-512
Modifiez votre configuration SSH pour rétrograder vos paramètres de sécurité pour Azure DevOps en ajoutant ce qui suit à votre fichier
~/.ssh/config
(%UserProfile%\.ssh\config
sous Windows) :Host ssh.dev.azure.com vs-ssh.visualstudio.com MACs +hmac-sha2-512,+hmac-sha2-256
Aucune méthode d’échange de clé correspondante
Unable to negotiate with <IP> 22: no matching key exchange method found. Their offer: diffie-hellman-group1-sha1,diffie-hellman-group14-sha1,diffie-hellman-group-exchange-sha256
Modifiez votre configuration SSH pour rétrograder vos paramètres de sécurité pour Azure DevOps en ajoutant ce qui suit à votre fichier
~/.ssh/config
(%UserProfile%\.ssh\config
sous Windows) :Host ssh.dev.azure.com vs-ssh.visualstudio.com KexAlgorithms +diffie-hellman-group-exchange-sha256,+diffie-hellman-group14-sha1,+diffie-hellman-group1-sha1
Important
L'algorithme d'échange de clés
diffie-hellman-group1-sha1
a été désactivé par défaut dans la version 6.9 d'OpenSSH etdiffie-hellman-group14-sha1
dans la version 8.2.
Conseil
Pour les instances auto-hébergées d'Azure DevOps Server et de TFS, utilisez le nom d'hôte approprié dans la ligne Host
au lieu de ssh.dev.azure.com vs-ssh.visualstudio.com
.
Q : Comment puis-je faire en sorte que Git se souvienne de la phrase secrète de ma clé ?
R : Vous pouvez utiliser un agent SSH. Linux, macOS et Windows (à partir de Windows 10 (build 1809) ou en utilisant Git pour Windows avec Git Bash) sont tous livrés avec un agent SSH. L'agent SSH peut être utilisé pour mettre en cache vos clés SSH pour une utilisation répétée. Consultez le manuel de votre fournisseur SSH pour savoir comment l’utiliser.
Q : J’utilise PuTTY comme client SSH et j’ai généré mes clés avec PuTTYgen. Puis-je utiliser ces clés avec Azure DevOps Services ?
R : Oui. Chargez la clé privée avec PuTTYgen, accédez au menu Conversions et sélectionnez Exporter la clé OpenSSH. Enregistrez le fichier de clé privée, puis suivez les étapes pour configurer des clés non définies. Copiez votre clé publique directement à partir de la fenêtre PuTTYgen et collez-la dans le champ Données clés dans vos paramètres de sécurité.
Q : Comment puis-je vérifier que la clé publique que j'ai téléchargée est la même que ma clé locale ?
R : Vous pouvez vérifier l'empreinte digitale de la clé publique téléchargée avec celle affichée dans votre profil via la commande suivante ssh-keygen
exécutée sur votre clé publique à l'aide de la ligne de commande. Vous devez modifier le chemin et le nom du fichier de clé publique si vous n’utilisez pas les valeurs par défaut.
Remarque
Depuis août/septembre 2024, nous migreons de MD5 vers des hachages SHA-256. Vous devrez peut-être choisir la fonction appropriée pendant la période de transition.
ssh-keygen -l -E md5 -f <path_to_your_public_key> -- use this for MD5 fingerprints
ssh-keygen -l -E sha256 -f <path_to_your_public_key> -- use this for SHA-256 fingerprints
Vous pouvez ensuite comparer la signature à celle de votre profil. Cette vérification est utile si vous rencontrez des problèmes de connexion ou si vous avez des inquiétudes concernant le collage incorrect de la clé publique dans le champ Données de clé lors de l’ajout de la clé à Azure DevOps.
Q : Comment puis-je commencer à utiliser SSH dans un référentiel dans lequel j'utilise actuellement HTTPS ?
R : Vous devez mettre à jour la télécommande origin
dans Git pour passer d’une URL HTTPS à une URL SSH. Une fois que vous avez l’URL du clone SSH, exécutez la commande suivante :
git remote set-url origin <SSH URL to your repository>
Les commandes Git accédant à la télécommande appelée origin
utilisent désormais SSH.
Q : J’utilise Git LFS avec Azure DevOps Services et j’obtiens des erreurs lors de l’extraction de fichiers suivis par Git LFS.
R : Azure DevOps Services ne prend actuellement pas en charge LFS via SSH. Utilisez HTTPS pour vous connecter aux dépôts avec des fichiers suivis Git LFS.
Q : Comment puis-je utiliser un emplacement de clé non définie, autrement dit, pas ~/.ssh/id_rsa et ~/.ssh/id_rsa.pub ?
R : Pour utiliser une clé stockée à un emplacement différent de celui par défaut, effectuez ces deux tâches :
Les clés doivent se trouver dans un dossier que vous pouvez uniquement lire ou modifier. Si le dossier dispose d’autorisations plus larges, SSH n’utilise pas les clés.
Vous devez indiquer à SSH l’emplacement de la clé, par exemple en le spécifiant comme « Identité » dans la configuration SSH :
Host ssh.dev.azure.com IdentityFile ~/.ssh/id_rsa_azure IdentitiesOnly yes
Le paramètre IdentitiesOnly yes
garantit que SSH n’utilise aucune autre identité disponible pour s’authentifier. Ce paramètre est particulièrement important si plusieurs identités sont disponibles.
Q : J’ai plusieurs clés SSH. Comment utiliser la bonne clé SSH pour Azure DevOps ?
R : En général, lorsque vous configurez plusieurs clés pour un client SSH, le client tente de s’authentifier avec chaque clé séquentiellement jusqu’à ce que le serveur SSH en accepte une.
Cependant, cette approche ne fonctionne pas avec Azure DevOps en raison de contraintes techniques liées au protocole SSH et à la structure de nos URLs Git SSH. Azure DevOps accepte la première clé fournie par le client lors de l’authentification. Si cette clé est invalide pour le référentiel demandé, la demande échoue sans tenter d’autres clés disponibles, ce qui entraîne l’erreur suivante :
remote: Public key authentication failed.
fatal: Could not read from remote repository.
Pour Azure DevOps, vous devez configurer SSH pour utiliser explicitement un fichier de clé spécifique. La procédure est la même que lors de l’utilisation d’une clé stockée dans un emplacement nondefault. Dites à SSH d’utiliser la clé SSH correcte pour l’hôte Azure DevOps.
Q : Comment utiliser différentes clés SSH pour différentes organisations sur Azure DevOps ?
R : Azure DevOps accepte aveuglément la première clé que le client fournit lors de l’authentification. Si cette clé est invalide pour le référentiel demandé, la demande échoue avec l’erreur suivante :
remote: Public key authentication failed.
fatal: Could not read from remote repository.
Cet échec est dû au fait que toutes les URLs Azure DevOps partagent le même nom d’hôte (ssh.dev.azure.com
), ce qui rend impossible pour SSH de les distinguer par défaut. Cependant, vous pouvez modifier votre configuration SSH pour différencier les différentes organisations en fournissant des clés distinctes pour chacune. Utilisez des alias d’hôte pour créer des sections Host
séparées dans votre fichier de configuration SSH.
# The settings in each Host section are applied to any Git SSH remote URL with a
# matching hostname.
# Generally:
# * SSH uses the first matching line for each parameter name, e.g. if there's
# multiple values for a parameter across multiple matching Host sections
# * "IdentitiesOnly yes" prevents keys cached in ssh-agent from being tried before
# the IdentityFile values we explicitly set.
# * On Windows, ~/.ssh/your_private_key maps to %USERPROFILE%\.ssh\your_private_key,
# e.g. C:\Users\<username>\.ssh\your_private_key.
# Imagine that we have the following two SSH URLs:
# * git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo
# * For this, we want to use `fabrikamkey`, so we'll create `devops_fabrikam` as
# a Host alias and tell SSH to use `fabrikamkey`.
# * git@ssh.dev.azure.com:v3/Contoso/Project2/con_repo
# * For this, we want to use `contosokey`, so we'll create `devops_contoso` as
# a Host alias and tell SSH to use `contosokey`.
#
# To set explicit keys for the two host aliases and to tell SSH to use the correct
# actual hostname, add the next two Host sections:
Host devops_fabrikam
HostName ssh.dev.azure.com
IdentityFile ~/.ssh/private_key_for_fabrikam
IdentitiesOnly yes
Host devops_contoso
HostName ssh.dev.azure.com
IdentityFile ~/.ssh/private_key_for_contoso
IdentitiesOnly yes
Ensuite, au lieu d'utiliser les vraies URL, indiquez à Git que vous souhaitez utiliser ces URL pour chaque référentiel comme distant en remplaçant le nom d'hôte dans les distants existants par devops_fabrikam
et devops_contoso
respectivement. Par exemple, git@ssh.dev.azure.com:v3/Fabrikam/Project1/fab_repo
deviendrait git@devops_fabrikam:v3/Fabrikam/Project1/fab_repo
.
Q : Quelles notifications puis-je recevoir sur mes clés SSH ?
R : Chaque fois que vous enregistrez une nouvelle clé SSH avec Azure DevOps Services, vous recevez une notification par e-mail vous informant qu’une nouvelle clé SSH a été ajoutée à votre compte.
Q : Que dois-je faire si je crois que quelqu’un autre que moi ajoute des clés SSH sur mon compte ?
R : Si vous recevez une notification d’enregistrement de clé SSH que vous n’avez pas initiée, vos identifiants pourraient être compromis.
La prochaine étape serait d’enquêter pour savoir si votre mot de passe est compromis ou non. La modification de votre mot de passe constitue toujours une bonne première étape pour se défendre contre ce vecteur d’attaque. Si vous êtes un utilisateur de Microsoft Entra, parlez avec votre administrateur pour vérifier si votre compte a été utilisé à partir d'une source/emplacement inconnu.
Q : Que dois-je faire si on me demande toujours mon mot de passe GIT_SSH_COMMAND="ssh -v" git fetch
et affiche no mutual signature algorithm
ou corresponding algo not in PubkeyAcceptedAlgorithms
?
R : Certaines distributions Linux, telles que Fedora Linux, ont des stratégies de chiffrement qui nécessitent des algorithmes de signature SSH plus forts que les supports Azure DevOps (à compter de janvier 2021). Il existe une requête de fonctionnalité ouverte pour ajouter cette prise en charge.
Vous pouvez contourner le problème en ajoutant le code suivant à votre configuration SSH (~/.ssh/config
) :
Host ssh.dev.azure.com vs-ssh.visualstudio.com
PubkeyAcceptedKeyTypes +ssh-rsa
Conseil
Pour les instances auto-hébergées d'Azure DevOps Server et de TFS, utilisez le nom d'hôte approprié dans la ligne Host
au lieu de ssh.dev.azure.com vs-ssh.visualstudio.com
.