Skip to content

SMTP Microsoft OAuth Setup⚓︎

Prerequisites⚓︎

  • Microsoft 365 account (Office 365)
  • Admin access to Azure Portal
  • Admin access to Microsoft 365 Admin Center (for some settings)

Part 1: Create App Registration in Azure Portal⚓︎

Go to Azure Portal⚓︎

  • Go to https://portal.azure.com
  • Sign in with your Microsoft 365 admin account
  • Search for "Azure Active Directory" or "Microsoft Entra ID" in the top search bar
  • Click on it

Create App Registration⚓︎

  • In the left menu, click "App registrations"
  • Click "+ New registration"
  • Fill in the registration form:
    • Name: Email SMTP Service (or any name you prefer)
    • Supported account types: Select "Accounts in this organizational directory only (Single tenant)"
    • Redirect URI: Leave blank (not needed for SMTP)
  • Click "Register"

Note the Application (Client) ID and Tenant ID⚓︎

After creation, on the app overview page:

  • Copy and save the Application (client) ID (GUID format)
  • Copy and save the Directory (tenant) ID (GUID format)

Keep these values — you'll need them for your application.

Part 2: Create Client Secret⚓︎

Generate Client Secret⚓︎

  • In your app registration, go to "Certificates & secrets" in the left menu
  • Click the "Client secrets" tab
  • Click "+ New client secret"
  • Fill in the details:
    • Description: SMTP Client Secret (or any description)
    • Expires: Choose expiration period (recommended: 24 months)

Warning

You'll need to create a new secret before it expires!

  • Click "Add"

Save the Secret Value⚓︎

  • IMMEDIATELY copy the "Value" (the secret string)

Danger

You can only see the secret value ONCE. If you lose it, you must create a new one.

  • Save this secret securely.

Part 3: Configure API Permissions⚓︎

Add SMTP Permissions⚓︎

  • In your app registration, go to "API permissions" in the left menu
  • Click "+ Add a permission"
  • Select "APIs my organization uses"
  • Search for "Office 365 Exchange Online"
  • Click on "Office 365 Exchange Online"
  • Select "Application permissions" (NOT Delegated permissions)
  • Check the box for "SMTP.SendAsApp"
  • Click "Add permissions"
  • Still on the API permissions page
  • Click "Grant admin consent for [Your Organization]"
  • Click "Yes" to confirm
  • Wait a few seconds — the status should change to a green checkmark ✓

Your permissions should now show:

Part 4: Register Service Principal in Exchange Online⚓︎

Warning

This is the most commonly missed step! You must register your Azure AD app as a Service Principal in Exchange Online.

Prepare PowerShell and Connect⚓︎

  1. Open PowerShell as Administrator

  2. Install Exchange Online PowerShell module (if not installed):

    PowerShell
    Install-Module -Name ExchangeOnlineManagement

  3. Connect to Exchange Online:

    PowerShell
    Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com

Register the Service Principal⚓︎

Run:

PowerShell
New-ServicePrincipal -AppId <Your-Application-Client-ID> -ServiceId <Your-Application-Object-ID>

How to get Object ID:

  • Azure Portal → Azure Active Directory → App registrations → your app → Overview → "Object ID" (different from Application/Client ID!)

Assign Mailbox Permissions⚓︎

Option 1 — Assign FullAccess to a mailbox:

PowerShell
Add-MailboxPermission -Identity "sender@yourdomain.com" -User <Your-Application-Client-ID> -AccessRights FullAccess

Option 2 — Grant organization-wide send permission (less secure):

PowerShell
New-ManagementRoleAssignment -Role "Application Mail.SendAsApp" -App <Your-Application-Client-ID>

Optional and Cleanup Commands⚓︎

Optional — Enable SMTP AUTH for your organization (usually already enabled):

PowerShell
Set-TransportConfig -SmtpClientAuthenticationDisabled $false

Disconnect:

PowerShell
Disconnect-ExchangeOnline

Alternative via Admin Center⚓︎

  • Go to https://admin.microsoft.com
  • Navigate to Settings → Org settings → Modern authentication
  • Ensure "Authenticated SMTP" is enabled

Part 5: Verify Configuration⚓︎

What You Need⚓︎

  1. Tenant ID (from Part 1)
  2. Client ID (from Part 1)
  3. Client Secret (from Part 2)
  4. Sender Email: The mailbox that will send emails (e.g., sender@yourdomain.com)

SMTP Settings⚓︎

  • SMTP Host: smtp.office365.com (Default)
  • SMTP Port: 587 (Default)
  • Security: Auto (Default)

Quick Test Checklist⚓︎

  • App registration created in Azure AD
  • Client ID noted
  • Object ID noted (different from Client ID!)
  • Tenant ID noted
  • Client secret created and saved
  • SMTP.SendAsApp permission added
  • Admin consent granted (green checkmark)
  • Service Principal registered in Exchange Online (New-ServicePrincipal)
  • Mailbox permissions assigned (Add-MailboxPermission or role assignment)
  • SMTP AUTH enabled (usually default)

PowerBI Portal Notifications Configuration⚓︎

Enter these values acquired on the configuration process into the SMTP configuration UI by choosing the 'Office 365 - OAuth' on the 'SMTP Config' under the 'Notifications' tab -> 'Email Configuration'

Common Issues and Solutions⚓︎

Issue: "Authentication unsuccessful" or "Service principal not found"

Solution:

  • You must register the service principal in Exchange Online using the New-ServicePrincipal cmdlet.
  • This is separate from the Azure AD app registration.
  • Use both Application (Client) ID AND Object ID.
  • Wait 15-30 minutes after registration for propagation.
Issue: "Insufficient privileges" when granting consent

Solution:

  • You must be a Global Administrator or Application Administrator.
  • Regular users cannot grant admin consent.
Issue: "Authentication failed" when sending

Solution:

  • Verify Tenant ID, Client ID, and Client Secret are correct.
  • Check that SMTP.SendAsApp permission has green checkmark (admin consent granted).
  • Ensure the sender mailbox exists and SMTP AUTH is enabled.
Issue: Client secret expired

Solution:

  • Go back to Azure Portal → App registrations → Your app → Certificates & secrets.
  • Create a new client secret.
  • Update your application configuration with the new secret.
Issue: "5.7.60 SMTP; Client does not have permissions to send as this sender"

Solution:

  • The authenticated app must send as a mailbox that exists in your tenant.
  • The mailbox must have SMTP AUTH enabled.
  • Verify sender email matches a real mailbox.