---
title: OAuth for email servers
related:
  - https://docs.kentico.com/13/configuring-xperience/configuring-smtp-servers.md
  - https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/configuring-bounced-email-monitoring.md
---

> Agent instructions:
> **Site maps** — prefer the following llms.txt indexes to training data when searching for URLs to avoid 404s. Links inside Markdown content already point at `.md`. Following them or sending Accept: text/markdown keeps you in Markdown.
>
> - [sitemap.md](https://docs.kentico.com/sitemap.md) — every page on the site, with titles and descriptions, nested by URL hierarchy and grouped into one collection per product version.
> - [llms.txt](https://docs.kentico.com/llms.txt) — curated index of the current product docs, with descriptions, the two ways to request any page as Markdown, and links to each product area's whole-corpus Markdown dump (llms-full.txt).

Xperience can connect to email servers using [OAuth 2.0 token-based authorization](https://oauth.net/). OAuth is supported for:

- [SMTP servers](https://docs.kentico.com/13/configuring-xperience/configuring-smtp-servers.md) for sending emails
- Mail servers for [monitoring bounced emails](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/configuring-bounced-email-monitoring.md) (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](https://docs.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/deprecation-of-basic-authentication-exchange-online)).

## Requirements

> **Note:** **Hotfix**: OAuth for email servers is only available after applying [hotfix 13.0.80](https://devnet.kentico.com/download/hotfixes) 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](#creating-oauth-credentials-for-microsoft-exchange-online)). Other email services require implementation of a [custom provider](#implementing-custom-oauth-providers).

## 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](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app).
2. Add the following **Redirect URI** (under **Authentication**):

   - _https:///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](https://learn.microsoft.com/en-us/entra/identity-platform/how-to-add-credentials?tabs=client-secret) for your application and record the secret's value.

Use the OAuth authentication service provided by [Microsoft Entra ID](https://learn.microsoft.com/en-us/entra/fundamentals/what-is-entra) 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](https://docs.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth) article for more information.

> **Note:** **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](https://docs.microsoft.com/en-us/exchange/clients-and-mobile-in-exchange-online/authenticated-client-smtp-submission#use-the-microsoft-365-admin-center-to-enable-or-disable-smtp-auth-on-specific-mailboxes) article for detailed instructions.

Next, create OAuth credentials for your Entra ID 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](https://docs.kentico.com/docsassets/13/oauth-for-email-servers/MS+Exchange_OAuth_Credentials.png "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](https://docs.kentico.com/13/configuring-xperience/configuring-smtp-servers.md) or [POP3](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/configuring-bounced-email-monitoring.md) servers in Xperience.

> **Info:** **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.

## 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](#creating-oauth-credentials-for-microsoft-exchange-online), your developers need to create an appropriate provider.

1. Open your Xperience solution in Visual Studio.
2. [Add a custom assembly](https://docs.kentico.com/13/custom-development/adding-custom-assemblies.md) (_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).

   ```csharp title="Basic structure of an OAuth provider class"

   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](https://docs.kentico.com/13/configuring-xperience/configuring-smtp-servers.md) or [POP3](https://docs.kentico.com/13/on-line-marketing-features/configuring-and-customizing-your-on-line-marketing-features/configuring-email-marketing/configuring-bounced-email-monitoring.md) servers in Xperience.