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.

    Screenshot of 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.

    Screenshot of register an application.

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

    Screenshot of several IDs.

Add API permissions

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

    Screenshot of hveoauth api permissions.

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

    Screenshot of APIs my organization uses.

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

    Note

    The Mail.Send application permission does not grant the ability to send email from all Exchange mail users. Following the described configuration, only HVE Account type mail users will be able to send email, unless the application is explicitly authorized for other mail users through Exchange application access controls. Depending on your configuration, this is enforced using either: Application Access Policies (legacy), or Role Based Access Control for Applications in Exchange Online.

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

    Screenshot of grant admin consent.

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.

Restrict OAuth access to allowed applications

High Volume Email supports restricting OAuth authentication to a specific set of Microsoft Entra ID applications. This helps prevent unauthorized or unintended applications from using an HVE account and reduces the risk of misuse or unexpected billing. By default, any application with valid OAuth credentials and the required Exchange Online permissions can authenticate to HVE. With allowed applications, you can explicitly define which applications are permitted to send email using a specific HVE account.

How allowed applications work

When allowed applications are configured for an HVE account:

  • During OAuth authentication, HVE validates the application identity in the access token.
  • Only applications that are explicitly allowed for the HVE account can authenticate successfully.
  • Authentication requests from other applications are rejected. The validation is based on the service principal ID (object ID) of the Microsoft Entra ID application used to obtain the OAuth token.

Note

Allowed applications apply to OAuth authentication only. They do not affect SMTP Basic authentication using passwords.

Configure allowed applications

Allowed applications are configured per HVE account using Exchange Online PowerShell. You can add or remove Microsoft Entra ID applications by specifying their service principal GUIDs.

Note

To specify the allowed app IDs, you must use the service principal object ID from the Overview page of the Enterprise Application node (Azure Portal) for the application registration. Do not use the object ID from the Overview page of the App Registrations node. Using the incorrect Object ID will cause an authentication failure. Learn more about Authenticate an IMAP, POP or SMTP connection using OAuth.

Add allowed applications

Add-HVEAppAccess -Identity HVEaccount@contoso.com -AppIds <service-principal-id-1>,<service-principal-id-2>

Remove allowed applications

Remove-HVEAppAccess -Identity HVEaccount@contoso.com -AppIds <service-principal-id-1>,<service-principal-id-2>

View allowed applications

Get-HVEAccountSettings -Identity HVEaccount@contoso.com | Format-List *AllowedApps*

Limits and behavior

  • Each HVE account can have a maximum of 10 allowed applications configured.
  • If no allowed applications are configured for an HVE account, no additional application-level restriction is enforced.

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
  • Last updated on