API Dolibarr : sécurité Tutoriel pas à pas pour équipes hybrides

(Version 23.x – compatible avec les déploiement cloud, on‑premise et hybride)

Objectif : Vous fournir une procédure claire, sécurisée et reproductible pour exploiter l’API de Dolibarr tout en protégeant les données sensibles de votre organisation, même lorsque les équipes travaillent à distance, au bureau ou en mode mixte.

1️⃣ Pourquoi la sécurité de l’API Dolibarr est cruciale pour les équipes hybrides

Risque Impact sur une équipe hybride Exemple concret
Accès non autorisé Un collaborateur distant peut récupérer des credentials en clair. Vol de token via un réseau Wi‑Fi public.
Exfiltration de données Les appels API peuvent révéler des factures, contacts, stocks. Publication accidentelle d’un fichier CSV contenant les prix.
Injection de scripts Des API non protégées peuvent être utilisées pour exécuter du code malveillant. Utilisation d’un endpoint pour déclencher du XSS sur le front‑office.
Manipulation de workflows Des validations de rôle manquantes entraînent des erreurs de facturation ou de stock. Un tiers crée/valide une facture frauduleuse.

Conclusion : Une mauvaise configuration de l’API expose non seulement les données, mais aussi les processus métiers. La sécurisation doit donc être intégrée dès le départ dans le workflow hybride.

2️⃣ Principes de base à appliquer | Principe | Description | Implémentation concrète |

|———-|————-|————————|
| Authentification forte | Utiliser des jetons qui ne peuvent pas être partagés ou interceptés. | OAuth2 / token généré par le serveur (JWT signé, durée courte). |
| Autorisation granulaire | Chaque token ne possède que les droits strictement nécessaires. | Création de rôles personnalisés (ex : “Facture‑Read‑Only”, “Dev‑Edit”). |
| Transmission chiffrée | Toute requête doit passer par HTTPS avec certificat valide. | Force TLS 1.2+, désactivation de TLS 1.0/1.1. |
| Limitation de l’exposition | Ne publier que les endpoints nécessaires aux scénarios métier. | Utiliser des routes limitées dans le fichier htdocs/api ou créer un reverse‑proxy dédié. |
| Audit & journalisation | Enregistrer chaque appel avec métadonnées (qui, quand, quoi, success/fail). | Activer logfile dans conf/persist.conf et analyser via ELK ou Graylog. |
| Mise à jour régulière | Patch des vulnérabilités du core et des modules complémentaires. | Planification d’un cycle de mise à jour trimestriel. |

3️⃣ Étapes détaillées de mise en place

Étape 1 – Préparer l’environnement de base

  1. Activer HTTPS 


    
#dans htdocs/.htaccess ou virtual host
    
RewriteEngine On   RewriteCond %{HTTPS} off
    
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
    
