Set up Microsoft Entra ID and Exchange online for OAuth

Overview

Previously we were supporting only basic auth(username, password) for SMTP emails for all email providers. But recently Microsoft announced to deprecate basic auth from SMTP and moving to OAuth authentication. Therefore we have implemented OAuth authentication using client_credentials mechanism for Microsoft SMTP Emails.

This document describes all the steps required to setup your Microsoft App and provide permission to access mailbox. These are divided into two parts.

Setup Microsoft App

1. Login to azure portal. Click on App Registration. Then New Registration.
   

2. Provide a Name to App. And in Supported account types section choose select Accounts in this organizational directory only. Redirect URI is not required hence ignore it. Then click Register.
   

3. Note down the Application (client) ID(client_id) and Directory (tenant) ID(tenant_id) of the Microsoft App.
   

4. Click New Client Secret.
   

5. Note down the secrets value highlighted in red box.
   

6. Now assign the required permissions to App. Click on API Permissions -> Add a permission → APIs my organization uses -> search for office 365 Exchange → click on it.
   

7. Select Application Permissions → SMTP → click on SMTP.SendAsApp checkbox → Add permission. After Adding permission, provide admin consent on the permission.
   

8. Now Permission page would look like this.
   

9. Now go back to azure home page. Click on Enterprise Applications → search the app with name → copy object Id(ObjectId). Note it down for further use.
   

Provide required Licence and Permissions

There are few permissions and licenses are required for SMTP emails.

1. Please ensure your Microsoft account has Exchange online license.

2. SMTP Auth must be enabled at tenant level.

   1. Go to the exchange admin center https://admin.exchange.microsoft.com/#/settings

   2. Click on Settings → Mail Flow. Ensure Turn Off SMTP AUTH protocol for your organization checkbox is unchecked.
      

3. A licensed mailbox is mandatory. SMTP can't send mail without a mailbox.
   

4. Now Register your Microsoft App with Exchange Online email service. We will use PowerShell command to provide exchange access to the microsoft App

   1. Install and run PowerShell in your machine

      Mac command:
      brew install --cask powershell
      
      Windows command:
      winget install --id Microsoft.PowerShell -e --source winget
      
      PowerShell Run command:
      pwsh

   2. Run the below command in PowerShell to install ExchangeOnlineManagement module

      Install-Module -Name ExchangeOnlineManagement
      Import-module ExchangeOnlineManagement 

   3. Connect Exchange service with the microsoft tenant using the below command.

      Connect-ExchangeOnline -Organization <tenant_id>
      
      Sample:
      Connect-ExchangeOnline -Organization 3c0a0034-da1f-479d-a860-082149bd9a54

   4. Register Microsoft app’s service principal in Exchange with the help of below command. Here client_id is Microsoft App client Id and enterprise_object_id is object id of the same app in Enterprise application collected in step 9.

      New-ServicePrincipal -AppId <client_id> -ObjectId <enterprise_object_id>
      
      Sample:
      New-ServicePrincipal -AppId 2f1b200b-90c8-4f7e-b137-a991d92d7137 -ObjectId 46f08a93-a981-4b41-9ebd-66849639baad

   5. Provide mailbox access to the Microsoft App.

      Add-MailboxPermission -Identity <mailbox_email> -User <enterprise_object_id> -AccessRights FullAccess
      
      Sample:
      Add-MailboxPermission -Identity "gina.davis@simpplr.net" -User 46f08a93-a981-4b41-9ebd-66849639baad -AccessRights FullAccess

SMTP OAuth Detail Required in Simpplr

Simpplr will require following detail regarding SMTP emails with OAuth Token.

• Client Id: client_id of microsoft app in App Registration.

• Client Secret: client_secret of microsoft app in App Registration.

• Tenant Id: Tenant Id of the microsoft account.

• Username: email address of the mailbox.

From address restrictions:

We are using a client_credentials (app-only) OAuth token to authenticate to Exchange Online SMTP.

What is allowed:

• From address is the authenticated mailbox used for SMTP

• Or another mailbox in same tenant with Send As permission

  • If From address ≠ auth.user then Grant Send As permission

    Add-RecipientPermission -Identity targetMailbox@tenant.com -Trustee senderMailbox@tenant.com -AccessRights SendAs

What is not allowed:

• SMTP OAuth (client_credentials) enforces strict tenant identity.

• It does not allow to send mail as or on behalf of mailboxes outside the tenant.

• External domains and non-Microsoft mailboxes are explicitly blocked. This is a by-design security restriction.

• Does not support Gmail / SES / custom SMTP identities as sender

• This restriction is enforced to prevent:

  • Email spoofing

  • Tenant/domain impersonation

  • Phishing risks

• Authorization code (delegated OAuth) also does not support external sender addresses

• SMTP Basic Auth allows external senders due to legacy SMTP behavior and relaxed identity enforcement.

With OAuth2 client_credentials, Exchange Online applies stricter controls:

The application can only send emails on behalf of mailboxes within your tenant or mailboxes (aliases) that have been explicitly granted Send As or Send on behalf permissions. If you use a From: address from a domain outside your tenant, the message will be blocked with the error: 554 5.2.252 SendAsDenied.