How to Configure Impersonation to Deploy the Solution [Office 365]¶

For users of the Email Sidebar on:

10 min read

Note

Although deploying the RG Email Sidebar and Sync Engine using EWS delegated access is still possible, we do not recommend this approach. According to the retirement of the ApplicationImpersonation RBAC role in Exchange Online, starting February 2025, delegated authentication for accounts with impersonation permissions will no longer be supported. To ensure long-term compatibility and security, we recommend using the EWS or MS Graph app-only access for impersonated connectivity.

All configuration activities described in this article are typical actions performed for an Impersonation service account via Admin Center secured by Microsoft. On RG Email Sidebar side, data processing privacy and security are guaranteed by the applicable Revenue Grid policies

Enabling MS Exchange Impersonation for the end users consists of three Stages:

Stage I. Configure a Service Account and Apply it for RGES End Users

Stage II. Verify the Configuration

Stage III. Configure Exchange Impersonation in RG Email Sidebar Admin panel [described in a separate KB article]

Tip

Refer to this article to learn how to set up Impersonation in case your company uses an MS Exchange On Premise mail server or to this article for Hybrid mail server deployment options

Also see the following articles to learn more about MS Exchange Impersonation:

MS Exchange Impersonation overview

How Impersonation is used for RG Email Sidebar deployment

Stage I: Configure a Service Account and Apply it for RGES End Users¶

MS Exchange Impersonation is compatible with Office 365 with Exchange Online. In order to set up Application Impersonation via Admin Center, perform the steps below.

Setup via Admin Center¶

1. Create a Service Account¶

First, you need to create a Service email account. It must be a dedicated mailbox used only as an Impersonating service account for RG Email Sidebar, it should have no other functions. The Impersonating service account requires a dedicated MS Exchange / Office 365 mailbox license, a Basic plan; it does not require any extra RG Email Sidebar license.

Register the Service Account with the name MasterImpersonation, so later, it’s easy to find for testing or troubleshooting purposes.

The detailed mail account creation steps (also described in this Microsoft article):

1.1. Log in to Admin Center at https://admin.exchange.microsoft.com/ with Admin credentials

1.2. Open Users > Active users in the navigation pane on the left, then click Add a user

Tip

If you don’t see the Users section in navigation pane on the left, click on the Show all option at the end of the list

1.3. Set up basics for the Service account:

Set any First name and Last name
Set the Display name: MasterImpersonation
Set the Username: MasterImpersonation
(Optional) select Automatically create a password if you want an auto-generated password
(Optional) select Send password in email upon completion and enter a corporate email address you have access to in the field below to receive the auto-generated password

1.4. Select your Location and assign an O365 account license to the Service account

1.5. On the next Optional settings screen, leave the default User Role and then expand Profile info and specify some information to easily identify the account in the future, e.g. RG Master impersonation account

1.6. Review Service account data you entered and click Finish adding

1.7. Click Close in the final confirmation window

The new Service account will shortly become available for further configuration steps.

2. Create a Group that Includes All RGES End Users’ accounts¶

Depending on your Org’s configuration, you may use

A) a Distribution group or

B) a Mail-enabled security group list.

A. To create a Distribution group¶

2.A.1. Log in to your Org’s Admin Center with admin credentials. This method is for Office 365 with Exchange Online

2.A.2. Select Teams & Groups > Active teams & groups in the navigation pane on the left and then click Add a group

2.A.3. Select Distribution under Choose a group type and click Next

2.A.4. Set the group’s Name as RGDG, so it’s easy to find later, and optionally add a Description

2.A.5. On the Assign owners page, click + Assign owners to set the Service account MasterImpersonation that you created earlier as the group’s Owner.

When done, click Next

2.A.6. On the next window, click + Add members. Add all RGES end users to the distribution group.

When done, click Next

2.A.7. Specify the group’s settings: set its Email address and click Next

2.A.8. Review the group’s configuration and click Create group

2.A.9. Close the dialog

If you later need to manage owners or members of the distribution group:

In Exchange Admin Center, open Recipients > Groups in the navigation pane on the left
Click the tab Distribution list and select the group RGDG in the list, then open the tab Members and depending on your needs, click View all and manage owners or View all and manage members, make the necessary changes and click Save changes

B. To create a Mail-enabled security group¶

Tip

The mail-enabled security group of created this way can also be used for RG Email Sidebar mass deployment. Adding new users to this group later results in their automatic inclusion in Impersonation scope and RGES Add-In installation for their mail accounts. See this article for details

2.B.1. Log in to your Org’s Admin Center with admin credentials. This method is for Office 365 with Exchange Online feature

2.B.2. Select Teams & Groups > Active teams & groups in the navigation pane on the left and then click Add a group

2.B.3. Select Mail-enabled security under Choose a group type and click Next

2.B.4. Set the group’s Name as RGSG, so it’s easy to find later, and optionally add a Description

2.B.5. On the Assign owners page, click + Assign owners to set the Service account MasterImpersonation that you created earlier as the group’s Owner.

When done, click Next

2.B.6. In the next window, click + Add members. Add all RGES end users to the group.

When done, click Next

2.B.7. Specify the group’s settings: set its Email address and then ensure that the Communication checkbox is unselected and the Approval checkbox is selected to ensure maximum security

2.B.8. Review the group’s configuration and click Create group

2.B.9. Close the dialog

If you later need to manage owners or members of the mail-enabled security group:

