3.1 : S'authentifier au quotidien : jetons et gestionnaires d'identifiants

Où nous en sommes

Vous savez depuis la leçon 2.8 pourquoi un jeton est nécessaire : Git est un client non interactif, incapable de suivre les redirections d’un fournisseur d’identité. Il ne connaît que l’authentification HTTP basique.

Cette leçon règle le comment, une bonne fois pour toutes. Une dizaine de minutes maintenant, et vous n’y penserez plus pendant des mois.


Créer votre jeton de travail

Paramètres utilisateur → Applications → Nouveau jeton d’accès.

Trois blocs à renseigner.

1. Le nom du jeton

Nommez-le d’après la machine et l’usage, pas d’après vous :

poste-romain-portable
poste-romain-vscode
srv-deploy01-lecture

Le nom n’est pas décoratif — et il l’est d’autant moins que, comme nous allons le voir, rien d’autre ne vous aidera à faire le tri plus tard. Le jour où un poste sera volé, c’est lui qui vous dira quel jeton révoquer sans casser les autres.

2. L’accès aux dépôts et organisations

Premier niveau de portée : sur quelles ressources le jeton peut agir.

Option Effet
Tout (public, privé et limité) Accès à toutes vos ressources
Publique uniquement Limité aux dépôts et organisations publics — les autorisations d’administration sont désactivées
Dépôts spécifiques Limité à une liste que vous choisissez

La troisième option est celle qui nous intéressera le plus dans cette formation. Forgejo précise qu’avec elle, seules les permissions liées aux dépôts et aux tickets peuvent être activées, et que les autorisations d’administration sont désactivées d’office. Autrement dit : c’est le mécanisme qui permet de créer un jeton limité à un seul dépôt — celui dont vos serveurs auront besoin en sections 8 et 12.

Pour votre jeton de travail quotidien, Tout est le choix pratique.

3. Les autorisations

Second niveau : quelles actions sont permises, catégorie par catégorie.

Forgejo présente une liste de domaines — repository, package, issue, organization, user, notification, admin, misc, activitypub — chacun avec une liste déroulante, positionnée par défaut sur Aucun accès.

C’est un bon défaut : vous partez de zéro et vous ouvrez uniquement ce qui est nécessaire.

Usage Autorisation à ouvrir
Cloner et pousser depuis votre poste repository en écriture
Un serveur qui ne fait que récupérer des scripts repository en lecture
Récupérer une image du registre package en lecture
Publier une image package en écriture

Ne touchez pas à admin. Un jeton de travail quotidien, mémorisé dans un gestionnaire d’identifiants, ne devrait jamais pouvoir administrer votre forge.

⚠️ Pas de date d’expiration

Contrairement à d’autres forges, Forgejo ne propose pas de fixer une durée de vie au jeton. Une fois créé, il reste valide jusqu’à ce que vous le supprimiez.

Cela a une conséquence directe : le nommage et la revue périodique ne sont pas des conseils de confort, ce sont vos seuls garde-fous. Un jeton oublié ne mourra jamais de lui-même. Nous y revenons en fin de leçon, et nous en ferons un point de contrôle régulier en section 14.

Copiez-le tout de suite

Le jeton s’affiche une seule fois. Forgejo n’en conserve ensuite qu’une empreinte : personne ne pourra le relire, pas même vous.

Collez-le immédiatement dans votre gestionnaire de mots de passe. Si vous le perdez, ce n’est pas grave — vous en générerez un autre — mais autant s’épargner l’aller-retour.


Le premier clone

Reprenez le dépôt scripts-powershell créé en TP 2, et clonez-le :

git clone https://forge.nordika.local/infrastructure/scripts-powershell.git

Git demande deux informations :

Username for 'https://forge.nordika.local': romain.dupont
Password for 'https://[email protected]':

Identifiant : le vôtre, celui de la forge. Mot de passe : le jeton, pas votre mot de passe.

Rien ne s’affiche pendant la saisie — c’est normal, collez et validez.

Si le clone réussit, l’essentiel est fait. Reste à ce que Git s’en souvienne.


Où le jeton est mémorisé

