Implementing OAuth2 for Outlook SMTP

Microsoft 365 / Exchange Online no longer supports Basic Authentication for many tenants. For customers who use their Microsoft Exchange SMTP servers within m-Power to send emails, this tech blog post will be a step-by-step guide on using OAuth2 client credentials with SMTP XOAUTH2 instead of a traditional password.

1. Register an application in Azure

• Go your Azure Portal.
• Go to App registrations → New registration. Any name works, such as m-Power Emails. No redirect URI is needed.
• Note the Application (client) ID and Directory (tenant) ID from the application’s Overview page.

• Under Certificates & secrets, create a client secret and copy its value immediately.

• Under API permissions, choose Add a permission → APIs my organization uses → Office 365 Exchange Online.

• Select Application permissions and then search for the SMTP.SendAsApp permission. Once found, check this option.

• Click Grant admin consent and then click Add Permission.

If you also use m-Power’s Email Reader Template, the same app registration can hold both SMTP.SendAsApp for sending and IMAP.AccessAsApp for reading.

2. Authorize the mailbox in Exchange Online

Run the following commands once in Exchange Online PowerShell as an Exchange administrator.

# Register the app's service principal with Exchange
New-ServicePrincipal -AppId <client-id> -ObjectId <enterprise-app-object-id>

# Allow the app to use the sending mailbox
Add-MailboxPermission -Identity "automated@yourcompany.com" `
    -User <enterprise-app-object-id> -AccessRights FullAccess

# SMTP AUTH must be enabled on the mailbox, even when using OAuth2
Set-CASMailbox -Identity "automated@yourcompany.com" -SmtpClientAuthenticationDisabled $false

The <enterprise-app-object-id> is found under Enterprise applications, not App Registrations, for the application you created:

3. Configure m-Power

In the m-Power interface, go to Admin → Messaging → Messaging Configuration.

Enter oauth2 in the email_auth_type property. The additional OAuth2 fields will appear automatically.

You can alternatively configure these settings directly from a text editor of your choosing, by going to this location:

.../m-power/mrcjava/job_streams/messaging.properties

• email_auth_type* — Enter oauth2. This property enables OAuth2 authentication. When blank, m-Power uses the previous email authentication behavior.
• email_server* — Enter smtp.office365.com:587
• email_user* — Enter the Microsoft 365 mailbox the system will send as, such as automated@yourcompany.com.
• email_sender* — Enter the default “From Address”. This must be the mailbox above that was set for email_user or a different address that mailbox is permitted to send as.
• email_oauth_tenant_id* — Enter the Directory (tenant) ID from Step 1.
• email_oauth_client_id* — Enter the Application (client) ID from Step 1.
• email_oauth_client_secret* — Enter the client secret value created back in Step 1.
• email_oauth_client_secret_encrypt* — Default value is false . Enter true to store the secret encrypted, similar to email_password_encrypt.
• email_oauth_scope — Optional. The default value is https://outlook.office365.com/.default
• email_password — This value is ignored when OAuth2 is enabled and may be left as-is or blank.

*– required.

An example messaging.properties configuration is shown below:

email_auth_type=oauth2
email_server=smtp.office365.com:587
email_user=automated@yourcompany.com
email_sender=automated@yourcompany.com
email_oauth_tenant_id=00000000-0000-0000-0000-000000000000
email_oauth_client_id=11111111-1111-1111-1111-111111111111
email_oauth_client_secret=xxxxxxxxxxxxxxxxxxxxxxxx
email_oauth_client_secret_encrypt=false

No Tomcat restart is required. The messaging configuration is re-read when the file changes.

How it works

• m-Power requests an access token from https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token using the client credentials grant, then authenticates to SMTP with AUTH XOAUTH2 as the configured email_user.
• Tokens are cached and refreshed automatically about five minutes before they expire, so bulk task runs do not repeatedly call the token endpoint.
• The OAuth2 setting is system-wide and applies to every email m-Power sends, including scheduled tasks and message queues, workflow email actions, emailed reports such as HTML, PDF, and Excel output, analytics emails, verification codes, and task-failure notifications.
• Additional JavaMail settings can still be supplied through email_other using the name:value;name:value format. These settings take precedence.

Troubleshooting

In the event the following Azure error codes are thrown, here is an explanation and solution for those codes.

Error	Solution
Log: failed to obtain OAuth2 access token with AADSTS7000215	Invalid client secret (or the secret has expired). Check the secret expiration date in your Azure Portal.
Log: AADSTS500011 / AADSTS65001	SMTP.SendAsApp permission is missing from the app registration or Admin Consent was not granted.
SMTP error 535 5.7.3 Authentication unsuccessful	Service principal not registered in Exchange, mailbox permission missing, or SMTP AUTH disabled on the mailbox / tenant.
Emails route to the plain (unauthenticated) sender	email_auth_type property in m-power’s messaging.properties is blank or misspelled; the value must be oauth2.