User Documentation
Download
Launch

Configuration

SMTP OAuth 2.0 Configuration in Joomla

Since version 6.2 Joomla supports OAuth 2.0 authentication for SMTP connections.

Instead of storing the password of the SMTP account, Joomla authorizes access through the mail provider. The provider returns a long-lived refresh token, which Joomla can later use to request short-lived access tokens for SMTP authentication.

The basic flow is:

Joomla
  ↓
OAuth provider authorization page
  ↓
User signs in and grants access
  ↓
Provider redirects back to Joomla
  ↓
Joomla receives an authorization code
  ↓
Joomla exchanges the code for tokens
  ↓
Refresh token is stored
  ↓
Access tokens are created when SMTP authentication is required
 

The SMTP password is therefore not used for OAuth 2.0 authentication.

Before you start

The setup consists of several steps.

  1. Create or register an OAuth application with your mail provider.
  2. Configure the application's allowed redirect URI.
  3. Configure the required SMTP permissions or OAuth scopes.
  4. Create a Client ID and Client Secret.
  5. If required by the provider, publish, deploy, or activate the OAuth application.
  6. Wait until provider-side changes have propagated. Depending on the provider and tenant configuration, this can take up to approximately one hour.
  7. Enter the OAuth settings in Joomla.
  8. Save the Joomla configuration.
  9. Start the OAuth authorization from Joomla.
  10. Sign in to the SMTP account and grant the requested permission.
  11. Verify that Joomla received and stored a refresh token.
  12. Send a test email.

Do not assume that a newly created or modified OAuth application is immediately usable. Provider-side configuration changes can take some time to become effective.

Joomla OAuth 2.0 settings

Open:

System
→ Global Configuration
→ Server
→ Mail
 

Select:

Mailer: SMTP
SMTP Authentication: OAuth 2.0
 

Joomla then displays the OAuth 2.0 configuration fields.

From Email Address

The configured From Email Address should match the mailbox used as the SMTP username.

Example:

From Email Address:
This email address is being protected from spambots. You need JavaScript enabled to view it.

SMTP Username:
This email address is being protected from spambots. You need JavaScript enabled to view it.
 

For the standard OAuth 2.0 SMTP setup, both values should refer to the same mailbox.

Using a different From address can require additional provider-side permissions such as Send As, aliases, or delegated mailbox permissions and may otherwise cause the provider to reject the message.

SMTP Username

The SMTP username identifies the mailbox Joomla uses for SMTP authentication.

Usually this is the complete email address:

This email address is being protected from spambots. You need JavaScript enabled to view it.
 

The account authorized during the OAuth flow should normally be the same account.

OAuth2 Client ID

The Client ID identifies the OAuth application registered with the mail provider.

It is generated by the provider when the OAuth application or OAuth client is created.

Example:

aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee
 

The Client ID is not a secret.

OAuth2 Client Secret

The Client Secret authenticates the Joomla OAuth application to the provider.

It is created by the provider together with, or after creating, the OAuth application.

Example:

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

The Client Secret must be kept private.

It should not be:

  • published
  • committed to a public repository
  • included in documentation
  • shared between unrelated Joomla installations unless intentionally using the same OAuth application

OAuth2 Scope

The scope tells the provider which permissions Joomla requests.

Scopes are provider-specific.

For SMTP authentication, the scope usually grants permission to access or send mail through the user's mailbox.

One or more scopes can be requested.

If multiple scopes are required, they are normally separated by spaces:

scope1 scope2 scope3
 

The exact scope value depends on the mail provider.

OAuth2 Authorize URL

The Authorize URL is the provider endpoint where the user signs in and grants Joomla access.

Joomla redirects the administrator to this URL when OAuth authorization is started.

The provider then:

  1. authenticates the user
  2. displays the requested permissions
  3. asks for consent if required
  4. redirects the browser back to Joomla

The exact URL depends on the provider.

OAuth2 Token URL

The Token URL is the provider endpoint Joomla uses to exchange OAuth credentials.

It is used for two important operations.

First, after authorization:

authorization code
    ↓
token endpoint
    ↓
access token + refresh token
 

Later:

refresh token
    ↓
token endpoint
    ↓
new access token
 

The administrator normally never interacts with this endpoint directly.

OAuth redirect URI

OAuth providers require Joomla's callback URL to be registered with the OAuth application.

For Joomla, the callback URL is:

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

Replace:

https://www.example.com
 

with the actual Joomla site URL.

The redirect URI configured at the provider must match the URI Joomla sends during authorization.