Sans configuration, Git redemande les identifiants à chaque opération. Insupportable au bout de trois minutes.

Le mécanisme qui les mémorise s’appelle un credential helper. Il en existe un adapté à chaque environnement.

Vérifiez d’abord celui qui est actif :

git config --get credential.helper

Sur Windows

Le Git Credential Manager, installé avec Git for Windows en leçon 1.6, est normalement déjà configuré. Si la commande précédente ne renvoie rien :

git config --global credential.helper manager

Le jeton est stocké dans le Gestionnaire d’identifiants Windows, chiffré au niveau de votre profil. Vous pouvez le vérifier : Panneau de configuration → Gestionnaire d’identifiants → Informations d’identification Windows. Une entrée git:https://forge.nordika.local doit y figurer.

C’est aussi là que vous irez la supprimer si besoin.

Sur Linux avec environnement graphique

Le trousseau du bureau prend le relais :

git config --global credential.helper libsecret

Selon votre distribution, l’assistant correspondant est fourni avec Git ou demande un paquet supplémentaire. Si la commande échoue avec un message du type git: 'credential-libsecret' is not a git command, cherchez le paquet correspondant dans votre gestionnaire — les noms varient d’une distribution à l’autre.

Sur macOS

git config --global credential.helper osxkeychain

Le jeton rejoint le trousseau du système.

Sur un serveur Linux sans interface

C’est le cas qui nous occupera en sections 8 et 12, et il mérite d’être traité correctement.

La solution temporaire — les identifiants restent en mémoire, puis disparaissent :

git config --global credential.helper 'cache --timeout=3600'

Utile pour une session de travail. Inadapté à une tâche planifiée qui s’exécute la nuit.

La solution persistante — et son inconvénient :

git config --global credential.helper store

Elle écrit le jeton en clair dans ~/.git-credentials. Ce n’est pas un défaut de conception : sans utilisateur devant l’écran pour saisir une phrase de passe, il n’y a rien pour chiffrer le fichier.

Les quatre mesures qui rendent la chose acceptable, vues en 2.8 :

# 1. Un compte de service dédié, pas votre compte personnel
# 2. Un jeton dédié à cette machine, en LECTURE SEULE
# 3. Des permissions restrictives
chmod 600 ~/.git-credentials
# 4. Une expiration, et une procédure de renouvellement notée

Ainsi, la fuite du fichier expose un droit de lecture sur un dépôt — un incident à traiter, pas une catastrophe.


Ce qu’il ne faut jamais faire

git clone https://romain:[email protected]/infra/scripts.git   # ❌

Le jeton se retrouve alors en clair dans .git/config, dans l’historique de votre shell, et potentiellement dans les journaux du serveur et du reverse proxy. C’est la manière la plus efficace de le diffuser à des gens qui n’auraient pas dû l’avoir.

Si vous héritez d’un dépôt configuré ainsi, corrigez l’adresse :

git remote set-url origin https://forge.nordika.local/infra/scripts.git

Puis considérez le jeton comme compromis et révoquez-le.


Renouveler ou changer un jeton

Un jour, sans prévenir :

remote: Invalid credentials
fatal: Authentication failed for 'https://forge.nordika.local/...'

Neuf fois sur dix, le jeton a expiré. Le réflexe est alors d’en générer un nouveau et de retenter — sauf que Git réutilise l’ancien, mémorisé, et échoue de nouveau. Il faut d’abord oublier l’entrée existante.

La méthode qui fonctionne partout, quel que soit le gestionnaire :

printf "protocol=https\nhost=forge.nordika.local\n\n" | git credential reject

La prochaine opération redemandera les identifiants. Saisissez le nouveau jeton.

Sur Windows, vous pouvez aussi supprimer l’entrée à la main dans le Gestionnaire d’identifiants. Avec le gestionnaire store, éditez simplement ~/.git-credentials. Avec le gestionnaire cache, git credential-cache exit vide la mémoire.


Les erreurs classiques

