Serveur OAuth2/OIDC

SmartAuth intègre un serveur OAuth2 compatible OpenID Connect. Il permet d'utiliser Dolibarr comme fournisseur d'identité (Identity Provider) central pour le Single Sign-On (SSO) avec des applications tierces.

Activation

1. Allez dans Accueil > Configuration > Modules > SmartAuth
2. Ouvrez l'onglet Serveur OAuth
3. Cochez Activer le serveur OAuth/OIDC
4. Cliquez sur Enregistrer

Paramètres du serveur

URL de l'issuer

L'URL de l'issuer identifie votre serveur OAuth. Si vous laissez ce champ vide, SmartAuth utilise l'URL auto-détectée de votre installation Dolibarr.

Durées des jetons

Sécurité

Endpoints OIDC

Lorsque le serveur OAuth est activé, les endpoints suivants sont disponibles :

Ces URLs sont affichées directement dans l'onglet de configuration du serveur OAuth après activation.

API interne : autoriser un client

Les routes que les modules de l'instance exposent en oauth2 (l'API interne, dite first-party) sont fermées par défaut. Sans cela, n'importe quel client OAuth de l'instance pourrait appeler n'importe quelle route de n'importe quel module avec les droits de son utilisateur de service.

La fiche d'un client OAuth affiche donc son état et porte les deux boutons correspondants :

C'est le symptôme à connaître : les identifiants sont bons, le jeton est délivré, la route est trouvée, et l'appel est refusé quand même. Le journal Dolibarr le nomme : SMARTAUTH_API_AUDIENCE not set - refusing <client_id>.

Les boutons écrivent la constante SMARTAUTH_API_AUDIENCE, qui est une liste : autoriser un client ne touche pas les autres, et le retirer non plus. Le retrait demande une confirmation, les appels du produit concerné s'arrêtant aussitôt.

Portail SSO public

