2.7 : LDAP et Active Directory : la solution de repli

Pourquoi cette leçon existe

En 2.5, je vous ai déconseillé de brancher vos applications directement sur vos contrôleurs de domaine. Je ne me dédis pas.

Mais il y a des situations où l’on n’a pas le choix : pas d’IdP dans l’organisation, pas de mandat pour en déployer un, ou une décision qui ne vous appartient pas. Dans ces cas-là, une liaison LDAP correctement configurée reste infiniment préférable à des comptes locaux gérés à la main — et l’objet de cette leçon est de la faire proprement.

Si vous avez configuré l’OIDC en 2.6, vous pouvez sauter cette leçon. Gardez simplement en tête qu’elle existe : le jour où vous devrez brancher un outil d’infrastructure qui ne sait pas faire d’OIDC, les principes exposés ici s’appliqueront.


Deux modes, un seul recommandé

Forgejo propose deux variantes de liaison LDAP.

LDAP via BindDN — Forgejo se connecte à l’annuaire avec un compte de service, recherche l’utilisateur, puis tente de s’authentifier avec le mot de passe saisi. C’est le mode à retenir : il permet de filtrer, de rechercher sur plusieurs attributs et de synchroniser.

LDAP simple auth — Forgejo construit directement le DN de l’utilisateur à partir d’un modèle. Pas de compte de service, mais une rigidité qui le rend peu utilisable en Active Directory, où les utilisateurs sont répartis dans plusieurs unités d’organisation.

Nous partons sur BindDN.


Le compte de service

C’est la première chose à créer, et c’est là que se joue une partie de la sécurité du montage.

Créez un compte dédié, uniquement pour cet usage. Pas un compte d’administration existant, pas un compte partagé entre applications.

Donnez-lui le strict minimum : la lecture de l’annuaire suffit. Aucun droit d’écriture, aucune appartenance à un groupe privilégié. La documentation de Forgejo le formule clairement — le mot de passe est stocké chiffré, mais il est recommandé de limiter au maximum les privilèges du compte.

Un mot de passe long, et documenté. Il vivra dans la configuration de Forgejo. Notez où il est utilisé, faute de quoi personne n’osera plus le changer dans trois ans.

Le mot de passe du BindDN est chiffré avec la SECRET_KEY de votre instance — celle générée à l’installation en 2.4. C’est une raison de plus pour laquelle cette clé fait partie intégrante de votre sauvegarde : sans elle, la liaison LDAP est à reconfigurer.


La configuration, champ par champ

Administration du site → Sources d’authentification → Ajouter une source, type LDAP (via BindDN).

Connexion au serveur

Champ Valeur pour Active Directory
Nom de l’authentification Active Directory
Hôte dc01.nordika.local
Port 636 (LDAPS) ou 389 (LDAP)
Activer le chiffrement TLS ✅
Bind DN CN=svc-forgejo,OU=Services,DC=nordika,DC=local
Bind Password Le mot de passe du compte de service

Sur le chiffrement, ne transigez pas. En LDAP simple, le mot de passe de l’utilisateur circule en clair sur votre réseau — celui du domaine, pas un mot de passe applicatif. Utilisez LDAPS sur le port 636, ou STARTTLS sur le 389.

Et n’oubliez pas que votre forge est un conteneur : il doit faire confiance à l’autorité qui a signé le certificat de vos contrôleurs de domaine. C’est le même problème que celui rencontré en 2.6 avec le certificat de l’IdP, et il se traite de la même manière.

Recherche des utilisateurs

Champ Valeur
User Search Base OU=Utilisateurs,DC=nordika,DC=local
User Filter (voir ci-dessous)
Attribut nom d’utilisateur sAMAccountName
Attribut prénom givenName
Attribut nom sn
Attribut e-mail (requis) mail

Le filtre utilisateur, décortiqué

C’est la pièce centrale. Voici le filtre recommandé pour Active Directory :

(&(objectCategory=Person)(memberOf=CN=Forge-Utilisateurs,OU=Groupes,DC=nordika,DC=local)(sAMAccountName=%[1]s)(!(UserAccountControl:1.2.840.113556.1.4.803:=2)))

Décomposons, parce que chaque morceau compte.

(objectCategory=Person) — ne remonter que des utilisateurs, pas des ordinateurs ni des contacts.

(memberOf=CN=Forge-Utilisateurs,...) — n’autoriser que les membres d’un groupe donné. Sans cette condition, l’ensemble de votre annuaire peut se connecter à la forge. C’est l’équivalent de la revendication requise vue en 2.6, et c’est tout aussi indispensable.