In particular, check:

  • protocol
  • hostname
  • path
  • query string
  • Joomla administrator path

For example:

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

and:

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

are different redirect URIs.

Microsoft 365

TL;DR

For a typical single-tenant Microsoft 365 setup, use:

SMTP Host:
smtp.office365.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
This email address is being protected from spambots. You need JavaScript enabled to view it.

SMTP Username:
This email address is being protected from spambots. You need JavaScript enabled to view it.

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
 

Register this redirect URI in Microsoft Entra:

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

Also make sure Authenticated SMTP is enabled for the mailbox.

After changing the application, permissions, or Exchange settings, allow up to approximately one hour for changes to propagate.

Overview

The Microsoft setup consists of:

  1. Register an application in Microsoft Entra.
  2. Configure the Joomla redirect URI.
  3. Configure delegated SMTP permissions.
  4. Create a Client Secret.
  5. Make sure SMTP AUTH is enabled for the mailbox.
  6. Wait for configuration changes to propagate if necessary.
  7. Enter the application settings in Joomla.
  8. Authorize the mailbox through Joomla.

Changes to application registrations, permissions, consent, or Exchange settings may not become effective immediately. In some environments, propagation can take up to approximately one hour.

1. Register the application

Open the Microsoft Entra admin center.

Navigate to:

Identity
→ Applications
→ App registrations
→ New registration
 

Enter a name such as:

Joomla SMTP OAuth
 

For a Joomla installation used with one Microsoft 365 organization, a single-tenant registration is normally appropriate:

Accounts in this organizational directory only
 

After registration, note:

Application (client) ID
Directory (tenant) ID
 

Both values are available on the application's Overview page.

2. Configure the redirect URI

Open:

App registrations
→ Joomla SMTP OAuth
→ Authentication
 

Add a platform:

Web
 

Register the Joomla callback URL:

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

Use the real Joomla site URL.

3. Configure SMTP permissions

Joomla requires delegated SMTP access.

The SMTP permission is:

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

Joomla also requires a refresh token so that SMTP authentication continues to work without the administrator signing in again.

Therefore the Joomla scope should include:

offline_access
 

The final scope is:

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

Depending on the organization's Microsoft Entra policies, administrator consent may be required.

4. Create the Client Secret

Navigate to:

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

Create a secret.

Microsoft displays values such as:

Secret ID
Value
 

Joomla requires the actual:

Value
 

Do not enter the Secret ID.

Store the secret immediately because Microsoft may only display the value once.

5. Enable SMTP AUTH

OAuth authorization alone is not sufficient if SMTP AUTH is disabled for the mailbox.

In the Microsoft 365 admin center, check the affected user.

Navigate approximately to:

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

Ensure:

Authenticated SMTP
 

is enabled.

Organization-wide Exchange Online policies or Microsoft security settings can also disable SMTP AUTH.

If the OAuth flow succeeds but SMTP still fails, this setting should be one of the first things to verify.

Changes to Exchange or mailbox settings can take some time to propagate.

6. Configure Joomla

Use:

SMTP Host:
smtp.office365.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
This email address is being protected from spambots. You need JavaScript enabled to view it.

SMTP Username:
This email address is being protected from spambots. You need JavaScript enabled to view it.
 

The From Email Address and SMTP Username should normally be identical.

Using a different sender address can require additional Microsoft 365 permissions such as Send As.

OAuth2 Client ID

Use the:

Application (client) ID
 

from the Entra application.

OAuth2 Client Secret

Use the Client Secret Value.

OAuth2 Scope

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

OAuth2 Authorize URL

For a single-tenant application:

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

Replace TENANT_ID with the Directory (tenant) ID.

OAuth2 Token URL

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

Use the same tenant ID.

7. Authorize the account

Save the Joomla configuration.

Start OAuth authorization.

Joomla redirects the browser to Microsoft.

Sign in using the account configured as:

SMTP Username
 

Approve the requested permissions.

Microsoft redirects the browser back to Joomla.

Joomla then exchanges the authorization code for OAuth tokens and stores the refresh token.

Afterwards Joomla can obtain new access tokens without requiring an interactive login.

Google Gmail and Google Workspace

TL;DR

For Gmail or Google Workspace, use:

SMTP Host:
smtp.gmail.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
This email address is being protected from spambots. You need JavaScript enabled to view it.

SMTP Username:
This email address is being protected from spambots. You need JavaScript enabled to view it.

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
 

Register this redirect URI for the Google OAuth client:

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

The OAuth client must use the application type:

