OAuth authentication for high volume emails for Microsoft 365

Learn how to use OAuth authentication to connect with SMTP protocols and to access email data for Office 365 users.

OAuth2 support for SMTP protocols as described below is available for both Microsoft 365 (which includes Office on the web) and Outlook.com users.

If you're not familiar with the OAuth 2.0 protocol, see OAuth 2.0 protocol on Microsoft identity platform overview. For more information about the Microsoft Authentication Libraries (MSAL), which implement the OAuth 2.0 protocol to authenticate users and access secure APIs, see MSAL overview.

Register your application

To use OAuth, an application must be registered with Microsoft Entra.

Follow the instructions listed in Register an application with the Microsoft identity platform to create a new application.

1. Sign in to the Microsoft Entra admin center at least as a Cloud Application Administrator.

2. Browse to Identity > Applications > App registrations and select New registration.

   

3. Enter a display name for your application. Users of your application might see the display name when they use the app, for example during sign-in. You can change the display name at any time and multiple app registrations can share the same name. The app registration's automatically generated Application (client) ID, not its display name, uniquely identifies your app within the identity platform.

   

4. After registration, several IDs are created, some of these are required later to obtain an OAuth 2.0 token.

   

Add API permissions

1. Under the left menu, select API permissions and select Add a permission.

   

2. Navigate to APIs my organization uses and search for Office 365 Exchange Online.

   

3. Under Request API permissions, choose Application permissions, select Mail.Send, and select Add permissions.

4. After adding the API permission, admin needs to select Grant admin consent for.

   

We're supporting both: delegate permission and application permission to allow legacy OAuth third-party applications, as they use application permissions with app secrets.

Delegate Permissions:

1. In the API permissions tab, add Mail.Send API permission from Office 365 Exchange Online\Delegated Permissions.
2. In the API permissions tab, select Grant admin consent.
3. In the Authentication tab, enable Allow public client flows.
4. Use the HVE mail user's credentials to request a token for the audience https://outlook.office.com/.default.

Application Permissions:

1. In the API permissions tab, add Mail.Send API permission from Office 365 Exchange Online\Application Permissions.
2. In the API permissions tab, select Grant admin consent.
3. In the Certificate & secrets tab, add a new client secret.
4. Use the client secret to request a token for the audience https://outlook.office.com/.default.

HVE SMTP protocol exchange

To authenticate an SMTP server connection, the client must respond with an AUTH command in SASL XOAUTH2 format. SASL XOAUTH2 encodes the username and access token together in the following format:

base64("user=" + userName + "^Aauth=Bearer " + accessToken + "^A^A") 

^A represents a Control + A (%x01).

For example, the SASL XOAUTH2 format to access application@contoso.onmicrosoft.com with access token EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA is:

base64("user=application@contoso.onmicrosoft.com^Aauth=Bearer EwBAAl3BAAUFFpUAo7J3Ve0bjLBWZWCclRC3EoAA^A^A") 

Sample client-server message exchange that results in an authentication success:

[connection begins]

C: auth xoauth2

S: 334

C: dXNlcj1hcHBsaWNhdGlvbkBjb250b3NvLm9ubWljcm9zb2Z0LmNvbQFBdXRoPUJlYXJlciBFd0JBQWwzQkFBVUZGcFVBbzdKM1ZlMGJqTEJXWldDY2xSQzNFb0FBAQE=

S: 235 2.7.0 Authentication successful

[connection continues...]

Sample client-server message exchange that results in an authentication failure:

[connection begins]

C: auth xoauth2

S: 334

C: dXNlcj1hcHBsaWNhdGlvbkBjb250b3NvLm9ubWljcm9zb2Z0LmNvbQFBdXRoPUJlYXJlciBFd0JBQWwzQkFBVUZGcFVBbzdKM1ZlMGJqTEJXWldDY2xSQzNFb0FBAQE=

S: 535 5.7.3 Authentication unsuccessful