Enterprise Chat and Email (ECE) is an additional feature provided under Contact Center Enterprise umbrella.  ECE provides multichannel functionality with CCE and offers an unified suite for chat and email interaction management to enable a blended agent for handling of web chat, email and voice interactions.

For this conversation, I am assuming that you already have working ECE which is integrated with CCE and Office 365.

Need for OAuth with ECE

ECE relies on email exchange like Office 365 to work for email channel. Normally ECE email aliases are configured with basic authentication, using Office 365 email address username and password.  However Microsoft has announced that they are deprecating support for basic authentication and have to move to OAuth 2.0.  Hence Cisco has also introduced several changes to facilitate this change and have ECE email aliases work with OAuth 2.0.  Personally I had very tough time following both Cisco and Microsoft and getting them on same understanding, to implement OAuth with ECE. So I would like to summarize what I did and successfully migrated my ECE 11.6(1) platform to OAuth in 3 months (including initial struggle with Cisco and Microsoft to understand their requirements).  With initial setup in place, it is quite easy to convert ECE email aliases from basic to OAuth.  Let’s have fun!!!

Pre-Requisites

Let’s briefly look at some pre-requisites to configure OAuth in ECE with Office 365.  We will be discussing about them in this forum.

1. ECE 12.0 or higher
2. If you are running ECE 11.6(1), then install below patches
   • ECE 11.6(1) ES 12 – adds OAuth configuration options to ECE
   • Click here to download this ES (needs CCO credentials)
   • ECE 11.6(1) ES12_ET1 – to resolve bug – CSCwd61276 – After ECE 11.6 ES 12 update scheduled reports come with empty body and attachment
   • Click here to download (needs CCO credentials)
3. Create externally accessible link to your ECE Web server
4. Register an Application with Azure Active Directory which provides OAuth token
5. Create Service Account in AD/Office 365 which will generate token on behalf of ECE email aliases

Installation steps for ECE 11.6 (1) ES 12

Pre-requisites

1. Copy the content of ECE 11.6 ES12 into a local temporary folder.
2. If the application is installed on SQL Server 2014 Enterprise Edition, backup the Active, Master and Reports databases.
3. If the application is installed on SQL Server 2014 Standard Edition, backup the Active, Master and Archive databases.
4. On ECE Web Servers, if previously modified, take a backup of file <ECE_Install_Directory>\eService\templates\finesse\gadget\agent\ece_config.js

Installation Steps

1. Stop Cisco service on
   • Application, Messaging and Services server for distributed ECE setup
   • Core server for co-located ECE setup
2. Run setup_windows.exe on the File, Services and Web servers / Core server (from the local temporary folder) and follow the steps in the installer.
3. If required from step 4 of pre-requisites, merge changes into file <ECE_Install_Directory>\eService\templates\finesse\gadget\agent\ece_config.js
4. Upon completion, start Cisco service on Application, Messaging and Services server / Core server.
5. On the agent’s desktop, clear browser cache.
6. After successful ES 12 installation, you will see below changes in ECE Administration Console:
   • OAuth Application tab shows up under Administration -> Partition: Partition name -> Email -> OAuth Application
   • Email Accounts tab shows up under Administration -> Department: Department name -> Email -> Accounts
   • New database table – EGML_MAIL_ACCOUNT – under eGActiveDB

Installation steps for ECE 11.6(1) ES12_ET1

This patch fixes Cisco bug – CSCwd61276 – After ECE 11.6(1) ES 12 update, scheduled reports come with empty body and attachment.  (BTW I reported this bug to Cisco first!!!).

Pre-requisites

1. Stop Cisco service on File, Services and Web servers / Core server depending what type of ECE deployment you have
2. Take the backup of <ECE_APP_Server or ECE_Core_Server>/Wildfly/wildfly-8.2.0.Final/modules folder.

Steps to apply patch

1. Unzip patch file and navigate to Application Server folder
2. Copy the contents of Application Server from patch to <ECE_Install_Dir> on Application server / Core server
3. Start Cisco service on File, Services and Web servers / Core server depending what type of ECE deployment you have

Create External URL for ECE Web server

While generating token with Azure Portal, you need to provide URL of ECE Web server which is accessible from external.  This link should be something like below:

https://yourcompany.ece.com which is pointing internally to https://yourecewebserver/ web/view/mail/admin/account/showauthcode.jsp

You need to work with your internal firewall / web hosting team to have this link created and test it by navigating it from external to your company.

Register Azure Active Directory Application

This task can be divided into 3 parts:

1. Register Application
2. Add Client Secret
3. Add API Permissions

Register Azure Application

1. Sign into the Azure portal.
2. Search for and select Azure Active Directory.
3. Under Manage, select App registrations > New registration.
4. In the Register an application page, provide the following details:
   • Name: Provide a user-facing display name for the application.
   • Supported Account Types: Select the Accounts in this organizational directory only (Single tenant) option.
   • Redirect URL: Provide the Redirect URL Click Register. This is the External URL created in previous step for ECE Web server
