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.

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

Étape 1 : Créer 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é.

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

É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.

1. 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.

   

2. Sélectionnez + Nouvelle clé.

   

3. 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.

   

4. 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.

5. 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.

   

6. 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 !

7. 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

1. 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 format visualstudio.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.

2. 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.

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/ou rsa-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 et diffie-hellman-group14-sha1 dans la version 8.2.

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.

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 :

1. 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.

2. 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