OAuth for email servers

Xperience can connect to email servers using OAuth 2.0 token-based authorization. OAuth is supported for:

OAuth provides a more secure alternative to basic authentication, which uses a simple combination of a username and password. Many mail services are deprecating support of basic authentication, leaving OAuth as the only viable authentication type. A notable example is Microsoft Exchange Online, which begins disabling basic authentication after October 1, 2022 (see Deprecation of Basic authentication in Exchange Online).


Hotfix: OAuth for email servers is only available after applying hotfix 13.0.80 or newer.

You need to have HTTPS set up for both your Xperience administration and live site.

Communication between Xperience and specific email services is ensured by an OAuth provider. By default, the system includes an OAuth provider for Microsoft Exchange Online (see Creating OAuth credentials for Microsoft Exchange Online). Other email services require implementation of a custom provider.

Managing OAuth credentials

To use OAuth authentication for an email server, you need to prepare credentials and generate an access token. Manage OAuth credentials in the Email OAuth credentials application within the Xperience administration.

You can use the created OAuth credentials to configure connections to mail servers throughout the system:

  • Default SMTP server (Settings → System → Emails → Default SMTP server)
  • Additional SMTP servers (SMTP servers application)
  • Bounced email server (Settings → On-line marketing → Email marketing → POP3 settings)
  • Email testing (System → Email)

In the email server configuration, select OAuth 2.0 as the Authentication type, fill in the username for the connection and then choose valid OAuth credentials.

Creating OAuth credentials for Microsoft Exchange Online

Start by preparing an application in the Microsoft Azure portal:

  1. Register an application with the Microsoft identity platform.
  2. Add the following Redirect URI (under Authentication):
    • https://<site domain>/CMSModules/EmailEngine/Pages/OAuth2AccessTokenDialog.aspx?redirected=1
      (insert your site's fully qualified domain name, including the application path or virtual directory)
  3. Add the following API permissions for your application – Microsoft Graph > Delegated permissions:
    • OpenId permissions > offline_access
    • POP > Pop.AccessAsUser.All
    • SMTP > SMTP.Send
    • User > User.Read (included by default for new applications)
  4. Record your applications Application (client) ID and Directory (tenant) ID values (you can find them on your application's Overview in the Azure portal).
  5. Add a client secret for your application and record the secret's value.

Use the OAuth authentication service provided by Azure Active Directory (Azure AD) to enable your application to connect with POP or SMTP protocols to access Exchange Online in Office 365. See the Authenticate an IMAP, POP or SMTP connection using OAuth article for more information.

Enable SMTP AUTH for your mailboxes

You also need to ensure that SMTP AUTH is enabled for your mailboxes in the Microsoft 365 admin center.

See the Enable or disable authenticated client SMTP submission (SMTP AUTH) in Exchange Online article for detailed instructions.

Next, create OAuth credentials for your Azure AD application in Xperience:

  1. Open the Email OAuth credentials application in the Xperience administration.
  2. Click New OAuth credentials.
  3. Fill in the following values:
    • Display name: any suitable name to identify your email application
    • OAuth provider
      • Assembly name: CMS.EmailEngine
      • Class: CMS.EmailEngine.MicrosoftExchangeOAuthProvider
    • Client ID: your application's Application (client) ID
    • Client secret: the client secret created for your applicaiton
  4. Click Save.
  5. Enter your application's Directory (tenant) ID into the Tenant ID field.
  6. Click Save again.
    Configuring OAuth credentials for Microsoft Exchange Online
  7. Click Get token to generate and store an OAuth access token for your application.

You can now use the created OAuth credentials to configure connections to SMTP or POP3 servers in Xperience.

Access token validity

OAuth access tokens have limited validity and expire after some time. However, Xperience automatically refreshes the access token as the previous one expires.