Configure Webex Connect Email App with Office365 Oauth

Introduction

This document describes the steps to configure an Email app for Office365 with Open Authorization (OAuth 2.0).

Contributed by Andrius Suchanka and Bhushan Suresh, Cisco TAC Engineer.

Prerequisites

Requirements

Cisco recommends that you have knowledge of these topics:

• Webex Contact Center (WxCC) 2.0
• Webex connectportal with Email flows configured 
• MS Azure access
• MS Office365 access

Components Used

The information in this document is based on these software versions:

• WxCC 2.0
• Cisco Webex Connect
• Microsoft Azure
• Microsoft Office365

The information in this document was created from the devices in a specific lab environment. All of the devices used in this document started with a cleared (default) configuration. If your network is live, ensure that you understand the potential impact of any command.

Configure

Step 1: Start email app configuration on Webex Connect

Start Email app configuration on Webex Connect platform. 

-Login to your Webex Connect tenant;

-Navigate to 'Assets->Apps', click 'Configure New App' and select 'Email'. Select 'OAuth 2.0' for authentication type, copy and store 'Forwarding Address' and 'Call Back URL' for later configuration steps:

Proceed to configuration on Microsoft side.

Step 2: Create an app in Microsoft Azure

Register an app in Azure portal as per 'Register an application with the Microsoft identity platform' document.

-Login to https://portal.azure.com;

-Navigate to 'Azure Active Directory', select 'App registrations' and click 'New registration';

-Provide application name, select appropriate account type, input Web 'Redirect URI' with your tenant name (that is https://yourwebexconnectname.us.webexconnect.io/callback as seen in step 1) and register the app:

-After app is registred - navigate to 'Authentication', scroll down to 'Implicit grand and hybrid flows', select 'Access tokens' option and save:

-Navigate to 'Certificates & secrets', select 'Client Secrets', click 'New client secret', add a description and validity length:

-Copy client secret value and store it for later use:

-Navigate to 'API permissions', click 'Add a permission', select 'APIs my organization uses', in search field input 'office 365' and select 'Office 365 Exchange Online'. Select 'Application permissions', expand 'Mail' section, check 'Mail.Send' and click 'Add permission':

-After said permission is added, admin consent has to be granted. Click on 'Grant admin consent':

-Navigate to 'Overview' and note down 'Application (client) ID' and 'Directory (tenant) ID' for further configuration use:

Note: make sure that that user consent for apps is allowed in Azure under 'Consent and permissions' for 'Enterprise applications' (this is a default settings):

Step 3: Configure mailbox user on Office365

-Login to https://admin.microsoft.com;

-Navigate to Users->Active Users;

-Select a user with a mailbox for integration with Webex Connect;

-After selecting specific user navigate to 'Mail', under 'Email apps' click on 'Manage email apps', make sure that 'Authenticated SMTP' is selected and click 'Save changes':

-Under 'Email Forwarding' click on 'Manage email forwarding', select 'Forward all emails sent to this mailbox', fill in 'Forwarding email address' with alias from Webex Connect App configuration as seen in step 1 (additionally if needed select 'Keep a copy of forwarded email in this mailbox') and click 'Save changes':

-Make sure that outbound email forwarding to external email addresses is allowed in your Microsoft 365 Defender portal.

-If not - create or modify existing anti-spam policies as per the Microsoft documentation:

Configure outbound spam filtering - Office 365

Note: if error related to 'Enable-OrganizationCustomization' is being shown while trying to save anti-spam policies with forwarding set to 'On', please run 'Enable-OrganizationCustomization' cmdlet as indicated in the Microsoft article - Enable-OrganizationCustomization (it can take up to 24 hours until said cmdlet change is taken into effect).

Note 2: in order to connect to Exchange Online PowerShell please research the article - Connect to Exchange Online PowerShell

Step 4: Configure Email App on Webex Connect

Switch back to Webex Connect email app configuration and fill in required fields.

-For 'Email ID' use mailbox which was configured femail forwarding towards Webex Connect email alis in step 3.

-Use the settings for SMTP configuration:

SMTP Server: smtp.office365.com
Port: 587
Security: STARTTLS

-For 'Username' use the same user as configured on step 3;

-For 'Client ID' use saved 'Application (client) ID' as indicated in step 2;

-For 'Client Secret' use saved 'Client secret' as indicated in step 2:

-Use 'https://login.microsoftonline.com/<your-azure-tenant-id>/oauth2/v2.0/authorize' for 'Authorization URL';

-Use 'offline_access https://outlook.office.com/SMTP.Send' for 'Scope';

-For 'Access Token URL' and 'Refresh Token URL' use 'https://login.microsoftonline.com/<your-azure-tenant-id>/oauth2/v2.0/token':

-Click 'Generate Token', make sure to use same user as configured in 'Username' field - 'Access Token', 'Refresh Token' and 'Validity' fields are populated:

-Click 'Save' and then 'Register to Webex Engage':

Verify

Verify by sending an email to Office 365 mailbox. If that email is presented to Webex Contact Center agent and a reply from Webex Contact Center agent is received by the original sender - configuration is successful.

Troubleshooting

If the emai flow still fails, access the Debug Console on Webex Connect portal page and search with the Email channel and the Timestamp 

This section has the Incoming Message and Outgoing Message along with the Status

Select the Message ID to gather more details on the Failure 

Once the Message ID is selected, the Error & Warnings section whill show more details of the error

If Cisco TAC needs to be enagaged, please gather the information: 

• Asset ID of the Email channel 
• Transaction ID and screenshot of the failed in the Debug logs as shown