User Documentation
Télécharger
Lancer

Configuration OAuth 2.0 SMTP dans Joomla!

Depuis la version 6.2, Joomla prend en charge l'authentification OAuth 2.0 pour les connexions SMTP.

Plutôt que de stocker le mot de passe du compte SMTP, Joomla autorise l'accès via le fournisseur de messagerie. Le fournisseur renvoie un jeton de rafraîchissement de longue durée, que Joomla peut ensuite utiliser pour demander des jetons d'accès de courte durée pour l'authentification SMTP.

Le flux de base est le suivant :

Joomla
  ↓
Page d'autorisation du fournisseur OAuth
  ↓
L'utilisateur se connecte et autorise l'accès
  ↓
Le fournisseur redirige vers Joomla
  ↓
Joomla reçoit un code d'autorisation
  ↓
Joomla échange le code contre des jetons
  ↓
Le jeton de rafraîchissement est stocké
  ↓
Les jetons d'accès sont créés lorsque l'authentification SMTP est requise

Le mot de passe SMTP n'est donc pas utilisé pour l'authentification OAuth 2.0.

Avant de commencer

La configuration comporte plusieurs étapes.

  1. Créer ou enregistrer une application OAuth auprès de votre fournisseur de messagerie.
  2. Configurer l'URI de redirection autorisée pour l'application.
  3. Configurer les droits SMTP ou les scopes OAuth requis.
  4. Créer un Id client et un Secret client.
  5. Si le fournisseur l'exige, publier, déployer ou activer l'application OAuth.
  6. Attendre que les modifications côté fournisseur soient propagées. Selon le fournisseur et la configuration du locataire, cela peut prendre jusqu'à environ une heure.
  7. Saisir les paramètres OAuth dans Joomla.
  8. Enregistrer la configuration Joomla.
  9. Démarrer l'autorisation OAuth depuis Joomla.
  10. Se connecter au compte SMTP et accorder le droit demandé.
  11. Vérifier que Joomla a reçu et stocké un jeton de rafraîchissement.
  12. Envoyer un e-mail de test.

Ne supposez pas qu'une application OAuth nouvellement créée ou modifiée est immédiatement utilisable. Les modifications de configuration côté fournisseur peuvent mettre un certain temps avant de devenir effectives.

Paramètres OAuth 2.0 de Joomla

Ouvrir :

Système
→ Configuration Générale
→ Serveur
→ Courriel

Sélectionner :

Logiciel d'envoi des courriels : SMTP
Authentification SMTP : OAuth 2.0

Joomla affiche alors les champs de configuration OAuth 2.0.

Adresse d'expédition

L'Adresse d'expédition configurée doit correspondre à la boîte aux lettres utilisée comme identifiant SMTP.

Exemple :

Adresse d'expédition :
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

Identifiant SMTP :
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

Pour la configuration SMTP OAuth 2.0 standard, les deux valeurs doivent faire référence à la même boîte aux lettres.

L'utilisation d'une adresse d'expédition différente peut nécessiter des droits supplémentaires côté fournisseur, tels que Envoyer en tant que, des alias, ou des droits de boîte aux lettres délégués, et peut sinon amener le fournisseur à rejeter le message.

Identifiant SMTP

L'identifiant SMTP identifie la boîte aux lettres que Joomla utilise pour l'authentification SMTP.

Il s'agit généralement de l'adresse e-mail complète :

Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

Le compte autorisé lors du flux OAuth doit normalement être le même compte.

Id client OAuth2

L'Id client identifie l'application OAuth enregistrée auprès du fournisseur de messagerie.

Il est généré par le fournisseur lors de la création de l'application ou du client OAuth.

Exemple :

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

L'Id client n'est pas un secret.

Secret client OAuth2

Le Secret client authentifie l'application OAuth Joomla auprès du fournisseur.

Il est créé par le fournisseur en même temps que l'application OAuth, ou après sa création.

Exemple :

OAuth2 Client Secret:
••••••••••••••••

Le Secret client doit rester confidentiel.

Il ne doit pas être :

  • publié
  • versionné dans un dépôt public
  • inclus dans la documentation
  • partagé entre des installations Joomla sans lien, sauf utilisation intentionnelle de la même application OAuth

Scope OAuth2

Le scope indique au fournisseur quels droits Joomla demande.

Les scopes sont spécifiques à chaque fournisseur.

Pour l'authentification SMTP, le scope accorde généralement le droit d'accéder ou d'envoyer des e-mails via la boîte aux lettres de l'utilisateur.

Un ou plusieurs scopes peuvent être demandés.

Si plusieurs scopes sont requis, ils sont normalement séparés par des espaces :

scope1 scope2 scope3

La valeur exacte du scope dépend du fournisseur de messagerie.

URL d'autorisation OAuth2