5. Click Register.
6. The Overview pane opens after the application is registered. The following information is displayed for the registered application. Please make a note of these as they will be needed while configuring ECE.
   • Application (client) ID (also called the client ID): This value uniquely identifies your application in the Microsoft identity platform.
   • Directory (tenant) ID (also called the tenant ID)

Add Client Secret

1. Sign into the Azure portal.
2. Search for and select Azure Active Directory.
3. Under Manage, click App registrations and select the application that you registered with Azure Active Directory.
4. Now, under Manage, select Certificates & secrets > New client secret.
5. In the Add a client secret page, provide the following details:
   • Description: Add a description for your client secret.
   • Expires: From the dropdown, select an expiration for the secret or specify a custom lifetime. You can select from the following options:
     • Recommended: 6 Months
     • 3 months
     • 12 months
     • 18 months
     • 24 months
     • Custom: you can provide custom start and end date
6. Click the Add button
7. The Client Secret Value and Secret ID are displayed.  Please make a note of these. We will need them while configuring ECE Application.

Assigning API Permissions

1. Sign into the Azure portal.
2. Search for and select Azure Active Directory.
3. Under Manage, click App registrations and select the application that you registered with Azure Active Directory.
4. Now, under Manage, select API Permissions > Microsoft Graph > Delegated permissions.
5. In the Request API page, select the following delegated permissions:
   • IMAP.AccessAsUser.All
   • Mail.Read
   • Mail.Read.Shared
   • Mail.ReadWrite
   • Mail.ReadWrite.Shared
   • Mail.Send
   • Mail.Send.Shared
   • offline_access
   • POP.AccessAsUser.All
   • SMTP.Send
   • User.Read
6. Click the Update Permissions button.

Create Service Account in AD

This service account is used to generate token on behalf of ECE email aliases.  If you do not want to use this service account then you will have to create individual ECE OAuth accounts in ECE for each of your email aliases, which can increase your maintenance overhead, depending on how many emails you manage in ECE, when your Azure Application’s Client Secret password expires and need to be updated.

I had explained how to create a Service Account in AD with application impersonation roles in my other blog – Configuring Unified Messaging for Unity.  Please refer section “Configuring Unified Messaging in Active Directory” in it to create Service Account.

Once Service account is created, follow below additional steps:

1. Assign Office 365 license to the Service Account
2. Add your Service Account to all ECE emails with Send As and Full Access mailbox delegation permissions in Office 365 as shown below.

3. You may also have to change your Default bulk email sending policy in Office 365, as it is defaulted to 300 emails per hour.  If you have many ECE email aliases (lest say 200+) then there are genuine chances that Default policy will get triggered and your Service Account may be restricted to not send any further outbound emails.  Please note, by doing above changes, now all your outgoing emails are counted under your Service Account.  Below is the snapshot of this policy (I learned this lesson the hard way as none of the MS or Cisco document outlines this):

ECE Configuration steps to add OAuth

Below tasks need to be completed in ECE for OAuth configuration:

1. Configuring OAuth Application
2. Configuring Email Accounts
3. Adding email aliases – New and Existing

Let’s have a look at each of these steps in detail.

Configuring OAuth Application

After registering your application with the Azure Active Directory, please follow below steps to configure your application details in the ECE Administration Console.

1. In the Tree pane, browse to Administration > Partition: Partition Name > Email > OAuth Applications.
2. In the List pane toolbar, click the New button
3. In the Properties pane, provide the following details:
   • Name: The name for the configuration.
   • Description: Provide a brief description.
   • Provider: Select Microsoft Office 365.
   • Endpoint: Select Worldwide.
   • Tenant ID: Provide the tenant ID assigned by Azure Active Directory.
   • Client ID: Provide the client ID assigned by Azure Active Directory.
   • Client Secret: Provide the client secret Value.
4. Click Save button.

Configuring Email Accounts and Alias

After configuring the OAuth applications, you need to create email accounts and add email aliases to them.

Creating Email Accounts

Please follow below steps in ECE Administration console:

1. In the Tree pane, browse to Administration > Department: Department Name > Email > Accounts.
2. In the List pane toolbar, click the New button
3. In the Properties pane, under the General tab, provide the following details:
   • Account Name: The name for the account.
   • Account Description: A brief description of the account.
   • Status: Select Active to make the account active. By default the status of an account is set as Active.
   • OAuth Registered App: Select the OAuth application, configured at the partition level.
   • Server Type: Select the server type you want to use. The options available are: POP3 and SMTP and IMAP and SMTP.  You will mostly be using POP3 and SMTP.
   • Address: The value is set as outlook.office365.com when an OAuth Registered App is selected. This value cannot be changed.
   • Authentication Type: The value is set as OAuth 2.0 and it cannot be changed.
   • Authentication Token: Click the Assistance button to generate the authorization code. On the Microsoft Sign in page, log into the Microsoft Service Account associated with the registered application and accept the permissions requested to generate the authorization code. Once the authorization is complete, a page is displayed with the authorization code.
   • Authorization code: Paste the authorization code.
