Une leçon volontairement générique
Chaque organisation a son fournisseur d’identité : Authentik, Keycloak, ADFS, Entra ID, Okta, Zitadel. Les écrans diffèrent, le vocabulaire aussi — mais le protocole est le même, et la moitié Forgejo est strictement identique.
Cette leçon est donc construite en deux temps : d’abord ce qu’il faut créer côté IdP, décrit en termes de protocole plutôt que de captures d’écran, puis la configuration côté Forgejo, détaillée champ par champ.
Un tableau de correspondance vous aidera à traduire dans le vocabulaire de votre produit.
Le principe, en six étapes
Avant de configurer quoi que ce soit, visualisez ce qui va se passer quand un utilisateur cliquera sur « Se connecter avec… ».
1. L'utilisateur clique sur le bouton dans Forgejo
│
2. Forgejo le redirige vers l'IdP ──────────────▶ IdP
│
3. L'utilisateur s'authentifie CHEZ L'IdP ◀─────────┤
(mot de passe, MFA, politiques…) │
│
4. L'IdP le renvoie vers l'URI de redirection ◀─────┘
avec un code à usage unique
│
5. Forgejo échange ce code contre un jeton
(côté serveur, avec son secret client) ────────▶ IdP
│
6. Forgejo lit l'identité dans le jeton
et crée ou retrouve le compte
Deux points à retenir de ce schéma.
Le mot de passe n’apparaît qu’à l’étape 3, chez l’IdP. Forgejo ne le voit jamais. C’est tout l’argument de la leçon précédente.
L’étape 5 se fait de serveur à serveur. Votre forge doit donc pouvoir joindre l’IdP par le réseau — évident, mais c’est la cause d’un certain nombre d’échecs en environnement cloisonné.
Côté fournisseur d’identité
Quel que soit votre produit, vous devez y créer une déclaration d’application et en ressortir avec trois informations.
Ce qu’il faut créer
| Paramètre | Valeur |
|---|---|
| Type de client | Confidentiel (l’application peut garder un secret) |
| Flux d’autorisation | Code d’autorisation (authorization code) |
| URI de redirection | https://forge.nordika.local/user/oauth2/<NomDeLaSource>/callback |
| Scopes | openid, profile, email — et groups si votre IdP le propose |
| Signature des jetons | RS256 (valeur usuelle) |
Ce qu’il faut en ressortir
- L’identifiant client (Client ID)
- Le secret client (Client Secret) — à traiter comme un mot de passe
- L’URL de découverte, de la forme
https://idp.nordika.local/.../.well-known/openid-configuration
Cette dernière est précieuse : elle décrit automatiquement tous les points d’accès de l’IdP. Forgejo sait la consommer, ce qui vous évite de saisir quatre ou cinq URL à la main.
Le vocabulaire selon les produits
| Notion | Authentik | Keycloak | Entra ID | ADFS |
|---|---|---|---|---|
| La déclaration | Provider + Application | Client | App registration | Application group |
| Identifiant | Client ID | Client ID | Application (client) ID | Client Identifier |
| Secret | Client Secret | Client secret (onglet Credentials) | Certificates & secrets | Secret |
| Découverte | Sous l’URL du provider | .../realms/<realm>/.well-known/... |
.../v2.0/.well-known/... |
.../adfs/.well-known/... |
| Groupes | Scope groups à ajouter |
Mapper de type Group Membership | Claim groups à configurer |
Claim rule |
Le cas des groupes mérite votre attention : dans la plupart des IdP, l’appartenance aux groupes n’est pas transmise par défaut. Il faut l’activer explicitement — un scope supplémentaire, un mapper, une règle de revendication selon les produits. Si vous voulez la mise en correspondance automatique avec les équipes Forgejo en 2.9, faites-le maintenant.
L’URI de redirection : le piège n°1
C’est de très loin la première cause d’échec, et elle mérite qu’on s’y arrête.
Forgejo construit l’adresse de retour à partir du nom que vous donnerez à la source d’authentification :
https://<votre-forge>/user/oauth2/<NomDeLaSource>/callback
Si vous nommez votre source Authentik, l’URI sera :
https://forge.nordika.local/user/oauth2/Authentik/callback
Trois conséquences.
Le nom doit être décidé maintenant, avant de configurer l’IdP — puisqu’il faut y déclarer l’URI exacte.
Choisissez un nom simple : sans espace, sans accent, sans caractère spécial. Un espace serait encodé dans l’URL et la moindre différence fait échouer la correspondance.
Ce nom sera visible par vos utilisateurs sur le bouton de connexion. Authentik ou Nordika SSO sont de bons choix ; oidc-test-2 un peu moins.
Et surtout : ne le changez plus après coup. Renommer la source change l’URI de redirection et casse l’authentification pour tout le monde, avec un message d’erreur qui ne pointe pas vers la cause.
En cas d’erreur, le symptôme est un message du type redirect_uri_mismatch ou invalid redirect URI affiché par l’IdP, pas par Forgejo. Comparez alors caractère par caractère : protocole, nom de domaine, majuscules, barre oblique finale.
Côté Forgejo
Rendez-vous dans Administration du site → Sources d’authentification → Ajouter une source.
Sélectionnez le type OAuth2, puis le fournisseur OpenID Connect.
Les champs
| Champ | Valeur |
|---|---|
| Nom de l’authentification | Le nom décidé plus haut — ⚠️ définitif |
| Fournisseur OAuth2 | OpenID Connect |
| Identifiant client | Récupéré dans l’IdP |
| Secret client | Récupéré dans l’IdP |
| URL de découverte automatique | L’adresse en .well-known/openid-configuration |
| Scopes additionnels | groups si vous voulez les récupérer |
| Nom / valeur de revendication requise | Facultatif — voir ci-dessous |
| Revendication des groupes | Le nom du claim contenant les groupes |
| Groupe administrateur | Le groupe dont les membres seront administrateurs |
| Groupe restreint | Le groupe dont les membres auront un accès limité |
(Les intitulés exacts varient légèrement selon les versions ; la logique reste identique.)
Restreindre l’accès dès l’authentification
Les champs de revendication requise sont ceux que l’on néglige, et ils sont précieux.
Sans eux, tout compte valide dans votre IdP peut se connecter à la forge — y compris des utilisateurs qui n’ont rien à y faire. Sur un IdP d’entreprise qui gère l’ensemble du personnel, cela peut représenter beaucoup de monde.
En renseignant un nom de revendication et la valeur attendue, vous imposez une condition d’entrée. Typiquement : n’accepter que les membres d’un groupe donné.
Deux approches, selon la culture de votre organisation :
- Filtrer côté IdP — l’application n’est proposée qu’aux membres d’un groupe. C’est le plus propre, et c’est ce que permettent la plupart des IdP modernes.
- Filtrer côté Forgejo — via la revendication requise. Utile si vous n’avez pas la main sur l’IdP.
Faire les deux ne coûte rien et évite les mauvaises surprises.
Le groupe administrateur
Ce champ vous permet de désigner un groupe de votre annuaire dont les membres deviendront administrateurs de la forge automatiquement.
C’est confortable, et c’est aussi un pouvoir considérable : quiconque peut ajouter un membre à ce groupe peut prendre le contrôle de votre forge — donc, à terme, de ce qui s’exécute sur vos postes. Choisissez un groupe dédié, dont la modification est elle-même contrôlée. Pas le groupe « Informatique » qui contient les stagiaires.
Les réglages qui gouvernent la création des comptes
L’interface ne fait pas tout. Quatre paramètres de configuration déterminent le comportement lors de la première connexion d’un utilisateur.
- FORGEJO__oauth2_client__ENABLE_AUTO_REGISTRATION=true
- FORGEJO__oauth2_client__USERNAME=preferred_username
- FORGEJO__oauth2_client__ACCOUNT_LINKING=login
- FORGEJO__oauth2_client__UPDATE_AVATAR=false
ENABLE_AUTO_REGISTRATION
À true, le compte Forgejo est créé automatiquement à la première connexion réussie. C’est ce que vous voulez : sinon, il faudrait créer chaque compte à la main avant que la personne puisse se connecter, ce qui vide l’intérêt du SSO.
Combiné à une revendication requise ou à un filtrage côté IdP, le risque est maîtrisé : seuls les utilisateurs autorisés arrivent jusque-là.
USERNAME
Détermine le nom d’utilisateur créé dans Forgejo. Quatre valeurs possibles : userid, nickname, email, preferred_username.
Ce choix a des conséquences durables, car ce nom apparaîtra dans les URL de tous les dépôts personnels et dans l’historique.
Ma recommandation : preferred_username, qui correspond généralement à l’identifiant de connexion — lisible et stable. Évitez userid, qui produit des identifiants techniques illisibles, et email, qui expose l’adresse dans les URL.
Notez que Forgejo normalise ces valeurs : suppression des accents, remplacement des espaces par des tirets.
ACCOUNT_LINKING — le paramètre à comprendre
Que faire quand un utilisateur se connecte via l’IdP alors qu’un compte portant la même adresse existe déjà dans Forgejo ? C’est exactement votre cas : vous avez créé un compte administrateur local en 2.4.
| Valeur | Comportement |
|---|---|
disabled |
Erreur affichée, connexion refusée |
login |
L’utilisateur doit se connecter avec son compte existant pour confirmer le rattachement |
auto |
Rattachement automatique et silencieux |
Retenez login. C’est la valeur par défaut, et c’est la bonne : l’utilisateur prouve qu’il possède bien le compte local avant que les deux identités soient fusionnées.
auto est tentant pour le confort, mais la documentation officielle l’assortit d’un avertissement explicite : il accorde l’accès à un compte existant sur la seule foi d’une adresse ou d’un nom identique. Si votre IdP ne vérifie pas rigoureusement les adresses, ou si quelqu’un peut modifier la sienne, vous ouvrez une voie d’usurpation. Sur une forge qui distribue du code exécuté avec des privilèges, ce n’est pas un risque à prendre.
Faut-il garder la connexion par mot de passe ?
Question légitime : une fois le SSO en place, faut-il fermer la porte locale ?
Trois réglages entrent en jeu.
# Autoriser encore la connexion locale par mot de passe
- FORGEJO__service__ENABLE_INTERNAL_SIGNIN=true
# Interdire la création de comptes autrement que par l'IdP
- FORGEJO__service__ALLOW_ONLY_EXTERNAL_REGISTRATION=true
Ma recommandation : gardez la connexion interne activée.
Souvenez-vous du compte d’administration local créé en 2.4. Il n’a de valeur que s’il peut effectivement servir. Le jour où l’IdP est indisponible — certificat expiré, mauvaise manipulation, panne — c’est votre seule porte d’entrée sur un service dont dépendent vos GPO et vos déploiements.
Désactiver ENABLE_INTERNAL_SIGNIN revient à mettre toutes vos clés dans une pièce dont la serrure dépend d’un autre système. Ça se défend en théorie, ça se regrette en pratique.
En revanche, ALLOW_ONLY_EXTERNAL_REGISTRATION à true est un bon compromis : plus aucun compte local ne peut être créé, mais ceux qui existent continuent de fonctionner.
Le piège de ENABLE_BASIC_AUTHENTICATION
Vous croiserez ce paramètre en cherchant à durcir la configuration. Réfléchissez avant d’y toucher.
Le désactiver empêche l’authentification HTTP basique par mot de passe. L’intention est bonne. Mais la documentation précise que vous perdrez alors l’accès à certains points d’API par mot de passe.
Surtout, cela nous amène directement au sujet de la leçon suivante : le SSO ne couvre pas les opérations Git. Un git push ne passe pas par le navigateur, donc pas par l’IdP. Il utilise un jeton, ou une authentification basique. Toucher à ce réglage sans avoir compris ce mécanisme, c’est se préparer une belle séance de diagnostic.
Le premier test
Procédez dans cet ordre, avec un navigateur en navigation privée pour éviter les sessions résiduelles.
1. Déconnectez-vous. La page de connexion doit maintenant afficher un bouton portant le nom de votre source.
2. Cliquez dessus. Vous devez être redirigé vers votre IdP.
3. Authentifiez-vous avec un compte de test — pas le vôtre, et surtout pas le compte d’administration local.
4. Vous devez revenir sur Forgejo, connecté, avec un compte créé automatiquement.
5. Vérifiez dans Administration du site → Comptes utilisateurs que le compte apparaît bien avec la bonne source d’authentification.
Les erreurs classiques
| Message | Cause |
|---|---|
redirect_uri_mismatch (côté IdP) |
L’URI déclarée dans l’IdP ne correspond pas exactement à celle de Forgejo |
invalid_client |
Identifiant ou secret client erroné |
| Erreur de certificat au retour | La forge ne fait pas confiance à l’autorité qui a signé le certificat de l’IdP |
Connection refused dans les journaux |
La forge ne joint pas l’IdP par le réseau (étape 5 du schéma) |
| « Un compte avec cette adresse existe déjà » | ACCOUNT_LINKING — comportement attendu avec login |
| Aucun groupe remonté | Le scope ou le mapper de groupes n’est pas configuré côté IdP |
| Le bouton n’apparaît pas | La source est désactivée, ou le cache du navigateur |
Le certificat de l’IdP : votre forge est un conteneur. S’il doit joindre un IdP interne avec un certificat émis par votre autorité, cette autorité doit être connue du conteneur, pas seulement de l’hôte. C’est un cas que l’on découvre généralement en lisant les journaux, et qui se traite en montant le certificat de l’autorité dans le conteneur.
Vérifier les groupes
Si vous avez configuré la transmission des groupes, contrôlez qu’ils arrivent bien. Le moyen le plus simple : renseignez temporairement le champ Groupe administrateur avec un groupe dont votre compte de test est membre, reconnectez-vous, et vérifiez qu’il est devenu administrateur.
Si oui, les revendications passent correctement — et vous êtes prêt pour la mise en correspondance avec les équipes, en leçon 2.9.
Pensez ensuite à retirer ce réglage temporaire.
Basculer sans casser
Une bascule d’authentification se fait progressivement.
- Configurez la source sans rien désactiver d’autre.
- Testez avec un compte de test, jamais avec le vôtre.
- Faites tester deux ou trois collègues avant d’annoncer quoi que ce soit.
- Vérifiez que le compte d’administration local fonctionne toujours — c’est le contrôle qu’on oublie systématiquement.
- Puis seulement activez
ALLOW_ONLY_EXTERNAL_REGISTRATION.
Et notez quelque part, dans votre documentation d’exploitation, la procédure d’accès de secours. Le jour où vous en aurez besoin, vous ne serez peut-être pas celui qui l’aura configurée.
Ce qu’il faut retenir
- Le protocole est identique quel que soit l’IdP ; seul le vocabulaire change.
- L’URI de redirection dépend du nom de la source : décidez-le avant, ne le changez jamais après.
- L’URL de découverte évite de saisir tous les points d’accès à la main.
- Sans revendication requise ou filtrage côté IdP, tout compte de l’IdP peut entrer.
ACCOUNT_LINKING=login: ne passez pas àautosans avoir mesuré le risque d’usurpation.USERNAME=preferred_usernameproduit les identifiants les plus lisibles et durables.- Gardez la connexion interne activée : le compte de secours doit pouvoir servir.
- Les groupes ne sont pas transmis par défaut : il faut les activer côté IdP.
- Testez avec un compte de test, et vérifiez toujours que l’accès de secours fonctionne encore.
Ressources complémentaires
(Des tutoriels détaillés par fournisseur d’identité viendront compléter cette leçon.)
Dans la leçon suivante
Nous traiterons le cas de ceux qui n’ont pas de fournisseur d’identité, ou dont l’organisation impose une liaison directe à l’annuaire : la configuration LDAP / Active Directory.
Filtres de recherche, attributs, compte de service, synchronisation périodique — avec les précautions qui s’imposent, et le rappel de ce que cette solution ne pourra pas vous apporter.