(sAMAccountName=%[1]s) — la substitution : %[1]s est remplacé par l’identifiant saisi dans le formulaire. La notation entre crochets permet de l’utiliser plusieurs fois, par exemple pour accepter aussi bien l’identifiant que l’adresse :

(|(sAMAccountName=%[1]s)(mail=%[1]s))

(!(UserAccountControl:1.2.840.113556.1.4.803:=2)) — la partie qui semble illisible et qui est pourtant essentielle : elle exclut les comptes désactivés.

Cette syntaxe est un opérateur de comparaison binaire propre à Active Directory : elle teste le bit 2 de l’attribut UserAccountControl, qui indique un compte désactivé. Le ! inverse la condition.

Sans elle, un compte désactivé dans l’annuaire continue de pouvoir se connecter à votre forge. C’est-à-dire qu’un collaborateur parti la semaine dernière garde l’accès à vos scripts d’administration. Copiez-la telle quelle.

Le filtre administrateur

(memberOf=CN=Forge-Admins,OU=Groupes,DC=nordika,DC=local)

Les membres de ce groupe deviennent administrateurs de la forge. Ce filtre s’applique au résultat du filtre utilisateur : un compte doit d’abord passer le premier pour être évalué par le second.

Même mise en garde qu’en 2.6 : quiconque peut ajouter un membre à ce groupe peut prendre le contrôle de la forge. Choisissez un groupe dédié et contrôlé.


Vérifier l’appartenance aux groupes

Forgejo propose une section distincte pour valider l’appartenance à un groupe, en alternative au memberOf placé dans le filtre utilisateur.

Champ Exemple
Group Search Base OU=Groupes,DC=nordika,DC=local
Group Name Filter (voir ci-dessous)
User Attribute in Group dn
Group Attribute for User member

Le filtre de nom de groupe déclare comment identifier les groupes valides dans cette base. Pour en accepter plusieurs, on utilise l’opérateur OU du LDAP, qui s’écrit en notation préfixée — le | avant les conditions, et non entre elles :

(|(cn=Forge-Utilisateurs)(cn=Forge-Admins))

C’est la même logique que le & du filtre utilisateur vu plus haut : l’opérateur ouvre le groupe de conditions au lieu de les séparer. Une seule condition s’écrit simplement (cn=Forge-Utilisateurs), sans opérateur.

Les deux derniers champs demandent un peu d’attention car ils se répondent :

  • Si votre groupe contient member: CN=jdupont,OU=... → User Attribute in Group vaut dn.
  • Si votre groupe contient memberUid: jdupont → il vaut uid (cas fréquent en OpenLDAP).

En Active Directory, c’est le premier cas : dn et member.

Faut-il utiliser cette section ou le memberOf du filtre ? Le filtre suffit dans la plupart des cas et reste plus simple à diagnostiquer. Cette section devient utile lorsque vos groupes ne sont pas exploitables via memberOf, ou pour combiner plusieurs conditions.


La synchronisation périodique

L’option Enable user synchronization active une tâche qui aligne périodiquement les comptes Forgejo sur l’annuaire — toutes les 24 heures par défaut, réglable via [cron.sync_external_users].

Elle fait trois choses : créer les nouveaux utilisateurs correspondant aux critères, mettre à jour les informations existantes, et désactiver les comptes qui ne remontent plus. Ce dernier point est celui qui compte : c’est ce qui fait qu’un départ dans l’annuaire se traduit par une désactivation dans la forge.

⚠️ Un avertissement de la documentation à prendre au sérieux : lors de sa première exécution, la tâche crée tous les utilisateurs correspondant à vos critères. Sur un annuaire d’entreprise sans filtre restrictif, vous pouvez vous retrouver avec plusieurs milliers de comptes d’un coup.

Vérifiez votre filtre avant d’activer la synchronisation. Le memberOf prend ici toute son importance.

Le comportement est piloté par UPDATE_EXISTING : à true (défaut), les comptes sont mis à jour et désactivés ; à false, seuls les nouveaux sont créés. Gardez la valeur par défaut, c’est elle qui apporte le bénéfice.


La haute disponibilité : le point faible

Voici une limite qu’il faut regarder en face, et qui illustre concrètement l’argument de la leçon 2.5.

La source d’authentification ne prend qu’un seul hôte. Vous saisissez dc01.nordika.local, et c’est tout. Si ce contrôleur de domaine est indisponible, plus personne ne se connecte à la forge.

Trois contournements, du plus simple au plus solide :