L'URL d'autorisation est le point de terminaison du fournisseur où l'utilisateur se connecte et accorde l'accès à Joomla.

Joomla redirige l'administrateur vers cette URL lorsque l'autorisation OAuth est démarrée.

Le fournisseur alors :

  1. authentifie l'utilisateur
  2. affiche les droits demandés
  3. demande un consentement si nécessaire
  4. redirige le navigateur vers Joomla

L'URL exacte dépend du fournisseur.

URL du jeton OAuth2

L'URL du jeton est le point de terminaison du fournisseur utilisé par Joomla pour échanger les identifiants OAuth.

Elle est utilisée pour deux opérations importantes.

D'abord, après l'autorisation :

authorization code
    ↓
token endpoint
    ↓
access token + refresh token

Plus tard :

refresh token
    ↓
token endpoint
    ↓
new access token

L'administrateur n'interagit normalement jamais directement avec ce point de terminaison.

URI de redirection OAuth

Les fournisseurs OAuth exigent que l'URL de rappel de Joomla soit enregistrée auprès de l'application OAuth.

Pour Joomla, l'URL de rappel est :

https://www.example.com/administrator/index.php?option=com_config&task=mail.oauth2callback&format=raw

Remplacer :

https://www.example.com

par l'URL réelle du site Joomla.

L'URI de redirection configurée chez le fournisseur doit correspondre à l'URI envoyée par Joomla lors de l'autorisation.

Vérifier en particulier :

  • le protocole
  • le nom d'hôte
  • le chemin
  • la chaîne de requête
  • le chemin d'administration de Joomla

Par exemple :

https://example.com/administrator/index.php?option=com_config&task=mail.oauth2callback&format=raw

et :

https://www.example.com/administrator/index.php?option=com_config&task=mail.oauth2callback&format=raw

sont des URI de redirection différentes.

Microsoft 365

TL;DR

Pour une configuration Microsoft 365 mono-tenant typique, utiliser :

SMTP Host:
smtp.office365.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

SMTP Username:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

OAuth2 Client ID:
<Application (client) ID>

OAuth2 Client Secret:
<Client Secret Value>

OAuth2 Scope:
https://outlook.office.com/SMTP.Send offline_access

OAuth2 Authorize URL:
https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize

OAuth2 Token URL:
https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token

Enregistrer cette URI de redirection dans Microsoft Entra :

https://www.example.com/administrator/index.php?option=com_config&task=mail.oauth2callback&format=raw

Vérifier également que l'option SMTP authentifié est activée pour la boîte aux lettres.

Après avoir modifié l'application, les droits ou les paramètres Exchange, prévoyez jusqu'à environ une heure pour que les changements se propagent.

Aperçu général

La configuration Microsoft comprend :

  1. Enregistrer une application dans Microsoft Entra.
  2. Configurer l'URI de redirection Joomla.
  3. Configurer les droits SMTP délégués.
  4. Créer un Secret client.
  5. S'assurer que SMTP AUTH est activé pour la boîte aux lettres.
  6. Attendre, si nécessaire, que les modifications de configuration se propagent.
  7. Saisir les paramètres de l'application dans Joomla.
  8. Autoriser la boîte aux lettres via Joomla.

Les modifications apportées aux enregistrements d'applications, aux droits, au consentement ou aux paramètres Exchange peuvent ne pas prendre effet immédiatement. Dans certains environnements, la propagation peut prendre jusqu'à environ une heure.

1. Enregistrer l'application

Ouvrir le centre d'administration Microsoft Entra.

Naviguer vers :

Identity
→ Applications
→ App registrations
→ New registration

Saisir un nom tel que :

Joomla SMTP OAuth

Pour une installation Joomla utilisée avec une seule organisation Microsoft 365, un enregistrement mono-locataire convient généralement :

Accounts in this organizational directory only

Après l'enregistrement, noter :

Application (client) ID
Directory (tenant) ID

Les deux valeurs sont disponibles sur la page Overview de l'application.

2. Configurer l'URI de redirection

Ouvrir :

App registrations
→ Joomla SMTP OAuth
→ Authentication

Ajouter une plateforme :

Web

Enregistrer l'URL de rappel Joomla :

https://www.example.com/administrator/index.php?option=com_config&task=mail.oauth2callback&format=raw

Utiliser l'URL réelle du site Joomla.

3. Configurer les droits SMTP

Joomla nécessite un accès SMTP délégué.

Le droit SMTP est :

https://outlook.office.com/SMTP.Send

Joomla nécessite également un jeton de rafraîchissement afin que l'authentification SMTP continue de fonctionner sans que l'administrateur ait à se reconnecter.

Par conséquent, le scope Joomla doit inclure :

offline_access

Le scope final est :

https://outlook.office.com/SMTP.Send offline_access

Selon les politiques Microsoft Entra de l'organisation, un consentement administrateur peut être requis.

