Dolibarr& SSO : Erreurs fréquentes et solutions pour passer à l’échelle Auteur : [Votre Nom] – Architecte solutions open‑source Date : 3 novembre 2025
— ## 1. Introduction
Dolibarr est une suite d‑ERP / CRM très légère, écrite en PHP, qui s’installe généralement en mode « stand‑alone » ou « shared‑hosting ».
Dans les grandes organisations, l’accès aux applications métiers est de plus en plus centralisé via Single Sign‑On (SSO) : Azure AD, Keycloak, Okta, Google Workspace, etc.
Le passage du modèle d’authentification « login / mot de passe » vers le SSO apporte des bénéfices en termes de sécurité, de productivité et de gouvernance, mais il introduit également des pièges spécifiques à Dolibarr lorsqu’on veut le faire évoluer (stabilité, scalabilité, haute disponibilité).
Cet article passe en revue les erreurs les plus courantes rencontrées lors de l’intégration d’un SSO à Dolibarr, puis propose des solutions concrètes pour transformer votre déploiement en une plateforme prête à l’échelle d’une entreprise du 5 000 à 50 000 utilisateurs.
2. Le contexte SSO avec Dolibarr
| Élément | Description | Pourquoi c’est critique pour Dolibarr |
|---|---|---|
| SSO provider | Azure AD, Keycloak, Okta, Auth0, OneLogin, etc. | Nécessite une configuration précise des redirect URIs et du client secret. |
| Entrepôt d’utilisateurs | LDAP / Active Directory, base interne, base externe | Dolibarr compte par défaut sur ses propres tables user/usergroup. |
| Gestion des groupes | Mapper les groupes du fournisseur SSO → les groupes Dolibarr | Sinon les autorisations ne sont pas synchronisées. |
| Web‑app mode | Mode « Front‑controller » (tout passe par index.php) |
Nécessite que le callback du SSO soit autorisé dans les paramètres de sécurité. |
| Scalabilité | Charge de plusieurs instances derrière un load‑balancer | Le token ou la session doit être partagé (sticky‑sessions ou cache partagé). |
3. Erreurs fréquentes
3.1. Configuration d’URL de callback incomplète
- Symptôme : Après la redirection vers le provider SSO, le retour à Dolibarr se solde par « 403 – Invalid redirect_uri » ou boucle infinie de login.
- Cause : L’URL configurée dans le client SSO ne correspond pas exactement à l’adresse publique du point d’entrée (ex.
https://app.example.com/dolibarr/oauth2callback). - Piste : Vérifier la routage dans
conf/conf.php(variable$_SERVER['REQUEST_URI']) et s’assurer que le même sous‑domaine et le même port sont utilisés.
3.2. Redirection HTTP/HTTPS mixte
- Symptôme : Login fonctionne en HTTP mais échoue en HTTPS ou inversement, avec des erreurs « Invalid state token ».
- Cause : Le provider SSO attend un redirect_uri exactement identique au schéma (http vs https).
- Solution : Forcer le protocole via
.htaccessou le serveur web (RewriteCond %{HTTPS} off).
3.3. Confusion entre client_id et client_secret
- Symptôme : Erreur 401 : invalid_client lors du premier échange OAuth.
- Cause : Le secret n’est pas stocké dans le fichier de configuration ou des caractères invisibles sont présents.
- Solution : Copier le secret depuis le provider sans espaces ; le placer dans
conf/conf.php($conf['oauth']['client_secret']).
3.4. Mappage des groupes d’utilisateurs inexistant – Symptôme : Les utilisateurs sont bien authentifiés, mais leurs droits restent « Guest ».
- Cause : Le script de synchronisation de groupes (
groupsync.php) ne trouve aucun groupe correspondant dans Dolibarr → groupes par défaut vide. -
Remède : Créer manuellement des groupes correspondants ou activer l’extension Automatic Group Sync (ex.
plugins/groupmanager). ### 3.5. Session partagée entre plusieurs instances - Symptôme : Les utilisateurs sont régulièrement déconnectés lorsqu’ils sont redirigés d’une instance à l’autre (load‑balancer).
- Cause : Les cookies de session (
PHPSESSID) ne sont pas persistés de façon partagée (pas de cache Redis ou de fichier de session partagé). - Solution : Configurer PHP ou Nginx pour stocker les sessions en Redis ou Memcached (voir § 5).
3.6. Problèmes de scaling du cache et des assets
- Symptôme : Chargement lent des pages après le déploiement de plusieurs serveurs ; erreurs « 500 – Internal Server Error » pendant les pics de trafic.
- Cause : Les fichiers de configuration (
conf/*.php) sont écrits en dur sur chaque nœud, ce qui empêche la propagation dynamique des changements de paramètres de SSO. - Solution : Externaliser la configuration vers un volume partagé (NFS, S3‑compatible bucket) ou utiliser un framework de configuration (ex.
ansible+templates).
3.7. Utilisation d’une version ancienne de Dolibarr
- Symptôme : Des bugs d’authentification SSO remontent dès la version 0.9 – 0.10.
- Cause : Support limité du PKCE et d’utilisation de l’option
response_type=codeuniquement. - Remède : Migrer dès que possible vers la branche 15.x (ou ultérieure) où le module OAuth est maintenu à jour.
4. Guide pas‑à‑pas : Implémenter correctement le SSO avec Dolibarr ### 4.1. Prérequis
| Prérequis | Détails |
|---|---|
| Dolibarr ≥ 15.x | Support complet des endpoints OAuth2 et des paramètres de security. |
| Web‑server (Nginx/Apache) | Rewrite rules actifs et possibilité de configurer proxy_set_header. |
| HTTPS | Termination TLS au load‑balancer (pas de redirection mixte). |
| Base de données | MySQL/MariaDB ou PostgreSQL compatible. |
| Cache partagé | Redis ou Memcached (optionnel mais recommandé). |
| IdP (SSO) | Azure AD, Keycloak, ou tout autre fournisseur compatible OpenID Connect / OAuth2. |
4.2. Étapes d’intégration
-
Enregistrement du client SSO
- Dans le provider, créer un client « Dolibarr ».
- Redirect URI :
https://app.example.com/dolibarr/oauth2callback(et le même en HTTP uniquement si vous avez désactivé HTTPS). - Noter Client ID et Client Secret.
-
Configuration de Dolibarr
Ajouter dansconf/conf.php(ou dans le fichier de configuration dédié) :$conf['oauth']['enabled'] = true;
$conf['oauth']['provider'] = 'openid'; // ou 'azuread' / 'keycloak'
$conf['oauth']['client_id'] = 'YOUR_CLIENT_ID';
$conf['oauth']['client_secret']= 'YOUR_CLIENT_SECRET';
$conf['oauth']['callback_url'] = 'https://app.example.com/dolibarr/oauth2callback';
$conf['oauth']['scope'] = 'openid email profile groups';
$conf['oauth']['token_endpoint'] = 'https://provider.com/oauth2/token';
$conf['oauth']['authorization_endpoint'] = 'https://provider.com/oauth2/authorize';
$conf['oauth']['userinfo_endpoint'] = 'https://provider.com/userinfo'; -
Mappage des groupes
- Créer les groupes dans Dolibarr qui correspondent aux groupes du provider (ex. HR, IT).
- Installer le plugin GroupMapper (
plugins/groupmapper) et configurer les règles d’appariement (ex.group_name=displayName).
-
Synchronisation périodique
- Mettre en place un cron qui interroge l’API du provider (
/groups) et met à jour les groupes Dolibarr. - Exemple de script
/path/to/dolibarr/scripts/groupsync.php:
« `bash /15 * php /var/www/dolibarr/scripts/groupsync.php >> /var/log/dolibarr/groupsync.log 2>&1
- Mettre en place un cron qui interroge l’API du provider (
-
Partage de session
-
Installer Redis et activer la persistance des sessions : « `ini
; php.ini
session.save_handler = redis
session.save_path = "tcp://127.0.0.1:6379" - En cas d’utilisation d’un load‑balancer avec sticky sessions, désactiver le mode « session‑stickiness » et se reposer sur Redis pour la continuité.
-
- Externalisation de la configuration
- Ranger tous les fichiers
conf/*.phpdans un répertoire partagé (/srv/dolibarr/config/). – Utiliser un outil d’infrastructure comme Ansible pour injecter les variables d’environnement ({{ oauth_client_id }}etc.) au moment du déploiement. ### 4.3. Test fonctionnel
- Ranger tous les fichiers
| Test | Action attendue | Critère de succès |
|---|---|---|
| Login via SSO | Redirection du navigateur vers le provider, authentification, retour dans Dolibarr avec l’UID du user connu. | Page d’accueil affichée, user dans la base a été créé, rôle correct. |
| Logout | Logout du provider, suivi d’une déconnexion locale. |
Redirection vers la page de login du provider, puis retour au portail SSO. |
| Group Sync | Utilisateur qui appartient au groupe IT dans le provider est automatiquement mis dans le groupe IT de Dolibarr. | Vérifier usergroup dans la DB ou via l’interface. |
| Load‑balancer | Session persistance via Redis assure que le second appel profite du même backend. | Aucun 500 ou session expired quand on change de serveur. |
5. Solutions pour passer à l’échelle
5.1. Architecture proposée pour le scaling horizontal
+----------------------+ +----------------------+ +----------------------+
| Load Balancer (LB) | <----> | Front‑end 1 (Dol) | <----> | Front‑end 2 (Dol) |
| (path /dolibarr) | | (PHP-FPM) | | (PHP-FPM) |
+----------------------+ +----------------------+ +----------------------+
| | |
v v v
+-------------------+ +-------------------+ +-------------------+
| Redis Cluster | <------> | PHP Session Store| | Shared Config |
+-------------------+ +-------------------+ +-------------------+
|
v
+-------------------+
| Database (HA) |
+-------------------+- LB : Terminaison TLS, réécriture du chemin
/dolibarr/*vers/src/index.php. - Front‑end : Serveurs PHP‑FPM identiques, scalables via Kubernetes HPA.
- Redis : Cache de sessions, files d’activités, lock‑manager.
- DB : Cluster maître‑esclave ou Galera pour la haute disponibilité.
- Config partagée :
/srv/dolibarr/config/monté en NFS ou via Ceph.
5.2. Gestion du cache de performance
| Cache | Fonction | Configuration recommandée pour le scaling |
|---|---|---|
| OPcache | Bytecode compilé | opcache.enable=1 (global, pas besoin de partage). |
| APCu | Variables partagées entre processus | Désactiver sur serveur multi‑node (pas partagé). |
| Redis | Sessions + token storage | maxmemory 2gb, maxmemory-policy allkeys-lru. |
| Varnish (optionnel) | Cache HTTP frontales | backend dédié à chaque front‑end, TTL 300 s. |
5.3. Déploiement automatisé
5.3.1. Dockerisation (Docker‑Compose) – point de départ
version: "3.8"
services:
web:
image: dolibarr/dolibarr:latest
environment:
- DOUSER=www-data
- DOgroup=www-data
- OAUTH_CLIENT_ID=${OAID}
- OAUTH_CLIENT_SECRET=${OAS}
- OAUTH_PROVIDER=${PROV}
- OAUTH_CALLBACK_URL=https://lb.example.com/dolibarr/oauth2callback
volumes:
- ./config:/srv/dolibarr/conf
- redis-data:/data
depends_on: [php-fpm, redis]
ports: ["80:80"]
php-fpm:
image: php:8.2-fpm
...
redis:
image: redis:7-alpine command: ["redis-server","--save","","--appendonly","no"]
volumes: ["redis-data:/data"]
volumes:
redis-data:- Le fichier
config/conf.phpreste monté et partag\u00e9 entre toutes les réplications. - La configuration de
OAUTH_*peut être injectée par Secrets Manager (AWS) ou Vault (HashiCorp).
5.3.2. Kubernetes (Helm chart) – pour la production
- Utiliser le chart community
helmrepo/dolibarr(ou créer un chart custom). - Paramétrer les ConfigMaps pour
conf/*.phpet les Secrets pour les credentials OAuth. - Déployer Redis‑Cluster via le chart
bitnami/rediscluster. - Activer ClusterIP + Ingress avec path‑based routing (
/dolibarr).
6. Bonnes pratiques supplémentaires
| Domaine | Bonnes pratiques |
|---|---|
| Sécurité | – Toujours forcer TLS. – Utiliser le PKCE si le client est public (ex. mobile). – Limiter le scope du token à openid profile. |
| Monitoring | – Activer le logging des échanges OAuth (/var/log/dolibarr/oauth.log).– Créer des alertes sur session timeout > 24 h. |
| Testing | – Utiliser les environnements staging avec un mock provider (ex. localhost:8080/keycloak).– Simuler un pic de 10 000 requêtes avec k6 ou ab. |
| Documentation | – Créer un Runbook qui liste les étapes de reset du cache Redis et de re‑synchronisation des groupes. |
| Versioning | – Planifier une migration semestrielle vers la dernière branche LTS de Dolibarr (actuellement 18.x). |
7. Checklist de mise en production
| ✅ | Action | Responsable |
|---|---|---|
| 1 | Créer le client OAuth dans le provider SSO avec le callback exact. | Admin SSO |
| 2 | Déployer la version ≥ 15.x de Dolibarr (Docker/K8s). | DevOps |
| 3 | Injecter les variables OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET via Secrets. |
SecOps |
| 4 | Configurer Redis pour les sessions et les tokens. | Infra |
| 5 | Mettre en place le cron de synchronisation des groupes. | DBA |
| 6 | Tester le login, gruppen sync, logout en boucle (10 min). | QA |
| 7 | Vérifier la persistance de session via plusieurs serveurs LB. | Infra |
| 8 | Activer le monitoring (metrics Prometheus, logs). | SRE |
| 9 | Documenter le runbook de restauration (cache, DB, config). | Ops |
| 10 | Planifier la migration des comptes existants (import LDAP → SSO). | IAM Team |
8. Conclusion
Le passage à l’échelle d’une application Dolibarr lorsqu’elle est couplée à un SSO ne réside pas seulement dans la configuration du provider, mais surtout dans la gestion unifiée des sessions, des groupes et de la configuration.
- Les erreurs les plus récurrentes (callback URL, protocole mixte, token secret mal stocké, absence de partage de session) sont toutes résolubles en suivant un processus méthodique.
- En adoptant une architecture container‑first avec Redis comme backing store, configuration partagée et automation (Docker/K8s + Helm), il devient possible de supporter des milliers d’utilisateurs tout en conservant la simplicité d’utilisation de Dolibarr.
En appliquant les solutions présentées (mappage des groupes, persistance de session, externalisation des paramètres de sécurité, monitoring et automatisation), vous transformerez votre déploiement initial « demo » en une plateforme robuste, sécurisée et prête à l’échelle pour toute l’entreprise.
À retenir : Éviter les pièges dès le premier jour, c’est gagner du temps sur chaque nouveau serveur que vous ajouterez au futur.
Sources : – Dolibarr Documentation – Chapter OAuth & SSO (v15‑18).
- OIDC RFC 8414 – Best‑practice recommandations.
- Experience interne @ [Nom de votre société] – 2023‑2025 projets SSO.
Vous avez d’autres questions ? N’hésitez pas à me contacter via LinkedIn ou à me laisser un commentaire ci‑dessous.