Symptôme Cause
Git redemande les identifiants à chaque commande Aucun credential helper configuré
Authentication failed alors que le jeton est neuf L’ancien jeton est encore mémorisé — utilisez git credential reject
Authentication failed avec le bon mot de passe Vous saisissez votre mot de passe et non le jeton
Ça fonctionne sur un dépôt, pas sur un autre La portée du jeton est insuffisante, ou vous n’avez pas les droits sur ce dépôt
403 au lieu de 401 Vous êtes authentifié, mais sans le droit d’écrire : question de permissions d’équipe
Erreur de certificat L’autorité interne n’est pas installée sur le poste — jamais sslVerify false

Distinguer 401 et 403 vous fera gagner du temps. 401 signifie « je ne sais pas qui vous êtes » : problème de jeton. 403 signifie « je sais qui vous êtes, et vous n’avez pas le droit » : problème d’équipe ou de portée. Le premier se règle dans vos identifiants, le second dans la forge.


Si vous avez activé SSH

Nous avons choisi le HTTPS exclusif en leçon 2.1. Si votre instance expose malgré tout le SSH, voici l’essentiel en cinq lignes.

Générez une paire de clés :

ssh-keygen -t ed25519 -C "romain@nordika"

Ajoutez le contenu de ~/.ssh/id_ed25519.pub dans Paramètres du compte → Clés SSH, puis testez :

ssh -T [email protected] -p 222

L’avantage sur un serveur est réel : la clé privée peut être protégée par une phrase de passe, et il n’y a pas de secret en clair dans un fichier de configuration Git. L’inconvénient l’est tout autant : un port supplémentaire à publier, et un protocole souvent bloqué par les proxys d’entreprise.


Bonne hygiène

Puisqu’un jeton ne meurt jamais tout seul, ces quatre habitudes sont votre seule ligne de défense.

Un jeton par machine. Plus long à créer, infiniment plus simple à révoquer : vous savez exactement ce que vous cassez.

La portée la plus étroite possible. Un serveur qui lit un dépôt n’a besoin que de « dépôts spécifiques » plus repository en lecture. Pas davantage.

Jamais de jeton partagé entre collègues. Un jeton porte votre identité : tout ce qui sera fait avec apparaîtra comme venant de vous, dans l’historique comme dans les journaux.

Une revue périodique. L’écran des applications affiche la date de dernière utilisation de chaque jeton. Un jeton inutilisé depuis six mois n’a probablement plus de raison d’être. Faute d’expiration automatique, c’est ce passage en revue qui joue ce rôle — nous en ferons un point de contrôle formel en section 14.

Et une révocation sans hésiter. Supprimer un jeton est instantané et sans effet de bord. Poste égaré, doute sur une manipulation, collègue parti : révoquez, recréez. Le coût est de deux minutes.


Ce qu’il faut retenir

  • Le jeton remplace le mot de passe pour toutes les opérations Git.
  • La portée se règle à deux niveaux : les ressources accessibles, puis les autorisations par catégorie.
  • « Dépôts spécifiques » permet de limiter un jeton à un seul dépôt — indispensable pour les accès machine.
  • Toutes les autorisations partent d’« Aucun accès » : n’ouvrez que le nécessaire, jamais admin.
  • Forgejo ne propose pas d’expiration : le nommage et la revue périodique sont vos seuls garde-fous.
  • Il ne s’affiche qu’une fois : copiez-le immédiatement.
  • Le credential helper évite de le ressaisir : manager sous Windows, libsecret sous Linux graphique, store sur un serveur.
  • Sur un serveur, store écrit en clair : jeton dédié, lecture seule, chmod 600.
  • Jamais de jeton dans l’URL d’un dépôt.
  • Après renouvellement, oubliez l’ancienne entrée avec git credential reject.
  • 401 = problème d’identité ; 403 = problème de droits.

Dans la leçon suivante

Vous êtes authentifié. Nous allons maintenant créer un dépôt sur la forge et y publier le travail réalisé en local lors du TP 1.

Deux chemins possibles selon que le dépôt existe déjà chez vous ou non — et un piège classique au milieu, celui du dépôt initialisé des deux côtés à la fois, qui produit un message d’erreur que tout le monde rencontre au moins une fois.