2.6 : Mettre en œuvre l'authentification OIDC

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

  1. L’identifiant client (Client ID)
  2. Le secret client (Client Secret) — à traiter comme un mot de passe
  3. 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.

  1. Configurez la source sans rien désactiver d’autre.
  2. Testez avec un compte de test, jamais avec le vôtre.
  3. Faites tester deux ou trois collègues avant d’annoncer quoi que ce soit.
  4. Vérifiez que le compte d’administration local fonctionne toujours — c’est le contrôle qu’on oublie systématiquement.
  5. 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 à auto sans avoir mesuré le risque d’usurpation.
  • USERNAME=preferred_username produit 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.

📎 Ressources 2