Connexion sécurisée

Pour les développeurs humains, la méthode de connexion Git recommandée est HTTPS + Git Credential Manager (GCM) : une connexion interactive via l’IdP de votre organisation, avec une MFA à chaque renouvellement du jeton. SSH est désactivé par défaut pour les nouvelles organisations fremforge ; les développeurs confirmés qui ont réellement besoin de SSH peuvent demander à l’administrateur de leur organisation de le réactiver. Cette page décrit la configuration de GCM pour macOS, Linux et Windows, ainsi qu’une section de repli pour SSH et les jetons d’accès personnels (PAT).

Pourquoi HTTPS + GCM est la méthode par défaut

GCM est l’assistant d’identifiants open source de Microsoft ; fremforge s’y intègre via le fournisseur OAuth2 intégré à Forgejo. Il fonctionne sur les postes de développement Windows, macOS et Linux.

HTTPS + Git Credential Manager (recommandé)

Étape 1 : installez GCM

# macOS via Homebrew
brew install --cask git-credential-manager

# Linux (Debian/Ubuntu, Fedora, etc. — see GCM repo for distro-specific paths)
curl -sL https://aka.ms/gcm/linux-install-source.sh | sh
git-credential-manager configure

# Windows — bundled with Git for Windows 2.28+ (re-installer prompt offers GCM)

Étape 2 : configurez GCM pour fremforge

À exécuter une fois par poste de travail :

# Tell GCM to use the Forgejo/Gitea OAuth provider for frem.sh URLs.
git config --global credential.https://frem.sh.gitProvider gitea

# Use fremforge's pre-registered Git Credential Manager OAuth application.
# Same client_id across every fremforge org — your sign-in still goes
# through your org's own IdP (the per-tenant OIDC source registered at
# /<your-org>/_admin/sso).
git config --global credential.https://frem.sh.oauthClientId e90ee53c-94e2-48ac-9358-a874fb9e0662