4. Click on Save button.

Adding Email Aliases

Under the Email Address tab, you can either create new email aliases or you can add existing email aliases.  Existing Email aliases which are configured with basic authentication, will be converted to OAuth authentication when they are added to OAuth Email account and they will not be available in the Email Alias list.

To add a new Email Alias:

1. In the Tree pane, browse to Administration > Department: Department Name > Email > Accounts.
2. In the List pane, select the account to which you want to add a new email alias.
3. In the Properties pane, under the Email Address tab, click the New button.
4. In the Add a New Alias window, provide the following details:
   • Email address: Type the email address for the alias. This is required information. The email address you provide here should be first created on the incoming email server.
   • Status: Select Active.
   • Automatic BCC: Type the email address to which you want to send a BCC copy of the email. Only one BCC address may be used. Whenever an email is sent out from this alias, a BCC copy of that email is automatically sent to this address. You can use this option when you want to review later the replies sent out from a particular alias.
   • Send Email To: Specify the email address to which the outgoing emails from this alias should go.
   • Whenever an agent replies to a customer email, the reply is sent only to the email address specified in the Send Email To field and not to the customer email address. You can use this option to test that the alias has been configured properly and to test workflows. Make sure that after testing the alias you make this field empty.
   • Default alias: Select Yes to make this alias the default alias for the department. When an agent composes a new email, the default alias is selected as the From address for the email. The default email address is also used for activities transferred to this department from other departments, if the value of the setting Set “From” email address for email activities transferred between departments is set to Use default alias of destination department.  This is normally set to No.
   • Redirection Email Addresses: List the email addresses from where you want to redirect the emails to this email address. Separate the list of email addresses using a semicolon. While replying to emails, in the From field, agents will by default see the redirection email address from where the email came in the system.
   • Folder: The folder from which emails are fetched. By default, inbox is selected. This can be changed to a different folder if IMAP protocol is selected.
   • Shared Mailbox: To add shared mailboxes as aliases to email accounts, select Yes. The default value is No.
5. Click on Save button.

To add an existing Email Alias:

1. In the Tree pane, browse to Administration > Department: Department Name > Email > Accounts.
2. In the List pane, select the account to which you want to add an existing basic authenticated email alias.
3. In the Properties pane, under the Email Address tab, click the Add Existing Email Address button.
4. In the Add Existing Aliases window, from the list of existing email aliases within the department, click the check boxes next to the email aliases you want to convert to OAuth authenticated aliases.
5. If the existing email alias belongs to a shared account, click the check box next to the Add as Shared Mailbox option.
6. Click OK. The aliases are validated and then added to the account. When an alias, which does not belong to the email account, is added, an error is shown.

I will discuss more about various errors that you may encounter while adding email alias (new or existing) to the Email Account in a separate Troubleshooting document.

Removing liked Aliases from Email Accounts

When email aliases are removed from an email account, any aliases that are moved from basic authentication to OAuth authentication, are converted Email Accounts back to basic authentication. These aliases become available in the Aliases list in an inactive state. The newly added OAuth authenticated aliases are deleted permanently.

You cannot delete an email account, if an alias added to the email account:

• Is configured as the default alias and is in the active state.
• Is associated with a retriever service instance.
• Is used in an inbound workflow.

To remove an email alias from an Email Account:

1. In the Tree pane, browse to Administration > Department: Department Name > Email > Accounts.
2. In the List pane, select the email account for which you want to remove the email aliases.
3. In the Properties pane, under the Email Address tab, click the Delete button to delete the email aliases you want to remove.
4. You are prompted to confirm the deletion. Click OK.

NOTE: DO NOT click on list of email addresses to sort them before making any changes, i.e., delete or edit.  If you sort email address then they are seen sorted but when you click on Edit or Delete, it edits or deletes the unsorted email alias.  So you may end up editing or deleting and email address that you are not intended to update.  I learned it the hard way, so please avoid this.

 Testing Connections for Email Accounts

After creating and saving an email account, the Test Connection button on the properties pane toolbar is enabled. It is used to test the validity of an email account.

An email account can become invalid due to the following reasons:

• When the generated authorization code is revoked or has expired.
• When the email aliases no longer belong to the account.
• When the permissions granted to the OAuth application are revoked.

To test the connection for an email account:

1. In the Tree pane, browse to Administration > Department: Department Name > Email > Accounts.
2. In the List pane, select an existing email account.
3. In the Properties pane toolbar, click the Test Connection button to test the validity of the account. If the email account is valid, the following message pops up: Connection established successfully. If the account is rendered invalid, an error message is shown.

I will conclude this guide here to describe how to enable OAuth 2.0 with Cisco ECE and Office 365.  As this has been a long one, I will create another blog to go through some errors and troubleshooting steps that you may encounter during this process.

EDIT: If you are looking for troubleshooting guide, here’s the first part of it which highlights some of the system level issues. And here’s the second part which describes day to day operational issues and a bit of ECE Database schema.

As always, feel free to leave comments or questions!!!