PHPMailer Azure OAuth2

Provides secure Microsoft Entra ID (Azure AD) OAuth2/XOAUTH2 authentication
for the PHPMailer SMTP module.

Client secrets are stored via the Key module
(typically backed by an environment variable), and OAuth2 tokens are stored in the
State API — never in exported configuration.

Features

• OAuth2 Authorization Code flow with Microsoft Entra ID (Azure AD).
• Client secret resolved at runtime from the Key module, never written to configuration.
• Access token and refresh token stored in the Drupal State API (excluded from configuration export).
• Automatic keep-alive token refresh on cron (every 60 days).
• Refresh token age monitoring with administrator warnings at 75 days.
• CSRF-protected authorization callback.
• Two-step migration wizard from the phpmailer_oauth2 module.

Mandatory Modules

• PHPMailer SMTP
• Key

Post-Installation

After installing the module, complete the following steps to configure
Microsoft Entra ID (Azure AD) OAuth2 authentication.

1. Register an Azure application.
   In the Azure portal, go to
   Microsoft Entra ID → App registrations → New registration.
   1. Enter an application name, for example
      Drupal PHPMailer, and select the appropriate account type.
   2. Under Redirect URIs, select Web
      and add:
      https://yourdomain.com/phpmailer-azure-oauth2/callback
   3. Go to
      Certificates & secrets → New client secret,
      create a client secret, and copy the secret value immediately.
      The value is shown only once.
   4. Go to
      API permissions → Add a permission → APIs my organization uses
      → Office 365 Exchange Online → Delegated permissions
      and add SMTP.Send.
   5. Grant Admin consent for the permission.
   6. From the application's Overview page, copy the
      Application (client) ID and
      Directory (tenant) ID.
2. Set the client secret.

   Set the
   PHPMAILER_OAUTH2_CLIENT_SECRET
   environment variable on your server.
   The included Key entity
   (phpmailer_azure_oauth2_client_secret)
   reads the secret automatically.

3. Configure the module.

   Go to
   /admin/config/system/phpmailer-azure-oauth2
   and enter:

   • Mailbox email address
   • Application (Client) ID
   • Directory (Tenant) ID
   • Client secret Key
     (leave the default unless you created your own Key)
4. Authorize with Microsoft Entra ID.

   Click Authorize with Microsoft Entra ID,
   sign in to your Microsoft account, and grant permission to the
   application.
   The access token and refresh token are stored securely in the
   Drupal State API.

5. Configure PHPMailer SMTP.

   On the PHPMailer SMTP settings page, select
   Azure OAuth2 (Key module + State API)
   as the SMTP authentication type.

Similar projects

The PHPMailer OAuth2 module also provides Microsoft Entra ID (Azure AD) OAuth2 authentication for PHPMailer SMTP. This module focuses on improving security and long-term reliability.

• More secure credential storage.
  Client secrets are stored using the
  Key module, and OAuth2 access and refresh tokens are stored in the Drupal State API. This keeps sensitive information out of exported configuration.
• Automatic token renewal.
  The module refreshes OAuth2 tokens automatically during cron, helping maintain uninterrupted email delivery. It also warns administrators if a refresh token has not been renewed after 75 days.
• Built-in CSRF protection.
  The OAuth2 authorization process uses the standard state parameter to validate the callback and protect against CSRF attacks.
• Easy migration.
  If you are already using phpmailer_oauth2, the included two-step migration wizard imports your existing configuration and OAuth2 tokens, so you do not need to authorize the application again.