L’application OAuth est le client git-credential-manager intégré, livré avec Forgejo : aucun enregistrement par instance n’est nécessaire, et le même identifiant client fonctionne avec toutes les instances fremforge et tous les hébergeurs Git basés sur Forgejo. Le client utilise PKCE (Proof Key for Code Exchange), si bien qu’aucun client_secret n’est requis sur la machine du développeur. Les rappels en boucle locale (http://127.0.0.1, http://localhost) sont acceptés sur n’importe quel port, conformément au §7.3 de la RFC 8252.

Étape 3 : clonez en HTTPS

git clone https://frem.sh/<your-org>/<your-repo>.git

GCM ouvre un onglet de navigateur → frem.sh vous demande votre e-mail (pour savoir à quelle organisation vous appartenez) → vous êtes renvoyé vers la page de connexion propre à votre organisation → seul le ou les boutons de l’IdP de votre organisation s’affichent → vous saisissez mot de passe et MFA auprès de votre IdP → le navigateur rend la main à GCM → le jeton est mis en cache. Les IdP des autres organisations ne sont jamais visibles. Les clones, fetch et push suivants se font sans interaction tant que le jeton est valide.

Les jetons d’accès durent 24 heures : pendant cette période, chaque git push se fait sans interaction. Les jetons de rafraîchissement durent 30 jours, si bien que le premier push après l’expiration du jeton d’accès le renouvelle sans ouvrir le navigateur. Chaque machine depuis laquelle vous vous connectez conserve sa propre connexion valide : utiliser git sur un portable et sur un poste fixe (ou dans WSL) n’oblige aucun des deux à se reconnecter. Après 30 jours sans push ni fetch, l’opération suivante rouvre le navigateur et votre IdP déclenche la MFA.

Quand GCM ouvre le navigateur pour une nouvelle connexion (un nouvel appareil, après une déconnexion, ou après 30 jours sans utilisation), frem.sh vous demande d’abord de confirmer votre identité avec votre application d’authentification ou votre clé de sécurité. Cela arrive environ une fois par mois sur chaque appareil ; le renouvellement de la connexion en arrière-plan ne vous le demande jamais. Voir Pourquoi me demande-t-on de confirmer mon identité ?

Étape 4 : facultatif, des réglages par défaut judicieux

# Cache the OAuth token between sessions instead of re-running the
# browser flow every laptop reboot. GCM stores it in the OS keychain
# (macOS Keychain / Windows Credential Manager / Linux libsecret).
git config --global credential.credentialStore gpg     # Linux only
git config --global credential.guiPrompt true          # macOS / Linux

Solutions de repli

Jeton d’accès personnel (bots CI et scripts uniquement)

Les PAT sont des identifiants porteurs statiques, sans MFA. Ils conviennent à l’automatisation sans intervention humaine ; jamais pour les push d’humains.

# 1. Mint at frem.sh/user/settings/applications
# 2. Set expiry to the shortest practical value (30 days for routine,
#    90 days for stable CI). If your org admin has set a max lifetime
#    policy, the mint page caps the dropdown automatically.
# 3. Use as the password for HTTPS clone:
git clone https://<your-username>:<pat>@frem.sh/<org>/<repo>.git

# Or via GCM's "store in keychain" path so you don't bake it into URLs:
git -c credential.helper=store clone https://frem.sh/<org>/<repo>.git
# Enter username + paste PAT when prompted; cached in ~/.git-credentials.

Jetons OIDC de Forgejo Actions (identité de charge de travail CI, sans identifiants statiques)

Pour une CI/CD qui déploie vers AWS / Azure / GCP / T Cloud Public, préférez l’identité fédérée aux PAT. fremforge fournit aux jobs CI des jetons OIDC de courte durée émis par son émetteur runner-OIDC, https://frem.sh/_app/runner/oidc (découverte à l’adresse https://frem.sh/_app/runner/oidc/.well-known/openid-configuration) ; configurez l’IAM de votre fournisseur cloud pour faire confiance à cet émetteur. Les claims (sub, aud, repository_owner) sont décrits sur la page ci-dessous. Consultez Runner OIDC pour les modèles de politique de confiance propres à chaque cloud.

SSH (uniquement si l’administrateur de votre organisation l’a explicitement activé)

Les nouvelles organisations fremforge ont SSH désactivé par défaut. Si votre organisation a besoin de SSH (CI historique, forte préférence des développeurs pour le parcours par clé SSH) :

1. L’administrateur de l’organisation ouvre <your-org>/_admin/auth-policy et coche « Autoriser le protocole SSH », en acceptant la limite documentée selon laquelle la liste d’IP autorisées ne s’applique pas à SSH.
2. Les membres ajoutent leurs clés SSH à l’adresse frem.sh/user/settings/keys et configurent leur ~/.ssh/config :

Host frem.sh
    Hostname ssh.frem.sh
    Port 443
    IdentityFile ~/.ssh/id_ed25519

3. Utilisez si possible des clés adossées à du matériel (ssh-add --apple-use-keychain sur macOS pour Touch ID ; ssh-keygen -t ed25519-sk pour FIDO/YubiKey sous Linux). Voir la section sur les clés SSH matérielles ci-dessous.

Vos propres applications OAuth : demandez des scopes explicites

Si vous enregistrez une application OAuth2 sur frem.sh (Paramètres de l’utilisateur ou de l’organisation › Applications) pour connecter des personnes ou appeler l’API en leur nom, son jeton ne peut faire que ce que permettent les scopes qu’elle a demandés :

• Scopes d’API (read:repository, write:issue, read:user et les autres) : le jeton fonctionne sur l’API et sur Git en HTTPS dans la limite de ces scopes, comme auparavant.
• Uniquement openid, profile, email, groups : le jeton connecte la personne et rien d’autre. Il fonctionne sur /login/oauth/userinfo et /login/oauth/introspect, et reçoit 401 sur l’API, les registres de paquets et Git.
• Aucun scope : même chose, connexion uniquement. Seuls les clients propres à fremforge (Git Credential Manager configuré comme ci-dessus et la CLI fremforge) conservent un accès complet sans scope.

Une application qui a besoin de l’API doit donc demander les scopes d’API nécessaires dans le paramètre scope de /login/oauth/authorize. Si elle dispose déjà d’une autorisation avec un autre scope, la personne révoque cette autorisation sous Applications OAuth2 autorisées sur frem.sh/user/settings/applications, puis se reconnecte.

Clés SSH adossées à du matériel (pour les organisations qui ont réactivé SSH)

Si l’administrateur de votre organisation a réactivé SSH et que vous devez vraiment l’utiliser, les clés adossées à du matériel sont la bonne pratique incontournable. La politique d’organisation Exiger des clés SSH adossées à du matériel lors de l’ajout de nouvelles clés refuse, dès l’enregistrement, toute clé qui n’appartient pas à la famille d’algorithmes sk-*.

macOS : Secure Enclave

ssh-keygen -t ed25519 -C "your-name@your-org" -f ~/.ssh/id_ed25519
ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Touch ID vous sollicite à chaque push si le trousseau macOS n’a pas déverrouillé la clé récemment. Pour une clé résidant entièrement dans la Secure Enclave (générée et conservée exclusivement dans la puce), utilisez Secretive.

Linux : YubiKey / authentificateur FIDO

ssh-keygen -t ed25519-sk -C "your-name@your-org" -f ~/.ssh/id_ed25519_sk
ssh-add ~/.ssh/id_ed25519_sk

ed25519-sk nécessite OpenSSH 8.2+ (février 2020) ; ecdsa-sk est la solution de repli sur les distributions plus anciennes.

Windows : adossé au TPM via WSL2 / KeePassXC

OpenSSH natif sous Windows n’expose pas directement le TPM. Deux possibilités :

1. WSL2 : suivez la procédure Linux dans WSL2.
2. Agent SSH de KeePassXC / 1Password : tous deux conservent des clés protégées par la biométrie Windows Hello.

Arbre de décision

Are you a human developer pushing code daily?
├── Yes → HTTPS + GCM (the recommended default; no SSH key needed)
│         ├── If your org has re-enabled SSH and you prefer it → hardware-backed SSH key
│         └── If you specifically need a static credential → PAT with 30-day expiry
└── No, I'm a CI bot or script
    ├── Cloud-deploying → Forgejo Actions OIDC token (no static cred)
    └── Other → PAT with tight scope + short expiry

Ce qu’il ne faut PAS faire

• Des PAT de longue durée dans des fichiers de configuration git / .netrc. Des identifiants porteurs statiques sans expiration sont le pire schéma d’authentification. Utilisez GCM pour les humains, les jetons OIDC pour la CI et des PAT à courte durée de vie pour les bots historiques.
• Un simple ssh-keygen -t ed25519 sans support matériel ni exigence de l’organisation. La clé reste dans ~/.ssh/ ; ordinateur perdu = clé compromise pendant toute sa durée de vie.
• Contourner la MFA avec des pratiques du type « clé SSH toujours approuvée ». Si votre organisation a besoin d’un contrôle du niveau d’une liste d’IP autorisées, cela implique HTTPS : la liste d’IP autorisées de fremforge s’applique en temps réel en HTTPS et est techniquement impossible en SSH.
• Réactiver SSH parce que « c’est plus rapide ». L’écart de friction à la configuration est négligeable passé le premier jour ; l’écart de posture de sécurité, lui, est réel.

Référence pour l’administrateur de l’organisation

Si vous êtes propriétaire d’une organisation et définissez la politique :

• Guide d’administration de la politique d’authentification : désactivation de SSH, exigence de clés SSH adossées à du matériel, autorité de certification SSH (intégrée le 2026-05-26), durée de vie maximale des PAT, option Autoriser les clés de déploiement de dépôt, commits signés, périmètre de la liste d’IP autorisées et aperçu en mode audit seul