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

• 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.