OAuth for email servers

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

• SMTP servers for sending emails
• Mail servers for monitoring bounced emails (POP3)

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

Requirements

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.

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

Implementing custom OAuth providers

OAuth providers ensure secure communication between Xperience and specific email services. To use OAuth authentication for email services other than Microsoft Exchange Online, your developers need to create an appropriate provider.

1. Open your Xperience solution in Visual Studio.

2. Add a custom assembly (Class Library project) to the solution, or re-use an existing assembly.

3. Reference the project from both your live site and Xperience administration (CMSApp) projects.

4. Add a new class under the custom project, implementing the IEmailOAuthProvider interface (available in the CMS.EmailEngine namespace).

   Basic structure of an OAuth provider class

   Copy

   
   
   
    using CMS.EmailEngine;
   
    public class CustomOAuthProvider : IEmailOAuthProvider
    {
        // Determines whether the email service requires a Tenant ID for OAuth authentication
        // If true, adds the 'Tenant ID' field to the editing form in the Xperience 'Email OAuth credentials' application
        public bool RequiresTenantID => false;
   
        // Allows you to override the ASPX editing page for credentials in the Xperience 'Email OAuth credentials' application
        // Only needed if your email service requires non-default configuration options in the Xperience 'Email OAuth credentials' application
        // Return null to keep the default authorization dialog (\~/CMSModules/EmailEngine/Pages/OAuth2AccessTokenDialog.aspx)
        public string CustomAuthorizationDialogPath => null;
   
        // Gets the URL used to request an authorization code, which contains all the necessary information (client id, requested scopes, etc.)
        // The authorization code retrieval flow begins by redirecting the user to this URL
        // Parameters:
        // redirectUrl - a URL where the OAuth provider redirects whilst providing the authorization code ('redirect_uri' query string parameter).
        // state - a unique generated value used to prevent CSRF attacks. We recommend adding the value as a 'state' query string parameter to the authorization URL.
        // credentials - the OAuth credentials object created in Xperience storing the Client ID, Client secret, etc.).
        public string GetAuthorizationUrl(string redirectUrl, string state, EmailOAuthCredentialsInfo credentials)
        {
            ...
        }
   
        // Trades the provided 'authorizationCode' for an access token
        // Set the access token, token expiration and a refresh token into the EmailOAuthCredentialsInfo credentials object
        public void CompleteAuthorization(string authorizationCode, string redirectUrl, EmailOAuthCredentialsInfo credentials)
        {
            ...
            // You need to save the EmailOAuthCredentialsInfo object after setting the required values
            credentials.EmailOAuthCredentialsAccessToken = "oauthtoken_value";
            credentials.EmailOAuthCredentialsTokenExpirationUtc = DateTime.UtcNow.AddSeconds(tokenExpiration);
            credentials.EmailOAuthCredentialsRefreshToken = "refreshtoken_value";
   
            EmailOAuthCredentialsInfo.Provider.Set(credentials);
        }
   
        // Refreshes the EmailOAuthCredentialsAccessToken credentials
        public string RefreshToken(EmailOAuthCredentialsInfo credentials)
        {
            ...
            // You need to save the EmailOAuthCredentialsInfo object after setting the updated token values
            credentials.EmailOAuthCredentialsAccessToken = "new_oauthtoken_value";
            credentials.EmailOAuthCredentialsTokenExpirationUtc = DateTime.UtcNow.AddSeconds(tokenExpiration);
            credentials.EmailOAuthCredentialsRefreshToken = "new_refreshtoken_value";
   
            EmailOAuthCredentialsInfo.Provider.Set(credentials); 
        }
    }
   
   
    

Now create OAuth credentials for your email service in Xperience:

1. Open the Email OAuth credentials application in the Xperience administration.
2. Click New OAuth credentials.
3. Configure the credential properties for your provider:
   • Display name – any suitable name to identify your email service.
   • OAuth provider – select your OAuth provider class.
   • Fill in all required credentials for the given email service (Client ID, Client secret, etc.).
4. Click Save.

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