Setting up email reply (POP) Integration using OAuth and Microsoft Office 365

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

Note that while Centercode’s integration features are intended to be approachable by a Product or Beta Testing professional, you this integration will likely require help from an internal technical or IT resource. Refer to our vocabulary and troubleshooting documentation .

OAuth2 support for POP protocols as described below is supported 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, start by reading the OAuth 2.0 protocol on Microsoft identity platform overview. 

You can use the OAuth authentication service provided by Azure Active Directory (Azure AD) to enable your application to connect with POP protocols to access Exchange Online in Office 365. To use OAuth with your application, you need to:

1. Register your application with Azure AD.
2. Get an access token from a token server.
3. Authenticate connection requests with an access token.

Register your application

To use OAuth, an application must be registered with Azure Active Directory.

Registering your application establishes a trust relationship between your app and the Microsoft identity platform. 

Follow these steps to create the app registration:

1. Sign in to the Azure portal.

2. If you have access to multiple tenants, use the Directories + subscriptions filter  in the top menu to switch to the tenant in which you want to register the application.

3. Search for and select Azure Active Directory.

4. Under Manage, select App registrations > New registration.

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

6. Specify who can use the application, sometimes called its sign-in audience.

7. Don't enter anything for Redirect URI (optional). You'll configure a redirect URI in the next section.

8. Select Register to complete the initial app registration.

   

When registration finishes, the Azure portal displays the app registration's Overview pane. You see the Application (client) ID. Also called the Client ID, this value uniquely identifies your application in the Microsoft identity platform.

Your application's code, or more typically an authentication library used in your application, also uses the Client ID. The ID is used as part of validating the security tokens it receives from the identity platform.

Add a redirect URI

A redirect URI is the location where the Microsoft identity platform redirects a user's client and sends security tokens after authentication.

In a production web application, for example, the redirect URI is often a public endpoint where your app is running, like https://contoso.com/auth-response. During development, it's common to also add the endpoint where you run your app locally, like https://127.0.0.1/auth-response or http://localhost/auth-response.

You add and modify redirect URIs for your registered applications by configuring platform settings as noted in the Register Your Application section above. 

Configure platform settings

Settings for each application type, including redirect URIs, are configured in Platform configurations in the Azure portal.

To configure application settings based on the platform or device you're targeting, follow these steps:

1. In the Azure portal, in App registrations, select your application.

2. Under Manage, select Authentication.

3. Under Platform configurations, select Add a platform.

4. Under Configure platforms, select the tile for your application type (platform) to configure its settings.

   

   Platform	Configuration Settings
   Web	Enter a Redirect URI for your app. This URI is the location where the Microsoft identity platform redirects a user's client and sends security tokens after authentication. Select this platform for standard web applications that run on a server.
   Single-page application	Enter a Redirect URI for your app. This URI is the location where the Microsoft identity platform redirects a user's client and sends security tokens after authentication. Select this platform if you're building a client-side web app by using JavaScript or a framework like Angular, Vue.js, React.js, or Blazor WebAssembly.
   iOS / macOS	Enter the app Bundle ID. Find it in Build Settings or in Xcode in Info.plist. A redirect URI is generated for you when you specify a Bundle ID.
   Android	Enter the app Package name. Find it in the AndroidManifest.xml file. Also generate and enter the Signature hash. A redirect URI is generated for you when you specify these settings.
   Mobile and desktop applications	Select one of the Suggested redirect URIs. Or specify a Custom redirect URI. For desktop applications using embedded browser, we recommend https://login.microsoftonline.com/common/oauth2/nativeclient For desktop applications using system browser, we recommend http://localhost Select this platform for mobile applications that aren't using the latest Microsoft Authentication Library (MSAL) or aren't using a broker. Also select this platform for desktop applications.

5. Select Configure to complete the platform configuration.

Redirect URI restrictions

There are some restrictions on the format of the redirect URIs you add to an app registration. For details about these restrictions, see Redirect URI (reply URL) restrictions and limitations.

Add credentials

Credentials are used by confidential client applications that access a web API. Examples of confidential clients are web apps, other web APIs, or service-type and daemon-type applications. Credentials allow your application to authenticate as itself, requiring no interaction from a user at runtime.

You can add both certificates and client secrets (a string) as credentials to your confidential client app registration.

Add a Certificate

Sometimes called a Public Key, a certificate is the recommended credential type because they're considered more secure than client secrets. For more information about using a certificate as an authentication method in your application, see Microsoft identity platform application authentication certificate credentials.

1. In the Azure portal, in App registrations, select your application.
2. Select Certificates & Secrets > Certificates > Upload certificate.
3. Select the file you want to upload. It must be one of the following file types: .cer, .pem, .crt.
4. Select Add.

Add a Client Secret

Sometimes called an application password, a client secret is a string value your app can use in place of a certificate to identity itself.

Client Secrets are considered less secure than certificate credentials. Application developers sometimes use client secrets during local app development because of their ease of use. However, you should use certificate credentials for any of your applications that are running in production.

1. In the Azure portal, in App registrations, select your application.
2. Select Certificates & Secrets > Client secrets > New Client Secret.
3. Add a description for your client secret.
4. Select an expiration for the secret or specify a custom lifetime.
   • Client secret lifetime is limited to two years (24 months) or less. You can't specify a custom lifetime longer than 24 months.
   • Microsoft recommends that you set an expiration value of less than 12 months.
5. Select Add.
6. Record the secret's value for use in your client application code. This secret value is never displayed again after you leave this page.

Get an Access Token

You can use one of Microsoft's MSAL client libraries to fetch an access token from your client application.

Alternatively, you can select an appropriate flow from the following list and follow the corresponding steps to call the underlying identity platform REST APIs and retrieve an access token.

1. OAuth2 authorization code flow
2. OAuth2 device authorization grant flow
3. OAuth2 client credentials grant flow

Make sure to specify the full scopes, including Outlook resource URLs, when authorizing your application and requesting an access token.

In addition, you can request for offline_access scope. When a user approves the offline_access scope, your app can receive refresh tokens from the Microsoft identity platform token endpoint. Refresh tokens are long-lived. Your app can get new access tokens as older ones expire.

Authenticate Connection Requests

You'll need your email provider's incoming server settings (POP) and outgoing server settings (SMTP). Here's a list of those settings for several email providers. If you don't see yours listed here, ask your email provider to give them to you.

You've just configured your OAuth Authentication credentials for POP email on Microsoft! 

You are now ready to send over the credential information Centercode needs in order to enable OAuth authentication for POP Email as outlined in our main article:  Email-Reply Integration for Feedback (via POP)