SmartAuth fournit un portail web public (htdocs/custom/smartauth/public/) destiné à être exposé sur un sous-domaine dédié (par exemple https://auth.exemple.fr). Ce portail sert :

Tous les visuels (CSS, logo, polices) sont chargés en same-origin depuis /assets/.

Configuration du vhost Apache

Créez un vhost dédié pointant sur htdocs/custom/smartauth/public/ comme DocumentRoot. Exemple minimal :

<VirtualHost *:443>
    ServerName auth.exemple.fr
    DocumentRoot /var/www/dolibarr/htdocs/custom/smartauth/public

    SSLEngine on
    SSLCertificateFile      /etc/letsencrypt/live/auth.exemple.fr/fullchain.pem
    SSLCertificateKeyFile   /etc/letsencrypt/live/auth.exemple.fr/privkey.pem

    <Directory /var/www/dolibarr/htdocs/custom/smartauth/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    # RFC 8615 reserves /.well-known/ for service discovery (OIDC, ACME...).
    # La config Apache par défaut sur Debian/Ubuntu interdit globalement
    # les chemins commençant par un point ; cette exception est obligatoire
    # pour que les endpoints de discovery OIDC soient accessibles.
    <LocationMatch "^/\.well-known/">
        Require all granted
    </LocationMatch>

    ErrorLog  ${APACHE_LOG_DIR}/auth.exemple.fr-error.log
    CustomLog ${APACHE_LOG_DIR}/auth.exemple.fr-access.log combined
</VirtualHost>

Validez la configuration et rechargez Apache :

sudo apache2ctl configtest
sudo systemctl reload apache2

À retenir : AllowOverride All est nécessaire pour que le .htaccess fourni par le module (public/.htaccess) soit pris en compte (réécritures vers index.php, headers de sécurité, MIME types des assets).

Résoudre "Forbidden" sur /.well-known/

Si la requête https://auth.exemple.fr/.well-known/openid-configuration répond 403 Forbidden, c'est que la règle globale Apache <DirectoryMatch "(^|/)\."> (commune sur Debian/Ubuntu) bloque le chemin avant même que le .htaccess du module ne s'exécute. Le <LocationMatch> indiqué plus haut résout le problème en autorisant explicitement /.well-known/.

Diagnostic sur le serveur :

# Repérer la règle qui bloque
sudo grep -rni "well-known\|directorymatch" /etc/apache2/ | head

# Confirmer dans le journal d'erreurs
sudo tail -30 /var/log/apache2/error.log | grep -i "denied\|forbid\|well-known"

Test après application du fix :

curl -i https://auth.exemple.fr/.well-known/openid-configuration

Doit renvoyer HTTP/1.1 200 et un corps JSON contenant "issuer", "authorization_endpoint", etc.

Constante SMARTAUTH_APP_URL

Le lien envoyé par email pour réinitialiser un mot de passe pointe par défaut sur DOL_MAIN_URL_ROOT (l'URL principale de Dolibarr). Pour que ce lien arrive sur le portail SSO et non sur l'admin Dolibarr, définissez la constante SMARTAUTH_APP_URL :

1. Allez dans Accueil > Configuration > Divers
2. Ajoutez/modifiez la constante SMARTAUTH_APP_URL avec pour valeur l'URL racine du portail (exemple : https://auth.exemple.fr)
3. Enregistrez

Le mail de réinitialisation contiendra alors un lien https://auth.exemple.fr/reset-password?token=...&email=... qui ouvre directement le formulaire sur le portail SSO.

Activation / désactivation des parcours self-service

Deux constantes Dolibarr contrôlent l'affichage des cartes "Créer un compte" et "Mon compte" sur la page d'accueil du portail :

Définissez-les à 0 pour masquer les parcours correspondants si votre déploiement ne les autorise pas (exemple : inscriptions réservées à un workflow externe).

Gestion des clients OAuth

Créer un client

1. Depuis l'onglet Serveur OAuth, cliquez sur Clients OAuth ou accédez directement à la liste des clients
2. Cliquez sur Nouveau client
3. Renseignez les informations du client :

Scopes disponibles

Des scopes personnalisés peuvent être enregistrés par les modules externes.

Client confidentiel ou public

• Client confidentiel -- Application serveur capable de protéger un secret (exemple : backend WordPress, Nextcloud). Un secret est généré et affiché une seule fois lors de la création.
• Client public (PKCE) -- Application mobile ou SPA qui ne peut pas stocker un secret en toute sécurité. L'authentification utilise PKCE (Proof Key for Code Exchange) à la place.

Attention : Le secret client est affiché une seule fois lors de la création. Copiez-le et conservez-le dans un endroit sécurisé. Il ne peut pas être récupéré ultérieurement. Vous pouvez toutefois le régénérer si nécessaire.

Gérer un client existant

Depuis la liste des clients OAuth, vous pouvez :

• Consulter -- Voir les détails du client, ses jetons actifs et le dernier jeton émis
• Modifier -- Mettre à jour les URIs de redirection, les scopes et les grants autorisés
• Activer/Désactiver -- Activer ou désactiver temporairement un client
• Régénérer le secret -- Générer un nouveau secret (l'ancien est immédiatement invalidé)
• Supprimer -- Supprimer le client et révoquer tous ses jetons

Client Credentials (machine-à-machine)

Le grant type client_credentials permet l'authentification entre serveurs sans interaction utilisateur.

Configuration

1. Créez un client OAuth de type confidentiel
2. Activez le grant type Client Credentials
3. Définissez un utilisateur de service sur la fiche du client

L'utilisateur de service détermine les permissions et l'entité pour les opérations effectuées par le client. Si aucun utilisateur de service n'est défini sur le client, SmartAuth utilise l'utilisateur par défaut global (constante SMARTAUTH_DEFAULT_USER).

Fonctionnement

1. Le client envoie grant_type=client_credentials avec son client_id et client_secret
2. SmartAuth valide les identifiants et les scopes demandés
3. SmartAuth retourne un access_token JWT (pas de refresh token ni d'id_token en mode client credentials)

Intégration Dolibarr (SSO)

SmartAuth peut servir de fournisseur d'authentification pour une autre instance Dolibarr.

Création du client Dolibarr

1. Allez dans l'onglet Serveur OAuth
2. Dans la section Intégration Dolibarr, cliquez sur Créer le client Dolibarr
3. Indiquez l'URI de redirection de votre instance Dolibarr cible, sous la forme https://votre-dolibarr/index.php?afteroauthloginreturn=1 : c'est le paramètre afteroauthloginreturn qui fait traiter le retour du SSO par Dolibarr. À la réactivation du module, cette variante est ajoutée automatiquement à côté de chaque URI .../index.php déjà enregistrée sur le client dolibarr-erp.

Configuration de l'instance Dolibarr cible

Après la création du client, l'onglet affiche les instructions de configuration :

1. Si SmartAuth n'est pas activé sur l'instance cible, copiez-y le fichier d'authentification (s'il l'est, Dolibarr le trouve dans le module) :

    cp htdocs/custom/smartauth/core/login/functions_smartauthoauth.php \
       /chemin/vers/dolibarr/htdocs/core/login/

2. Modifiez le fichier conf.php de l'instance cible :

    $dolibarr_main_authentication = 'smartauthoauth,dolibarr';

3. Configurez les constantes Dolibarr sur l'instance cible :

   Constante	Valeur
   SMARTAUTH_OAUTH_ISSUER	URL de votre serveur SmartAuth
   SMARTAUTH_OAUTH_CLIENT_ID	dolibarr-erp

Test de connexion

Depuis l'onglet Serveur OAuth, utilisez le bouton Tester la connexion pour vérifier que le serveur SmartAuth est accessible via l'endpoint de discovery.