4. Créer le secret client

Naviguer vers :

App registrations
→ Joomla SMTP OAuth
→ Certificates & secrets
→ Client secrets
→ New client secret

Créer un secret.

Microsoft affiche des valeurs telles que :

Secret ID
Value

Joomla requiert la valeur réelle :

Value

Ne pas saisir le Secret ID.

Enregistrer le secret immédiatement car Microsoft peut n'afficher la valeur qu'une seule fois.

5. Activer SMTP AUTH

L'autorisation OAuth seule n'est pas suffisante si SMTP AUTH est désactivé pour la boîte aux lettres.

Dans le centre d'administration Microsoft 365, vérifier l'utilisateur concerné.

Naviguer approximativement vers :

Users
→ Active users
→ User
→ Mail
→ Manage email apps

S'assurer que :

Authenticated SMTP

est activé.

Les politiques Exchange Online à l'échelle de l'organisation ou les paramètres de sécurité Microsoft peuvent également désactiver SMTP AUTH.

Si le flux OAuth réussit mais que le SMTP échoue toujours, ce paramètre doit être l'un des premiers éléments à vérifier.

Les modifications des paramètres Exchange ou de la boîte aux lettres peuvent mettre un certain temps à se propager.

6. Configurer Joomla

Utiliser :

SMTP Host:
smtp.office365.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

SMTP Username:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

L'Adresse d'expédition et l'Identifiant SMTP doivent normalement être identiques.

L'utilisation d'une adresse d'expéditeur différente peut nécessiter des droits Microsoft 365 supplémentaires tels que Send As.

OAuth2 Client ID

Utiliser :

Application (client) ID

de l'application Entra.

OAuth2 Client Secret

Utiliser le Secret client Valeur.

OAuth2 Scope

https://outlook.office.com/SMTP.Send offline_access

OAuth2 Authorize URL

Pour une application mono-locataire :

https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/authorize

Remplacer TENANT_ID par le Directory (tenant) ID.

OAuth2 Token URL

https://login.microsoftonline.com/TENANT_ID/oauth2/v2.0/token

Utiliser le même tenant ID.

7. Autoriser le compte

Enregistrer la configuration Joomla.

Démarrer l'autorisation OAuth.

Joomla redirige le navigateur vers Microsoft.

Se connecter en utilisant le compte configuré comme :

SMTP Username

Approuver les droits demandés.

Microsoft redirige le navigateur vers Joomla.

Joomla échange alors le code d'autorisation contre des jetons OAuth et stocke le jeton de rafraîchissement.

Par la suite, Joomla peut obtenir de nouveaux jetons d'accès sans nécessiter de connexion interactive.

Google Gmail et Google Workspace

TL;DR

Pour Gmail ou Google Workspace, utiliser :

SMTP Host:
smtp.gmail.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

SMTP Username:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

OAuth2 Client ID:
<Google OAuth Client ID>

OAuth2 Client Secret:
<Google OAuth Client Secret>

OAuth2 Scope:
https://mail.google.com/

OAuth2 Authorize URL:
https://accounts.google.com/o/oauth2/v2/auth

OAuth2 Token URL:
https://oauth2.googleapis.com/token

Enregistrer cette URI de redirection pour le client OAuth Google :

https://www.example.com/administrator/index.php?option=com_config&task=mail.oauth2callback&format=raw

Le client OAuth doit utiliser le type d'application :

Web application

Selon l'audience, le statut de publication, la configuration des utilisateurs de test et les scopes demandés, il peut être nécessaire de publier l'application OAuth ou de la rendre accessible d'une autre manière à l'utilisateur SMTP.

Après avoir modifié la configuration de l'application OAuth, prévoir jusqu'à environ une heure pour que les changements soient pris en compte.

Aperçu

La configuration Google se compose des étapes suivantes :

  1. Créer ou sélectionner un projet Google Cloud.
  2. Configurer Google Auth Platform / le consentement OAuth.
  3. Configurer le scope Gmail requis.
  4. Créer un client OAuth Web.
  5. Configurer l'URI de redirection Joomla.
  6. Publier l'application OAuth ou la rendre accessible aux utilisateurs concernés.
  7. Attendre, si nécessaire, que les changements de configuration soient pris en compte.
  8. Saisir les informations du client OAuth dans Joomla.
  9. Autoriser le compte Gmail ou Google Workspace.

Les modifications apportées à la configuration OAuth de Google, à la configuration du consentement, aux scopes, à la configuration des utilisateurs de test ou à la publication de l'application peuvent ne pas être effectives immédiatement. Dans certains cas, prévoir jusqu'à environ une heure avant de considérer une configuration comme défaillante.

1. Créer ou sélectionner un projet Google Cloud

Ouvrir Google Cloud Console.

Créer un nouveau projet ou sélectionner un projet existant destiné à l'installation Joomla.