Un nom DNS partagé — utilisez le nom du domaine lui-même (nordika.local), qui résout vers l’ensemble des contrôleurs. C’est la solution la plus simple, mais la répartition est aveugle : le client peut se voir attribuer un DC en panne et échouer.

Une adresse virtuelle portée par un répartiteur de charge, avec des sondes de disponibilité. Efficace, mais c’est une brique de plus.

Un fournisseur d’identité qui, lui, sait gérer plusieurs contrôleurs et présente un point d’entrée unique et stable.

Vous aurez reconnu l’argument de la leçon 2.5 : le problème ne disparaît pas, il se déplace vers un composant conçu pour le traiter.


Tester

Ne testez pas avec votre compte. Utilisez un compte de test appartenant au groupe autorisé.

  1. Déconnectez-vous, puis connectez-vous avec l’identifiant du domaine et son mot de passe.
  2. Le compte doit être créé automatiquement dans Forgejo, avec le nom, le prénom et l’adresse renseignés.
  3. Vérifiez dans Administration du site → Comptes utilisateurs que la source d’authentification est correcte.
  4. Testez un compte hors du groupe : la connexion doit être refusée.
  5. Testez un compte désactivé dans l’annuaire : la connexion doit également être refusée. C’est le contrôle qui valide votre filtre UserAccountControl.
  6. Vérifiez que le compte d’administration local fonctionne toujours.

Les erreurs classiques

Symptôme Cause probable
LDAP Result Code 49: Invalid Credentials Bind DN ou mot de passe du compte de service erroné
Erreur de certificat L’autorité de vos DC n’est pas connue du conteneur Forgejo
Connexion refusée pour tout le monde Base de recherche ou filtre incorrect
Un compte désactivé se connecte encore Condition UserAccountControl absente du filtre
Compte créé sans adresse e-mail Attribut mail vide dans l’annuaire — il est requis
Timeout à la connexion Le conteneur ne joint pas le DC : réseau ou pare-feu
Des milliers de comptes créés Synchronisation activée avec un filtre trop large

Pour diagnostiquer un filtre, validez-le d’abord côté annuaire, avec ldapsearch depuis un serveur Linux ou Get-ADUser -LDAPFilter en PowerShell. Vous saurez immédiatement s’il remonte les bons comptes, sans faire d’aller-retour dans l’interface de Forgejo.


Ce que cette solution ne vous apportera pas

Pour finir, et sans y revenir davantage — c’est simplement ce qu’il faut savoir en connaissance de cause.

Pas de double authentification. Le protocole ne le permet pas. Vous pouvez activer la 2FA propre à Forgejo, mais elle est indépendante de votre annuaire.

Pas de politique conditionnelle. Ni restriction horaire, ni contrôle de la provenance, ni exigence renforcée selon le contexte.

Le mot de passe du domaine transite par l’application. L’utilisateur le saisit dans Forgejo, qui le transmet à l’annuaire.

Un compte de service de plus avec droit de lecture sur votre annuaire, à faire vivre dans le temps.

Rien de tout cela n’empêche de fonctionner. Mais si un IdP devient possible un jour, la bascule vaudra le déplacement — et vous savez maintenant configurer les deux.


Ce qu’il faut retenir

  • Préférez le mode BindDN, avec un compte de service dédié en lecture seule.
  • Chiffrez la connexion : le mot de passe du domaine ne doit jamais circuler en clair.
  • Le filtre utilisateur doit restreindre à un groupe — sinon tout l’annuaire peut entrer.
  • La condition UserAccountControl exclut les comptes désactivés : sans elle, un ancien collaborateur garde son accès.
  • Vérifiez votre filtre avant d’activer la synchronisation, sous peine de créer des milliers de comptes.
  • La source ne gère qu’un seul hôte : anticipez l’indisponibilité d’un contrôleur.
  • Le mot de passe du BindDN est chiffré avec la SECRET_KEY — encore une raison de la sauvegarder.
  • Testez avec un compte hors du groupe et avec un compte désactivé.

Dans la leçon suivante

Votre authentification est en place, par OIDC ou par LDAP. Vos collègues se connectent à l’interface avec leurs identifiants habituels.

Et pourtant, au premier git clone, ça ne fonctionnera pas.

La prochaine leçon traite le malentendu le plus coûteux de cette section : l’authentification web et les opérations Git suivent deux chemins totalement distincts. Le SSO couvre le navigateur ; il ne couvre ni git push, ni le runner d’intégration continue, ni le registre de conteneurs, ni l’API. Nous verrons pourquoi, et comment gérer les jetons d’accès qui prennent le relais.