— Guide d’installation
Connexion
OAuth Microsoft
× Dolibarr.
Mise en place complète de l’authentification moderne pour l’envoi d’e-mails depuis Dolibarr via Microsoft 365. Couvre les deux modes : configuration globale (une boîte pour Dolibarr) et MultiSMTP (par utilisateur).
— Vue d’ensemble
La procédure en 4 phases.
L’installation s’enchaîne dans cet ordre strict. Les deux premières phases sont réalisées côté Microsoft (Azure / Entra ID + Centre d’admin M365), les deux suivantes côté Dolibarr.
1
Microsoft Azure / Entra ID
Inscrire l’application
Créer une App Registration, récupérer Client ID + Secret + Tenant ID, configurer les permissions API et le consentement administrateur.
2
Microsoft 365 Admin
Activer SMTP authentifié
Sur la boîte cible, cocher « SMTP authentifié ». Obligatoire même avec OAuth2. Sans cela, erreur 535 garantie.
3
Dolibarr — OAuth
Configurer le fournisseur
Activer le module OAuth, créer un service Microsoft Exchange Online, générer le token. Deux variantes selon le mode choisi.
4
Dolibarr — Mails
Paramétrer l’envoi
Configurer la méthode d’envoi, le serveur SMTP, l’identifiant et le service OAuth associé. Tester l’envoi en bout de chaîne.
Choix du mode : global ou par utilisateur ?
Dolibarr permet deux approches pour OAuth. Faire ce choix avant de commencer la phase 3 — la procédure diverge à partir de là.
Mode global
Une boîte pour tout Dolibarr
Tous les utilisateurs envoient depuis la même adresse (typiquement contact@ ou noreply@). Configuration unique au niveau de l’entité Dolibarr.
- Installation simple, paramétrage 1 fois
- Une seule App Registration Azure
- Adapté aux petites équipes ou aux envois automatisés
- Réponses centralisées sur une boîte unique
Mode MultiSMTP
Une configuration par utilisateur
Chaque collaborateur envoie depuis sa propre adresse personnelle. Module MultiSMTP requis. Configuration sur chaque fiche utilisateur.
- Module MultiSMTP à installer en plus
- Un service OAuth par boîte (suffixes :
-jdupont, -mmartin…)
- Chaque utilisateur fait son propre consentement
- Adapté aux équipes commerciales, support, secrétariat
— Phase 1 · Microsoft Azure / Entra ID
Inscrire l’application Dolibarr
dans Entra ID.
Cette phase est unique pour toute l’organisation, même en mode MultiSMTP avec plusieurs boîtes. Une seule App Registration Azure suffit ; les différents utilisateurs s’y rattachent ensuite via leur consentement.
-
1.1
Accéder au portail Microsoft Entra
Se connecter à entra.microsoft.com (accès direct, recommandé depuis 2024) ou à portal.azure.com et chercher Microsoft Entra ID. Les deux portails donnent accès au même service.
-
1.2
Créer l’inscription d’application
Naviguer vers Identité → Applications → Inscriptions d’applications → Nouvelle inscription.
Nom = Dolibarr OAuth
Types de comptes = Comptes dans cet annuaire organisationnel uniquement
URI de redirection = Web — laisser vide pour l’instant
Valider. La page Vue d’ensemble de l’application s’affiche.
-
1.3
Récupérer les identifiants
Sur la page Vue d’ensemble, copier et conserver précieusement :
ID d’application (client)
ID de l’annuaire (locataire)
-
1.4
Générer le secret client
Menu Certificats & secrets → + Nouveau secret client. Donner une description, choisir une durée (24 mois recommandé).
⚠ Copier immédiatement la « Valeur » du secret (et non l’ID). Cette valeur ne sera plus jamais affichée par la suite. Noter aussi la date d’expiration au calendrier IT — il faudra la renouveler avant cette date.
-
1.5
Configurer les permissions API — étape critique
Menu Autorisations de l’API → + Ajouter une autorisation. Sélectionner Office 365 Exchange Online (et non Microsoft Graph) → Autorisations déléguées.
Important — uniquement Exchange Online
Dans Dolibarr (v23+), seule l’API Office 365 Exchange Online fonctionne pour l’envoi SMTP via OAuth2. Les permissions équivalentes côté Microsoft Graph (Mail.Send, Mail.Read) ne sont pas reconnues par le flux SMTP XOAUTH2 utilisé par Dolibarr. Erreur classique : configurer les scopes côté Graph et obtenir un token valide… qui sera refusé en 535 par le serveur SMTP.
Ajouter les permissions une par une (utiliser la barre de recherche en haut de la liste pour les trouver rapidement) :
SMTP.Send
IMAP.AccessAsUser.All
User.Read
offline_access
⚠ Cliquer ensuite sur « Accorder un consentement d’administrateur pour [organisation] » et confirmer. Le statut de chaque permission doit passer au vert. Sans cette étape, le token sera émis mais refusé à l’envoi.
Articulation Azure ↔ Dolibarr
Ces permissions sont déclarées ici dans Azure (ce que l’application a le droit de demander). Elles seront ensuite cochées côté Dolibarr dans le champ Étendues du service OAuth (phase 3, ce qui est effectivement demandé au consentement). Les deux côtés doivent être alignés : une permission non déclarée dans Azure mais demandée dans Dolibarr → erreur invalid_scope.
— Phase 2 · Microsoft 365 Admin
Activer SMTP authentifié
sur la boîte cible.
Étape souvent oubliée, qui génère 80 % des échecs 5.7.139. À faire pour chaque boîte qui enverra des e-mails depuis Dolibarr.
Idée reçue à corriger
Oui, c’est obligatoire même avec OAuth2. Beaucoup pensent qu’OAuth2 remplace SMTP authentifié — c’est faux. OAuth2 remplace seulement le couple login / mot de passe (Basic Auth). La capacité même d’authentifier en SMTP (par n’importe quelle méthode) reste contrôlée par cette case. Sans elle, le serveur refuse la connexion AUTH XOAUTH2 au niveau du protocole, peu importe la validité du token.
-
2.1
Accéder au Centre d’administration Microsoft 365
Se connecter à admin.microsoft.com avec un compte administrateur global ou administrateur Exchange.
-
2.2
Ouvrir la boîte concernée
Naviguer vers Utilisateurs → Utilisateurs actifs. Sélectionner le compte qui enverra les e-mails depuis Dolibarr.
-
2.3
Activer la case SMTP authentifié
Onglet Courrier → Gérer les applications de courrier. Cocher SMTP authentifié. Enregistrer.
En mode MultiSMTP, répéter cette étape pour chaque boîte qui sera utilisée comme expéditeur.
Vérification au niveau du tenant
Si l’option n’apparaît pas ou reste grisée, vérifier que le paramètre tenant Disable SMTP AUTH for the organization est désactivé (Centre d’admin Exchange → Paramètres → Courrier). Une politique d’accès conditionnel (Conditional Access) qui bloque les clients legacy peut également refuser SMTP — la vérifier également si l’option reste grisée.
— Phase 3a · Dolibarr · mode global
Configurer OAuth pour
une boîte unique.
À suivre si vous avez choisi le mode global (une boîte pour tout Dolibarr). Pour le mode MultiSMTP, voir la phase 3b.
-
3a.1
Activer le module OAuth
Accueil → Configuration → Modules. Repérer le module OAuth et l’activer.
-
3a.2
Créer le service OAuth Microsoft
Accueil → Configuration → OAuth → Onglet Services OAuth. Ajouter une nouvelle entrée.
Fournisseur = Microsoft Exchange Online [SMTP/IMAP]
ID Client = [Application client ID depuis Azure — phase 1.3]
Secret Client = [Valeur du secret — phase 1.4]
Locataire = [Tenant ID — phase 1.3]
Étendues (scopes) : Dolibarr affiche une liste de cases à cocher correspondant aux permissions disponibles. Cocher les mêmes permissions que celles ajoutées côté Azure en phase 1.5 :
☑ SMTP.Send
☑ IMAP.AccessAsUser.All
☑ User.Read
☑ offline_access
Le bon fournisseur
Choisir Microsoft Exchange Online [SMTP/IMAP] dans la liste déroulante. L’ancien fournisseur Microsoft [outlook.office365] est conservé pour compatibilité mais le nouveau est plus fiable et correctement configuré pour SMTP. Disponible à partir de Dolibarr v23.
-
3a.3
Configurer l’URL de redirection côté Azure
Dolibarr affiche maintenant une URL de redirection sur la fiche du service OAuth. La copier.
Retourner sur l’application Azure (phase 1) → menu Authentification → + Ajouter un URI de redirection. Sélectionner Web et coller l’URL Dolibarr. Enregistrer.
-
3a.4
Générer le jeton (Token)
Retour sur Dolibarr → service OAuth créé → onglet Jeton d’accès → Générer le jeton (ou Grant access).
Une fenêtre Microsoft s’ouvre. Se connecter avec le compte e-mail qui enverra les mails (celui activé phase 2). Accepter les permissions.
💡 Ouvrir une fenêtre de navigation privée pour éviter d’être connecté à un autre compte Microsoft par erreur.
-
3a.5
Vérifier le jeton
De retour dans Dolibarr, vérifier que le champ refreshToken n’est pas à null. C’est la garantie du renouvellement automatique.
⚠ Si refreshToken = null : offline_access n’est pas présent dans les scopes (vérifier côté Azure ET côté Dolibarr). Sans refresh token, le mail fonctionnera pendant 1 heure puis tombera en panne silencieusement — il faudra ré-autoriser manuellement toutes les heures.
— Phase 3b · Dolibarr · mode MultiSMTP
Configurer OAuth par
utilisateur (MultiSMTP).
Variante du mode global, à suivre si vous avez choisi une boîte d’envoi par utilisateur. Le module MultiSMTP doit être installé et activé au préalable.
-
3b.1
Activer les modules OAuth et MultiSMTP
Configuration → Modules. Activer OAuth et MultiSMTP. Un nouvel onglet MultiSMTP apparaît sur chaque fiche utilisateur.
-
3b.2
Créer un service OAuth par boîte mail
Configuration → OAuth. Créer un nouveau service Microsoft Exchange Online pour chaque boîte, nommé avec un suffixe unique :
Nom du service = MICROSOFT-jdupont
Nom du service = MICROSOFT-mmartin
Les valeurs Client ID, Secret, Tenant et Scopes sont identiques d’un service à l’autre (même application Azure). Seul le suffixe diffère — c’est l’identifiant interne (keyforprovider) qui rattache un token distinct à chaque utilisateur.
-
3b.3
Associer chaque service à son utilisateur
Pour chaque utilisateur, ouvrir Utilisateurs & Groupes → fiche utilisateur → onglet MultiSMTP → Modifier :
Méthode d’authentification = XOAUTH2
Identifiant SMTP = jean.dupont@orep-securite.com
Jeton OAuth à utiliser = MICROSOFT-jdupont
Laisser les autres champs (serveur, port, TLS) vides : les valeurs globales seront utilisées. Enregistrer.
-
3b.4
Consentement OAuth — par l’utilisateur lui-même
L’utilisateur se connecte à Dolibarr avec son propre compte, ouvre sa fiche utilisateur → onglet MultiSMTP. Le bouton « Obtenir un nouveau jeton » apparaît à côté de la ligne Gestion du token OAuth2.
Il clique : redirection vers Microsoft → s’authentifier avec sa propre adresse e-mail → accepter les permissions.
Étape critique
Si l’administrateur Dolibarr fait le consentement à la place de l’utilisateur depuis sa propre session Microsoft, le token sera émis sur la boîte de l’administrateur. C’est l’utilisateur final qui doit cliquer, depuis sa session Dolibarr, et s’authentifier avec son propre compte Microsoft. Fenêtre privée recommandée pour éviter les confusions de session.
— Phase 4 · Dolibarr · paramétrage des e-mails
Configurer l’envoi
et tester.
Cette phase finalise la chaîne en branchant Dolibarr sur le service OAuth créé précédemment. La même configuration s’applique aux deux modes ; en MultiSMTP, elle sert de valeurs globales par défaut.
-
4.1
Ouvrir la configuration des e-mails
Accueil → Configuration → E-mails → Modifier.
-
4.2
Choisir la méthode d’envoi
Méthode d’envoi recommandée : SMTP/SMTPS socket library (PHPMailer). C’est la méthode supportée et maintenue par Dolibarr aujourd’hui.
Et Swift Mailer ?
Swift Mailer est officiellement déprécié depuis novembre 2021 (remplacé par Symfony Mailer côté upstream). Dans Dolibarr, l’option subsiste dans certaines versions pour compatibilité, mais elle n’est plus la recommandation. Utiliser SMTP/SMTPS socket library en priorité, et basculer sur Swift Mailer uniquement si la première méthode échoue pour des raisons spécifiques à l’environnement.
-
4.3
Saisir les paramètres SMTP
Hôte SMTP = smtp.office365.com
Port = 587
Chiffrement (STARTTLS) = Oui
Identifiant SMTP = [adresse e-mail complète de l’expéditeur]
Authentification = OAuth2 / XOAUTH2
Service OAuth = [le service créé en phase 3]
Expéditeur (From) = [la même adresse que l’identifiant SMTP]
⚠ L’Identifiant SMTP et l’adresse From doivent être identiques, et identiques à l’adresse du compte qui a fait le consentement OAuth. Sinon : erreur 5.7.60 — Client does not have permissions to send as this sender.
-
4.4
Enregistrer et tester
Cliquer sur Enregistrer. Puis en bas de la page, section Tester la disponibilité du serveur, saisir une adresse de destination et envoyer un e-mail de test.
Le résultat s’affiche immédiatement. Vérifier également la réception côté destinataire (parfois le test indique succès mais le message arrive en spam).
✓ Configuration complète
Si le test passe, tous les e-mails envoyés depuis Dolibarr partiront via OAuth2 sur la boîte configurée. Aucun mot de passe stocké, renouvellement automatique du token tant que le refresh est valide (90 jours glissants).
— Dépannage
Les erreurs les plus
fréquentes.
Chaque erreur ci-dessous renvoie à une cause précise et une action à mener. La localisation indique où le problème se trouve réellement (Azure, M365, Dolibarr ou réseau).
refreshToken = null
Localisation : Azure — scope manquant
Le token expire au bout d’une heure et n’est pas renouvelé
Cause : le scope offline_access n’a pas été demandé au moment du consentement. Solution : vérifier que offline_access est présent (1) côté Azure dans les permissions API et (2) côté Dolibarr dans le champ Étendues. Re-générer le token après correction.
535 5.7.139
Localisation : Microsoft 365 — SMTP authentifié désactivé
Authentication unsuccessful — SMTP AUTH disabled
Cause : la case SMTP authentifié n’est pas cochée sur la boîte ou la politique tenant bloque SMTP AUTH. Erreur fréquente — beaucoup pensent que cocher cette case n’est plus nécessaire avec OAuth2. Solution : retourner phase 2 et activer SMTP authentifié sur la boîte. Vérifier également la politique tenant et les règles Conditional Access.
5.7.60
Localisation : Dolibarr — From ≠ identifiant SMTP
Client does not have permissions to send as this sender
Cause : l’adresse From diffère de l’identifiant SMTP, ou diffère de l’adresse du compte qui a consenti. Solution : aligner les trois adresses (From = identifiant SMTP = compte du consentement OAuth). Si l’envoi doit se faire au nom d’une boîte partagée, accorder explicitement Send As dans Exchange.
AADSTS65001
Localisation : Azure — consentement admin manquant
The user or administrator has not consented
Cause : consentement administrateur non accordé sur les permissions API. Solution : retourner Azure → Autorisations de l’API → cliquer sur Accorder un consentement d’administrateur pour [organisation]. Vérifier que toutes les permissions passent au vert.
AADSTS7000215
Localisation : Azure — secret client invalide
Invalid client secret provided
Cause : secret expiré, ou mal copié (espaces, troncature). Solution : Azure → Certificats & secrets → générer un nouveau secret → recopier la Valeur immédiatement → mettre à jour le service OAuth dans Dolibarr.
AADSTS70008
Localisation : Microsoft — refresh token expiré ou révoqué
The refresh token has expired or been revoked
Cause : mot de passe Microsoft changé, sessions révoquées par l’admin, ou 90 jours sans envoi. Solution : retourner sur le service OAuth Dolibarr → cliquer à nouveau sur Générer le jeton (ou « Obtenir un nouveau jeton » en MultiSMTP) → refaire le consentement.
invalid_scope
Localisation : Azure — scope absent ou mal écrit
The scope is not valid
Cause : permission demandée non autorisée sur l’application, ou scope mal orthographié. Solution : vérifier que les permissions SMTP.Send, offline_access sont bien sur Office 365 Exchange Online (pas Microsoft Graph). Vérifier l’orthographe exacte du scope dans Dolibarr : offline_access https://outlook.office365.com/SMTP.Send.
Connection timeout
Localisation : réseau — port 587 bloqué
Timeout sur smtp.office365.com:587
Cause : port 587 sortant bloqué par le pare-feu de l’hébergeur ou du client. Solution : ouvrir le port 587 sortant vers smtp.office365.com. Tester depuis le serveur : swaks --to test@externe.com --server smtp.office365.com:587 --tls ou simplement openssl s_client -connect smtp.office365.com:587 -starttls smtp.
