Utiliser l’authentification par clé SSH

  • Article

Azure DevOps Services | Azure DevOps Server 2022 | Azure DevOps Server 2019

Vous pouvez vous connecter à vos référentiels Git via SSH sur macOS, Linux ou Windows et vous connecter en toute sécurité à l’aide de l’authentification HTTPS.

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é, RSA 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 à l'aide de l'algorithme RSA, exécutez la commande suivante à partir d'un PowerShell ou d'un autre shell tel que bash sur votre client :

ssh-keygen

Le résultat de la commande doit afficher le résultat suivant (où username est remplacé par 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 serez invité à utiliser une phrase secrète pour chiffrer vos fichiers de clé privée. La phrase secrète peut être vide, mais elle n’est 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 présentation, une note s'affiche en haut contenant les empreintes digitales du serveur. Notez-les car ils seront requis 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 c'était la première connexion, vous devriez recevoir le résultat suivant :

    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 donnée avec les empreintes digitales proposées sur la page de paramètres susmentionnée. Ne procédez que s'ils correspondent !

    Si tout est configuré correctement, le résultat devrait ressembler à ceci :

    remote: Shell access is not supported.

    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

    Vous devriez maintenant être invité à saisir votre phrase secrète pour votre clé SSH avant de pouvoir continuer, sauf si elle est gérée par un agent SSH :

    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.

Vous avez peut-être déjà 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 assurez-vous que rsa-sha2-256 et/ou rsa-sha2-512 sont autorisés.

Pour plus d’informations, veuillez consulter ce blog post.

Q : SSH ne parvient pas à établir une connexion. Que dois-je faire ?

R : Vous pouvez 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.

    Vous avez peut-être déjà 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 assurez-vous que rsa-sha2-256 et/ou rsa-sha2-512 sont autorisés.

    Pour plus d’informations, veuillez consulter ce blog post.

  • Aucune clé hôte correspondante

    Cela ne doit se produire ni sur Azure DevOps Service ni sur les versions plus récentes d’Azure DevOps Server, comme expliqué dans le blog post.

    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 pour cela. 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. Veuillez consulter le manuel de votre fournisseur SSH pour plus de détails sur la façon de 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 par défaut. 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 devrez 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 ~/.ssh/id_rsa.pub

Vous pouvez ensuite comparer la signature MD5 à 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 devrez 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 utiliseront 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é autre que celui par défaut, c'est-à-dire 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'utilisera pas les clés.

  2. Vous devez indiquer à SSH l'emplacement de la clé, par ex. 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’utilisera aucune autre identité disponible pour s’authentifier. Ceci 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 règle générale, si vous configurez plusieurs clés pour un client SSH et que vous vous connectez à un serveur SSH, le client peut essayer les clés une à la fois jusqu’à ce que le serveur en accepte un.

Toutefois, cela ne fonctionne pas avec Azure DevOps pour des raisons techniques liées au protocole SSH et à la façon dont nos URL SSH Git sont structurées. Azure DevOps accepte aveuglément la première clé que le client fournit lors de l’authentification. Si cette clé n'est pas valide pour le référentiel demandé, la requête échouera sans essayer d'autres clés disponibles en raison de 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 autre que celui par défaut. Dites simplement à 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 acceptera aveuglément la première clé fournie par le client lors de l'authentification. Si cette clé n'est pas valide pour le référentiel demandé, la requête échouera avec l'erreur suivante :

remote: Public key authentication failed.
fatal: Could not read from remote repository.

Cependant, vous pouvez modifier votre configuration SSH pour différencier les différentes organisations et fournir des clés différentes pour chacune. Pour ce faire, vous devrez utiliser des alias d'hôte pour créer des sections Host distinctes dans votre configuration SSH. En effet, toutes les URL Azure DevOps hébergées ont le même nom d’hôte (ssh.dev.azure.com), SSH n’a donc aucun moyen de les distinguer par défaut.

# 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, cela 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 auprès d'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 concernant l'enregistrement d'une clé SSH et que vous ne l'avez pas téléchargée manuellement sur le service, vos informations d'identification peuvent avoir été compromises.

L’étape suivante consiste à déterminer si votre mot de passe a été 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.