SMTP Microsoft OAuth Setup

Configure your notifications using Microsoft OAuth SMTP

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

1

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

2

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"

3

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

1

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)

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

  • Click "Add"

2

Save the Secret Value

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

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

1

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"

2

Grant Admin Consent

  • 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

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

1

Prepare PowerShell and Connect

  1. Open PowerShell as Administrator

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

PowerShell
Install-Module -Name ExchangeOnlineManagement

  1. Connect to Exchange Online:

PowerShell
Connect-ExchangeOnline -UserPrincipalName [email protected]
2

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!)

3

Assign Mailbox Permissions

Option 1 — Assign FullAccess to a mailbox:

PowerShell
Add-MailboxPermission -Identity "[email protected]" -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>
4

Optional and Cleanup Commands

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

PowerShell
Set-TransportConfig -SmtpClientAuthenticationDisabled $false

Disconnect:

PowerShell
Disconnect-ExchangeOnline
5

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., [email protected])

SMTP Settings

  • SMTP Host: smtp.office365.com (Default)

  • SMTP Port: 587 (Default)

  • Security: Auto (Default)

Quick Test Checklist

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.

PreviousNotification SettingsNextArticles

Last updated