Web application
 

Depending on the audience, publishing status, test-user configuration, and requested scopes, the OAuth application may need to be published or otherwise made available to the SMTP user.

After changing the OAuth application configuration, allow up to approximately one hour for changes to propagate.

Overview

The Google setup consists of:

  1. Create or select a Google Cloud project.
  2. Configure Google Auth Platform / OAuth consent.
  3. Configure the required Gmail scope.
  4. Create a Web OAuth client.
  5. Configure the Joomla redirect URI.
  6. Publish or make the OAuth application available to the intended users.
  7. Wait for configuration changes to propagate if necessary.
  8. Enter the OAuth client information in Joomla.
  9. Authorize the Gmail or Google Workspace account.

Changes to Google OAuth configuration, consent configuration, scopes, test-user configuration, or application publishing may not become effective immediately. In some cases, allow up to approximately one hour before treating a configuration as broken.

1. Create or select a Google Cloud project

Open Google Cloud Console.

Create a new project or select an existing project intended for the Joomla installation.

The OAuth configuration and credentials belong to this project.

2. Configure Google Auth Platform

Open:

Google Auth Platform
 

Configure the application's:

Branding
Audience
Data Access
 

At minimum configure:

  • application name
  • support email
  • developer contact
  • intended audience

For a Google Workspace organization, an application intended only for users inside the organization can normally use an internal audience.

For external applications, configure the appropriate publishing status and test users.

3. Configure the Gmail scope

For Gmail SMTP OAuth access, use:

https://mail.google.com/
 

This grants OAuth access required for Gmail SMTP authentication.

The scope is considered sensitive or restricted by Google, so additional Google verification requirements can apply to public applications.

For private organizational use, particularly with Google Workspace, the requirements can differ.

4. Create the OAuth client

Open:

Google Auth Platform
→ Clients
 

Create a new OAuth client.

Choose:

Web application
 

Joomla is a server-side web application and requires a Web OAuth client.

5. Configure the redirect URI

Under the OAuth client, add the authorized redirect URI:

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

Use the exact Joomla URL.

The complete callback URL must be registered.

Registering only:

https://www.example.com
 

is not sufficient.

6. Publish or enable the application

Depending on the configured audience and Google account type, the application may need to be published or users may need to be explicitly added as test users.

Before troubleshooting Joomla, verify that the account used for SMTP is actually allowed to authorize the OAuth application.

After changing:

  • audience
  • test users
  • requested scopes
  • publishing status
  • OAuth client configuration

allow some time for the changes to propagate.

In some cases this can take up to approximately one hour.

7. Copy the OAuth credentials

Google provides:

Client ID
Client Secret
 

A Google Client ID normally looks similar to:

123456789012-example.apps.googleusercontent.com
 

Copy both values into Joomla.

Keep the Client Secret private.

8. Configure Joomla

Use:

SMTP Host:
smtp.gmail.com

SMTP Port:
587

SMTP Security:
STARTTLS

SMTP Authentication:
OAuth 2.0

From Email Address:
This email address is being protected from spambots. You need JavaScript enabled to view it.

SMTP Username:
This email address is being protected from spambots. You need JavaScript enabled to view it.
 

The From Email Address and SMTP Username should normally be identical.

Using a different sender address can require additional alias or delegation configuration in Google Workspace or Gmail.

OAuth2 Client ID

Use the OAuth Client ID created in Google Cloud.

OAuth2 Client Secret

Use the secret created for the Google OAuth client.

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. Authorize the account

Save the Joomla configuration.

Start OAuth authorization.

Joomla redirects the administrator to Google.

Sign in using the Gmail or Google Workspace account configured as:

SMTP Username
 

Approve the requested Gmail permission.

Google redirects back to Joomla.

Joomla exchanges the authorization code for OAuth tokens and stores the refresh token.

The refresh token is then used to request new short-lived access tokens whenever SMTP authentication is required.

Final check

After the setup is complete, verify the following:

  • SMTP authentication is set to OAuth 2.0.
  • From Email Address matches the SMTP username.
  • SMTP username matches the authorized mailbox.
  • Client ID is correct.
  • Client Secret is correct.
  • Scope matches the provider.
  • Authorization URL is correct.
  • Token URL is correct.
  • Joomla callback URL is registered exactly at the provider.
  • The OAuth application is enabled or published for the affected user.
  • Provider-side changes had enough time to propagate.
  • Joomla successfully completed OAuth authorization.
  • Joomla received a refresh token.
  • A Joomla test email can be sent successfully.