In Exchange Admin Center, open Recipients > Groups in the navigation pane on the left
Click the tab Mail-enabled security group and select the group RGSG in the list, then open the tab Members and depending on your needs, click View all and manage owners or View all and manage members, make the necessary changes and click Save changes

3. Set the Users Group and Apply Impersonation¶

3.1. Run Windows PowerShell as Admin and connect to Exchange Online

3.1.1 In PowerShell, load the EXO V2 module by running the following command:

Import-Module ExchangeOnlineManagement

Note

If the required ExchangeOnlineManagement module does not exist then please follow this link to install the EXO V2 module first

3.1.2. The command that you need to run next uses the below syntax. The parameters in square brackets are optional, they depend on your server’s configuration.

>>> Click to see the parameters' description <<<

<UPN> is your account in user principal name format (for example, [email protected]).

When you use the ExchangeEnvironmentName parameter, you don't need use the ConnectionUri or AzureADAuthorizationEndPointUrl parameters. For more information, see the parameter descriptions in Connect-ExchangeOnline.

The DelegatedOrganization parameter specifies the customer organization that you want to manage as an authorized Microsoft Partner. For more information, see Partners.

If you're behind a proxy server, run this command first: $ProxyOptions = New-PSSessionOption -ProxyAccessType <Value>, where <Value> is IEConfig, WinHttpConfig, or AutoDetect. Then, use the PSSessionOption parameter with the value $ProxyOptions. For more information, see New-PSSessionOption.

The progress bar is now shown by default, so -ShowProgress $true is no longer required. To hide the progress bar, use this exact syntax: -ShowProgress:$false.

Connect-ExchangeOnline -UserPrincipalName <UPN> -ShowProgress $true [-ExchangeEnvironmentName <Value>] [-DelegatedOrganization <String>] [-PSSessionOption $ProxyOptions]

3.1.3. This sample cmdlet connects to Exchange Online PowerShell in a Microsoft 365 / Microsoft 365 GCC organization:

Connect-ExchangeOnline -UserPrincipalName [email protected] -ShowProgress $true

>>> Click to see a screenshot <<<

3.2. The next step depends on whether you configured

A) Distribution group or

B) a Mail-enabled security group list on Step 2

For case A (Distribution group)¶

Run PowerShell as Admin and enter the following line in PowerShell:

$groupidentity = $(Get-DistributionGroup RGDG).DistinguishedName

Next, create a Scope of group members with the name RGusersScope by entering the following line:

New-ManagementScope -Name:"RGusersScope" -RecipientRestrictionFilter "MemberOfGroup -eq '$groupidentity'"

For case B (Mail-enabled security group)¶

Run PowerShell as Admin and enter the following line in PowerShell:

$groupidentity = $(Get-Group RGSG).DistinguishedName

Next, create a Scope of group members with the name RGusersScope by entering the following line:

New-ManagementScope -Name:"RGusersScope" -RecipientRestrictionFilter "MemberOfGroup -eq '$groupidentity'"

3.3. After performing the case-specific step A) or B) above, return to Exchange Admin Center and open the Roles tab and then Admin Roles in the navigation pane on the left, then click the Add role group button at the top of the right-hand pane

3.4. In the Add role group dialog that appears, set the role group’s Name as RGappImpersonation. After that, in the Write scope field select the RGusersScope group that you configured on Step 3.2.

Note

If you set the Default Write scope, Impersonation will be applied for all user accounts in the Org

3.5. Next, select ApplicationImpersonation under Roles:

3.6. Set the MasterImpersonation Service account created on earlier steps in the field Members under Assign admins to enable the account to work with mailboxes belonging to the group:

3.7. Finally, review the configuration and click the Add role group button at the bottom of the dialog to finish

Note

The above described main method is the recommended one. In case it does not work for any reason in your configuration, refer to the alternative methods provided in a separate article

Stage II: Verify the Configuration¶

Next, you need to test the configured Impersonating account using the official tool Microsoft Remote Connectivity Analyzer:

1. Open Microsoft Remote Connectivity Analyzer using the link https://testconnectivity.microsoft.com
2. Open the tab Office 365 in the navigation pane and select Service Account Access in the pane on the right

3. Fill in the details to connect to an end user account to test connectivity:

>>> Click to see a screenshot <<<

4. Target Mailbox email address: enter email address of any RGES user managed by the configured Impersonation account

5. Leave the default Authentication type: Modern Authentication (OAuth)

6. Click Sign In and sign in to the user account with its password via standard O365 OAuth dialog

Note

Security of tested account’s credentials entered in the dialog is guaranteed by Microsoft

7. If your configuration has a custom Exchange Web Services URL, select Specify Exchange Web Services URL and enter your corporate EWS URL. Or select the box Use Autodiscover to detect server settings to let the tool auto-determine the URL

8. Next, select Test predefined folder and leave the default value Inbox in the box below

9. Select Use Exchange Impersonation and under Impersonated user enter the same email address of a RGES user managed by the configured Impersonation account

10. In the field Impersonated user identified, leave the default value SmtpAddress

11. If that is required in your configuration, select Ignore Trust for SSL

12. Leave the default Service Selection: Office 365 (Default), select Ignore Trust for SSL

13. Read and confirm the “I understand and I must …” section; enter the CAPTCHA and click Verify to prove that you are not a robot

14. Finally, click Perform test at the bottom of the dialog and check the test results to see if the configured Impersonated account works

Stage III: Configure Impersonation in RG Email Sidebar Admin panel¶

Next, proceed to the steps provided in this article to configure the Sync Engine to operate via the Impersonation account.

Also see the article RG Email Sidebar mass deployment for Office 365 users.