Partager via


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) :

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.

  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.

    Capture d’écran illustrant l’élément de menu Clés publiques SSH et l’avatar de l’utilisateur sélectionné dans Azure DevOps.

  2. Sélectionnez + Nouvelle clé.

    Capture d’écran illustrant l’accès au menu Configuration de la sécurité dans Azure DevOps.

  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.

    Capture d’écran illustrant la configuration d’une clé publique dans Azure DevOps.

  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.

    Capture d’écran de l’accès à la configuration de la sécurité dans Azure DevOps Services.

  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

Remarque

Pour utiliser SSH avec un référentiel préalablement cloné via HTTPS, consultez mettre à jour vos télécommandes vers 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.

    Capture d’écran illustrant l’URL clonée SSH Azure Repos

    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.

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

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.

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 :

  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.

Exemple de notification SSH

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.