Setting up OAuth2 SMTP authentication for Microsoft 365

Microsoft is retiring Basic Authentication for SMTP AUTH, with full deactivation on April 30, 2026. After this date, SMTP connections using username/password will stop working. OAuth2 is now required for sending email via Microsoft 365.

This guide walks you through configuring OAuth2 SMTP authentication using the Service Principal method (SMTP.SendAsApp), which is Microsoft's documented approach for application-based SMTP access.

To enable OAuth2 SMTP authentication, you need to:

1. Create an App Registration in Microsoft Entra ID
2. Register a Service Principal in Exchange Online and grant mailbox permissions
3. Configure Contensis with the OAuth2 credentials
4. Wait for permissions to propagate (typically 15-30 minutes)

Time Required: 20-30 minutes (plus propagation time)

1. Sign in to the Microsoft Entra admin center
2. Navigate to App registrations
3. Click New registration
4. Configure:
   • Name: Contensis SMTP OAuth2 (or a name of your choosing)
   • Supported account types: "Single tenant"
   • Redirect URI: Leave blank
5. Click Register

After registration, copy these values (you'll need them later):

• Application (client) ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Directory (tenant) ID: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

1. In your app registration, go to Certificates & secrets
2. Click New client secret
3. Configure:
   • Description: "SMTP OAuth2 Client Secret"
   • Expires: Choose appropriate duration (e.g., 24 months)
4. Click Add
5. IMPORTANT: Copy the Value immediately (it won't be shown again)

1. Go to API permissions
2. Click Add a permission
3. Select APIs my organization uses
4. Search for and select: Office 365 Exchange Online
5. Choose Application permissions
6. Search for and add: SMTP.SendAsApp
7. Click Add permissions
8. CRITICAL: Click Grant admin consent for [Your Organization]
   • You must be a Global Administrator or Application Administrator
   • The status should show a green checkmark for all permissions

This step registers a Service Principal in Exchange Online and grants it permission to send email from your mailbox. It cannot be done through any web portal — PowerShell is required.

Download and run Configure-ServicePrincipal.ps1 - it automates all of the steps below, including module installation, connection, service principal creation, and mailbox permission assignment.

The script will prompt you for:

• Application (Client) ID — from Part 1, Step 2
• • In the Microsoft Entra admin center, go to Identity > Applications > App registrations
  • Select your app, then click Overview
  • Click the link under Managed application in local directory
  • Copy the Object ID from the Enterprise Application page (this is different from the App Registration Object ID)
  Enterprise Application Object ID — follow the steps below to find the object ID
• Sender email address — the mailbox that will send emails

• PowerShell 5.1 or PowerShell 7+
• Exchange Online Administrator role
• A mailbox with an Exchange Online licence that will be used as the sender

Open PowerShell as Administrator and run:

Sign in with an account that has Exchange Administrator permissions.

Once the Service Principal is set up in Exchange Online, configure Contensis with the OAuth2 credentials.

1. Navigate to Management Console > Global Settings
2. Set the following values:

The sender email address (the "from" address) is configured per-notification or in your email settings — it must match a mailbox that was granted permissions in Part 2.

Service Principal permissions typically propagate within 15-30 minutes, but can occasionally take longer.

During this time, authentication attempts may fail with errors like:

• "535 5.7.3 Authentication unsuccessful"
• "Authentication failed"

What to do:

• Wait at least 15-30 minutes after granting mailbox permissions
• Send a test email from Contensis
• If still failing after 30 minutes, review the troubleshooting section below

If you need to diagnose issues after setup, download and run Diagnose-OAuth2Config.ps1 — it checks the service principal registration, mailbox permissions, and organisation-wide SMTP settings.

Possible causes:

1. Service Principal doesn't exist in Exchange — run Configure-ServicePrincipal.ps1
2. Mailbox permissions not granted — run Configure-ServicePrincipal.ps1
3. Permissions haven't propagated yet — wait 15-30 minutes
4. Wrong API permission (using Mail.Send instead of SMTP.SendAsApp) — fix in the Entra admin center
5. Missing admin consent for SMTP.SendAsApp — grant it (Part 1, Step 4)
6. Incorrect Object ID used (App Registration Object ID instead of Enterprise Application Object ID)

How to verify:

Or run Diagnose-OAuth2Config.ps1 to check everything automatically.

Causes:

• Mailbox doesn't have an Exchange Online licence
• Email address is incorrect (check for typos)
• User account is disabled

Solution:

• Verify the mailbox in Microsoft 365 Admin Center
• Assign an Exchange Online licence
• Use the exact email address

Causes:

• Service principal wasn't created in Exchange
• Wrong Object ID used (must be Enterprise Application Object ID)
• Service principal creation failed silently

Solution:

Check organisation settings:

If True, SMTP AUTH is blocked organisation-wide. Contact your Exchange administrator to enable it.

If you need multiple mailboxes to send mail through the application, grant permissions to each mailbox:

Now any of these mailboxes can be used as the sender email address in Contensis.

• App Registration created in Microsoft Entra ID
• Application (Client) ID, Directory (Tenant) ID, and Enterprise Application Object ID noted
• Client Secret created and saved securely
• SMTP.SendAsApp permission granted with admin consent
• Service Principal created in Exchange Online (via script or manually)
• Mailbox permissions granted to Service Principal (FullAccess)
• Waited 15-30 minutes for propagation
• Contensis configured with OAuth2 settings (Part 3)
• Test email sent successfully

If you encounter issues not covered in this guide:

1. Run Diagnose-OAuth2Config.ps1 to check your configuration
2. Verify all steps were completed exactly as written
3. Wait 30 minutes for propagation if you haven't already
4. Check the Microsoft 365 Service Health Dashboard for known issues
5. Review Exchange Online logs and message trace
6. Raise a helpdesk ticket