La configuration OAuth et les identifiants appartiennent à ce projet.

2. Configurer Google Auth Platform

Ouvrir :

Google Auth Platform

Configurer les éléments suivants de l'application :

Branding
Audience
Data Access

Configurer au minimum :

  • le nom de l'application
  • l'e-mail de support
  • le contact développeur
  • l'audience visée

Pour une organisation Google Workspace, une application destinée uniquement aux utilisateurs internes à l'organisation peut normalement utiliser une audience interne.

Pour les applications externes, configurer le statut de publication approprié ainsi que les utilisateurs de test.

3. Configurer le scope Gmail

Pour un accès Gmail SMTP OAuth, utiliser :

https://mail.google.com/

Cela accorde l'accès OAuth requis pour l'authentification SMTP Gmail.

Ce scope est considéré comme sensible ou restreint par Google, des exigences de vérification supplémentaires de Google peuvent donc s'appliquer aux applications publiques.

Pour un usage organisationnel privé, en particulier avec Google Workspace, les exigences peuvent être différentes.

4. Créer le client OAuth

Ouvrir :

Google Auth Platform
→ Clients

Créer un nouveau client OAuth.

Choisir :

Web application

Joomla est une application web côté serveur et nécessite un client OAuth de type Web.

5. Configurer l'URI de redirection

Dans le client OAuth, ajouter l'URI de redirection autorisée :

https://www.example.com/administrator/index.php?option=com_config&task=mail.oauth2callback&format=raw

Utiliser l'URL Joomla exacte.

L'URL de rappel complète doit être enregistrée.

N'enregistrer que :

https://www.example.com

n'est pas suffisant.

6. Publier ou activer l'application

Selon l'audience configurée et le type de compte Google, il peut être nécessaire de publier l'application ou d'ajouter explicitement des utilisateurs comme utilisateurs de test.

Avant de dépanner Joomla, vérifier que le compte utilisé pour le SMTP est effectivement autorisé à valider l'application OAuth.

Après avoir modifié :

  • l'audience
  • les utilisateurs de test
  • les scopes demandés
  • le statut de publication
  • la configuration du client OAuth

laisser un peu de temps aux modifications pour se propager.

Dans certains cas, cela peut prendre jusqu'à environ une heure.

7. Copier les identifiants OAuth

Google fournit :

Client ID
Client Secret

Un Id client Google ressemble normalement à :

123456789012-example.apps.googleusercontent.com

Copier les deux valeurs dans Joomla.

Garder le secret client confidentiel.

8. Configurer Joomla

Utiliser :

SMTP Host:
smtp.gmail.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

SMTP Username:
Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.

L'Adresse d'expédition et l'Identifiant SMTP doivent normalement être identiques.

L'utilisation d'une adresse d'expéditeur différente peut nécessiter une configuration supplémentaire d'alias ou de délégation dans Google Workspace ou Gmail.

OAuth2 Client ID

Utiliser l'Id client OAuth créé dans Google Cloud.

OAuth2 Client Secret

Utiliser le secret créé pour le client OAuth Google.

OAuth2 Scope

https://mail.google.com/

OAuth2 Authorize URL

https://accounts.google.com/o/oauth2/v2/auth

OAuth2 Token URL

https://oauth2.googleapis.com/token

9. Autoriser le compte

Enregistrer la configuration de Joomla.

Démarrer l'autorisation OAuth.

Joomla redirige l'administrateur vers Google.

Se connecter avec le compte Gmail ou Google Workspace configuré en tant que :

SMTP Username

Approuver le droit Gmail demandé.

Google redirige de nouveau vers Joomla.

Joomla échange le code d'autorisation contre des jetons OAuth et stocke le jeton de rafraîchissement.

Le jeton de rafraîchissement est ensuite utilisé pour demander de nouveaux jetons d'accès de courte durée chaque fois que l'authentification SMTP est requise.

Vérification finale

Une fois la configuration terminée, vérifier les points suivants :

  • L'identification SMTP est réglée sur OAuth 2.0.
  • L'adresse d'expédition correspond à l'identifiant SMTP.
  • L'identifiant SMTP correspond à la boîte aux lettres autorisée.
  • L'Id client est correct.
  • Le Secret client est correct.
  • Le scope correspond au fournisseur.
  • L'URL d'autorisation est correcte.
  • L'URL du jeton est correcte.
  • L'URL de rappel Joomla est enregistrée exactement telle quelle chez le fournisseur.
  • L'application OAuth est activée ou publiée pour l'utilisateur concerné.
  • Les modifications côté fournisseur ont eu suffisamment de temps pour se propager.
  • Joomla a correctement terminé l'autorisation OAuth.
  • Joomla a reçu un jeton de rafraîchissement.
  • Un e-mail de test Joomla peut être envoyé avec succès.