Résoudre les erreurs d'authentification Git courantes avec SSH et les jetons
Les erreurs d'authentification sont une source courante de frustration pour les utilisateurs de Git, en particulier lors du clonage, du pull ou du push de code. Les échecs persistants, se manifestant souvent par fatal: Authentication failed ou des messages 403 Forbidden, indiquent que Git ne peut pas vérifier votre identité de manière sécurisée auprès du service d'hébergement distant (comme GitHub, GitLab ou Bitbucket).
Ce guide complet aborde les raisons principales derrière ces échecs. Nous irons au-delà des simples invites de nom d'utilisateur/mot de passe – qui sont maintenant largement obsolètes – pour nous concentrer sur des méthodes d'authentification modernes et sécurisées : les clés SSH et les jetons d'accès personnels (PATs). Maîtriser ces techniques est essentiel pour un flux de travail de développement fiable, garantissant que vos identifiants sont à la fois sécurisés et correctement reconnus par votre fournisseur Git.
1. Diagnostiquer les indicateurs d'échec d'authentification
Avant de mettre en œuvre une solution, il est crucial de comprendre pourquoi Git échoue. Les erreurs d'authentification proviennent généralement de deux sources principales : des identifiants expirés ou révoqués, ou l'utilisation du mauvais protocole (HTTPS ou SSH) pour les identifiants stockés.
Messages d'erreur courants
- 403 Forbidden : Cela signifie généralement que votre tentative de connexion a réussi, mais que les identifiants fournis (mot de passe ou jeton) n'ont pas les autorisations nécessaires pour effectuer l'opération.
fatal: Authentication failed for 'https://...': Indique que Git a tenté d'utiliser des identifiants stockés (souvent via un assistant d'authentification) mais qu'ils étaient invalides, ou qu'aucun identifiant valide n'a été trouvé.- Boucle d'invite de mot de passe : Si vous êtes invité à plusieurs reprises à entrer un mot de passe via HTTPS, cela signifie souvent que votre fournisseur d'hébergement n'accepte plus les mots de passe pour les opérations Git, nécessitant un jeton d'accès personnel à la place.
Identifier votre type de connexion
Git s'authentifie différemment selon le schéma d'URL distante. Vérifiez l'URL distante de votre dépôt :
git remote -v
| Schéma d'URL | Méthode d'authentification requise |
|---|---|
https://github.com/user/repo.git |
Jeton d'accès personnel (PAT) via HTTPS |
[email protected]:user/repo.git |
Paire de clés SSH |
Si vous aviez l'intention d'utiliser SSH mais que l'URL distante est HTTPS, ou vice-versa, vous devez soit modifier l'URL, soit changer de méthode d'authentification.
Pour passer de HTTPS à SSH :
git remote set-url origin [email protected]:USERNAME/REPOSITORY.git
2. Solution 1 : Établir l'authentification par clé SSH
Les clés SSH offrent le moyen le plus sécurisé et le plus simple de s'authentifier auprès des services Git, ne nécessitant aucune invite de mot de passe ultérieure après la configuration initiale. Elles reposent sur une paire de clés publique/privée.
2.1 Vérification des clés SSH existantes
Vérifiez si vous avez déjà une paire de clés SSH générée sur votre machine :
ls -al ~/.ssh
Recherchez des fichiers nommés id_rsa, id_ed25519, ou similaires, associés à un fichier .pub correspondant (la clé publique).
2.2 Génération d'une nouvelle paire de clés SSH
Si aucune clé appropriée n'existe, générez-en une nouvelle. Ed25519 est l'algorithme moderne recommandé, bien que RSA 4096 bits soit également sécurisé.
# Générer une clé Ed25519
ssh-keygen -t ed25519 -C "[email protected]"
# Suivez les invites. Il est fortement recommandé d'utiliser une phrase secrète forte.
2.3 Enregistrement de la clé publique auprès de votre hôte Git
La clé publique doit être enregistrée auprès de votre hôte Git (par exemple, paramètres GitHub, paramètres GitLab).
- Copiez le contenu de la clé publique dans votre presse-papiers :
bash cat ~/.ssh/id_ed25519.pub - Accédez aux paramètres de votre service d'hébergement et trouvez la section pour les clés SSH.
- Collez le contenu entier du fichier de clé publique dans le champ d'enregistrement de la clé.
2.4 Test de la connexion SSH
Après l'enregistrement, testez la connexion pour vous assurer que l'hôte reconnaît votre clé. Utilisez la commande suivante, en remplaçant github.com si nécessaire :
ssh -T [email protected]
En cas de succès, vous recevrez un message de bienvenue confirmant votre authentification, tel que : Hi USERNAME! You've successfully authenticated...
Astuce : Si la connexion échoue, assurez-vous que votre agent SSH est en cours d'exécution et qu'il a chargé votre clé. Utilisez
eval "$(ssh-agent -s)"suivi dessh-add ~/.ssh/id_ed25519(ou le chemin de votre clé).
3. Solution 2 : Utilisation des jetons d'accès personnels (PATs) pour HTTPS
Si vous préférez continuer à utiliser les URL distantes HTTPS (ou si vous ne pouvez pas utiliser SSH), vous devez utiliser un jeton d'accès personnel (PAT) au lieu de votre mot de passe de compte. C'est une exigence cruciale sur les principales plateformes depuis 2021.
3.1 Génération du jeton d'accès personnel
Les PATs sont générés directement dans les paramètres de sécurité de votre hôte Git.
- Accédez aux paramètres : Allez dans les paramètres de votre profil, généralement sous
Developer SettingsouAccess Tokens. - Générez un nouveau jeton : Fournissez un nom descriptif et définissez une date d'expiration (il est recommandé de définir une expiration, par exemple 90 jours).
- Définissez les étendues (Scopes) : Surtout, attribuez les autorisations nécessaires (scopes). Pour un accès général au dépôt, vous avez généralement besoin de l'étendue
repo. - Enregistrez le jeton : Une fois généré, copiez immédiatement le jeton. Il ne sera plus affiché.
Attention : Traitez votre PAT comme un mot de passe. S'il est compromis, il accorde un accès complet aux étendues que vous avez attribuées.
3.2 Utilisation du PAT
Lors d'une opération Git via HTTPS, il vous sera demandé votre nom d'utilisateur et votre mot de passe.
| Invite | Valeur à saisir |
|---|---|
| Nom d'utilisateur : | Votre nom d'utilisateur Git réel |
| Mot de passe : | La chaîne complète du jeton d'accès personnel (PAT) |
Une fois saisi, Git stockera généralement ce jeton en toute sécurité à l'aide d'un assistant d'authentification (voir Section 4).
4. Gérer les identifiants avec les assistants d'authentification
Saisir à plusieurs reprises de longs PATs est peu pratique. Les assistants d'authentification de Git mettent en cache ou stockent de manière sécurisée vos informations d'authentification afin que vous n'ayez à les saisir qu'une seule fois.
4.1 Configuration de l'assistant d'authentification par défaut
Les assistants d'authentification gèrent la manière dont Git enregistre vos informations d'authentification. Les méthodes les plus sécurisées utilisent le stockage sécurisé natif du système d'exploitation.
Pour macOS : Utilisez l'assistant Trousseau d'accès (souvent activé par défaut) :
git config --global credential.helper osxkeychain
Pour Windows : Utilisez le Gestionnaire d'informations d'identification Windows :
git config --global credential.helper manager
Pour Linux : L'assistant cache peut stocker temporairement les identifiants, mais l'assistant store les stocke non chiffrés (à utiliser avec prudence).
# Met en cache les identifiants en mémoire pendant 1 heure (3600 secondes)
git config --global credential.helper 'cache --timeout=3600'
4.2 Réinitialisation des identifiants stockés
Si vos erreurs d'authentification persistent, l'identifiant existant stocké (mais invalide) est probablement le coupable. Vous devez effacer les identifiants stockés pour forcer Git à vous demander à nouveau le PAT.
Si vous utilisez le Trousseau d'accès macOS :
- Ouvrez l'application Trousseau d'accès.
- Recherchez
github.comou votre hôte Git. - Supprimez l'entrée de mot de passe internet correspondante.
Si vous utilisez le Gestionnaire d'informations d'identification Windows :
- Ouvrez le Panneau de configuration et accédez au Gestionnaire d'informations d'identification.
- Sous Informations d'identification Windows, recherchez les informations d'identification génériques liées à
git:https://...ou à votre domaine d'hôte. - Supprimez l'entrée.
Après avoir effacé les anciens identifiants, la prochaine opération Git (par exemple, git pull) vous invitera à saisir le nom d'utilisateur et le nouveau PAT, que l'assistant stockera ensuite en toute sécurité.
Résumé et prochaines étapes
Résoudre les erreurs d'authentification Git persistantes revient à s'assurer que vous utilisez un type d'identifiant moderne et pris en charge (clé SSH ou PAT) qui correspond à votre protocole d'URL distante (SSH ou HTTPS).
| Si l'erreur persiste... | Action |
|---|---|
| 403 Forbidden | Vérifiez les étendues du PAT ou les permissions de la clé SSH sur l'hôte. |
| Invites répétées (HTTPS) | Générez un jeton d'accès personnel (PAT) et assurez-vous que l'assistant d'authentification le stocke correctement. |
| La clé SSH échoue | Confirmez que la clé publique est enregistrée et que ssh-agent est en cours d'exécution et chargé avec la clé privée. |
En suivant ces étapes, vous pouvez éliminer les erreurs d'identifiants, ce qui conduit à un flux de travail Git plus fluide et plus sécurisé.