```     *Obligatoire* : certificat Let’s Encrypt ou CA interne.

  2. Restreindre l’accès à l’API 

    <Directory "/var/www/html/dolibarr/htdocs/api">
    
   Require ip 10.0.0.0/8            # IP interne de votre réseau d’entreprise       Require ip 192.168.100.0/24     # Sous‑réseau du bureau principal
    
   Require host vpn.mycompany.com  # Accès via VPN uniquement
    
</Directory>

  3. Configurer les logs 
    ; conf/persist.conf
    
logfile = /var/log/dolibarr/api_access.log
    
logerrorfile = /var/log/dolibarr/api_error.log
    
loglevel = 3        ; 0=off, 3=debug (à désactiver en prod)

Étape 2 – Créer un système d’authentification OAuth2

Dolibarr n’a pas d’API OAuth2 native, mais on peut l’ajouter via le module dolibarr_auth ou un reverse‑proxy comme Traefik avec middleware oauth2-proxy.

Option A – Utiliser mod_auth_openidc (Apache)

  1. Installer le module 

    sudo apt-get install libapache2-mod-auth-openidc
    
a2enmod auth_openidc

  2. Configurer le client OIDC (exemple avec Azure AD, Keycloak, ou Auth0) 

    <Location /api>
    
   AuthType OIDC       OIDCClientID your-client-id       OIDCClientSecret your-client-secret       OIDCSigningRequestLib curl       OIDCProviderMetadataURL https://login.mycompany.com/.well-known/openid-configuration
    
   Require valid-accounts
    
</Location>

    Chaque requête vers `/api/` passe par le serveur d’identité, renvoie un JWT signé.*

  3. Extraire le JWT dans votre logique API 

    // In api/index.php (ou endpoint dédié)
    
$jwt = $_SERVER['HTTP_AUTHORIZATION'] ?? '';
    
$token = substr($jwt, 7); //Bearer <token>
    
$payload = (array) json_decode(base64_decode(str_getcsv($token, '.')[0]), true);
    
$userId = $payload['sub']; // id de l’utilisateur   $roles  = $payload['roles'] ?? [];
    // Stockage dans $user->id, $user->rights, etc.

Option B – Générer un token “Dolibarr‑API‑Key”

  1. Créer une clé secrète (dans htdocs/core/api_keys.php – fichier non versionné) 

    <?php
    
define('API_GENERIC_KEY', 'R4nD0mS3cR3tK3y!2025');

  2. Endpoint de création de clé (exemple simple api/create_key.php) 

    <?php
    
require_once("../core.inc.php");
    
$user = new User($_REQUEST['user']); // id de l'utilisateur
    
$key = bin2hex(random_bytes(32));  // 64 caractères hex
    
$expires = date('Y-m-d H:i:s', strtotime('+30 days'));
    
$db->insert('user_api_keys', array(
    
   'user' => $user->id,
    
   'key'  => $key,
    
   'expires' => $expires,
    
   'status' => 'active'
    
));
    
echo json_encode(['key'=>$key,'expires'=>$expires]);

  3. Utilisation du token 

    GET /api.php?mode=test&key=abcd1234... HTTP/1.1
    
Host: api.mycompany.com

    Le serveur compare la clé avec la base de données, récupère les droits de l’utilisateur, puis accepte ou refuse l’appel.

Étape 3 – Définir des rôles et permissions

Rôle Description Droits API (méthodes HTTP)
admin Administrateur complet Tous les endpoints (GET/POST/PUT/DELETE)
billing_view Consultation de factures GET /invoice uniquement (en lecture)
purchase_order_editor Création/modif de commandes POST /order , PUT /order/{id}
read_only Accès en lecture seule GET /product, GET /customer

Mise en œuvre : Dans chaque méthode d’API, vérifier if (! $user->haveRight('module@action')) die('403');

Étape 4 – Limiter les appels (Rate‑Limiting & Quotas)

#/.htaccess

RewriteEngine On

RewriteCond %{REQUEST_URI} ^/api/.*$ [NC]

RewriteCond %{QUERY_STRING} ^api_key=([^&]+) [NC]

RewriteRule ^ - [E=API_KEY:%1]

Header set Access-Control-Allow-Origin "https://api.mycompany.com"

Header set Access-Control-Allow-Methods "GET,POST,PUT,DELETE,OPTIONS"

Header set Access-Control-Allow-Headers "Content-Type, Authorization"

SetEnvIfExpr %{ENV_VARIABLE} ^[A-Za-z0-9+/=]{60,62} api_key
# Limiter à 150 requêtes/5min par IP

RewriteCond %{ENV:API_KEY} ^[A-Za-z0-9+/=]{60,62}$

RewriteCond %{HTTP:X-RateLimit-Limit} ^$ 

RewriteCond %{REQUEST_URI} ^/api/.*$

RewriteCond %{REMOTE_ADDR} !^127\.0\.0\.1$

RewriteRule ^ - [E=RATE_EXCEEDED:1]

ErrorDocument 429 "Too Many Requests – 5 min limit reached"

Vous pouvez également implémenter cela dans le code PHP avec le $conf->global->set('apikey_rate', 150); ou via un middleware NGINX (limit_req_zone).

Étape 5 – Mettre en place la surveillance et les alertes

Outil Fonction Exemple de règle d’alerte
ELK (Elastic + Logstash + Kibana) Analyser les logs d’accès API source:api_access AND status:401 -> alert("AuthFailed")
Prometheus + Alertmanager Mettre des métriques sur le nombre d’appels api_requests_total{endpoint="invoice"} > 10000 → alerte
Grafana Dashboard temps réel Graphique des appels par rôle, temps de réponse, etc.
Fail2Ban Bloquer IPs malveillantes sur 403/429 récurrents filter.d/api-dolibarr.conf avec bantime = 3600

4️⃣ Bonnes pratiques spécifiques aux équipes hybrides

Situation Astuce Explication
Travail à distance (Wi‑Fi public) Utiliser un VPN d’entreprise ou un proxy inversé client‑side qui injecte le token dans chaque requête. Évite que le token soit intercepté en clair sur le réseau.
Collaborateurs avec appareils personnels Imposer la politique BYOD : les appareils doivent s’enregistrer auprès du MDM, installer le certificat API, et ne pas désactiver le pare‑feu. Réduit le risque de fuite de credentials via un logiciel non conforme.
Intégrations CI/CD (DevOps) Stocker le token d’API dans Vault ou GitHub Secrets et le récupérer au runtime, pas dans le repo git. Empêche que le token soit versionné ou exposé lors d’un git push.
Déploiement multi‑site Centraliser la configuration API via un ConfigMap ou Consul partagé, afin que chaque site utilise les mêmes paramètres et secrets. Garantit la cohérence des règles de sécurité (ex : même expiration des clés).
Formation continue Organiser des sessions mensuelles « Sécurité API Dolibarr » avec des scénarios de phishing ou de brute‑force. Sensibilise les équipes sur les risques et les procédures d’urgence.

5️⃣ Checklist de vérification avant le go‑live

✅ Item
1 HTTPS obligatoire sur tous les sous‑domaines d’API
2 Authentification OAuth2 / clé API configurée, expirée 30‑90 jours
3 Tous les endpoints exposés sont limités aux IPs ou à un VPN autorisé
4 Journalisation détaillée activée et les logs sont archivés (réduction > 30 jours)
5 Quotas de requêtes définis (ex : 150 req/min par rôle)
6 Tests d’intrusion automatisés (OWASP ZAP) passent avec 0 vulnérabilités critiques
7 Scénarios de rollback testés (ex : réactivation du mode “maintenance” si un token est compromis)
8 Documentation interne mise à jour (Swagger/OpenAPI, flux de création de token)
9 Alertes configurées dans Grafana/ELK pour les tentatives d’accès anormales
10 Audit de conformité interne (RGPD, ISO 27001) réalisé et archivé

— ## 6️⃣ Exemple de Swagger (OpenAPI) minimal pour l’API Dolibarr 

openapi: 3.0.3

info:

  title: Dolibarr Hybrid‑Team API

  version: 1.0.0

servers:

  - url: https://api.mycompany.com/dolibarr/api

    description: Production API (HTTPS)

security:

  - BearerAuth: []

components:

  securitySchemes:

    BearerAuth:

      type: http

      scheme: bearer

      bearerFormat: JWT

paths:

  /order:

    get:

      summary: Get orders (admin)

      security:

        - BearerAuth: []

      responses:

        '200':

          description: List of orders

        '403':

          description: Forbidden

    post:

      summary: Create order (purchase_editor)

      security:

        - BearerAuth: []

      requestBody:

        required: true

        content:

          application/json:

            schema:

              $ref: '#/components/schemas/OrderCreate'

      responses:

        '201':

          description: Order created

        '403':

          description: Not authorized

components:

  schemas:

    OrderCreate:

      type: object

      required: [client_id, product_ref, qty]

      properties:

        client_id:

          type: integer

        product_ref:

          type: string

        qty:

          type: integer

        date:

          type: string

          format: date

Cette spécification peut être générée automatiquement à partir des fichiers api/index.php et servira de contrat de sécurité partagé entre le DevOps, le Team QA, et les développeurs.

7️⃣ Conclusion

Le passage à une architecture hybride, où les collaborateurs se partagent des espaces de travail physiques et virtuels, rend la sécurisation de l’API Dolibarr inconsequential. En suivant le processus pas à pas présenté ci‑dessus :

  1. Forcer le chiffrement (HTTPS, TLS) 2. Authentifier chaque appel avec un token OAuth2 ou une clé API unique,

  2. Ne exposer que les endpoints strictement nécessaires,

  3. Limiter l’accès par IP/VPN et appliquer du rate‑limiting,

  4. Gouverner les droits via des rôles clairs,

  5. Auditer et alerter en continu,

vous obtenez une API fiable, traçable et résiliente, capable de soutenir les besoins d’une équipe qui travaille simultanément depuis le bureau, le home‑office ou en déplacement.

Prochaine étape : Implémentez les premiers éléments (HTTPS + création de clés) sur un environnement de test, validez à l’aide du Swagger généré, puis migrez progressivement vers la production en suivant la checklist.

Bonne sécurisation ! 🚀 —

Ce document a été rédigé par l’équipe Dolibarr Secure‑Hybrid – mise à jour le 3 novembre 2025.

Publications similaires