---
title: "Exchange ESA Impersonation"
canonical: "https://help.agiloft.com/space/HELP/598671383/Exchange+ESA+Impersonation"
format: markdown
---
> Macro (anchor)

Microsoft Exchange [Impersonation](https://msdn.microsoft.com/en-us/library/office/bb204095%28v=exchg.140%29.aspx?f=255&MSPPError=-2147217396) configuration greatly depends on how your Exchange server is set up. The steps below will enable you to create the most basic impersonation setup. If you require a more customized configuration, please consult your Exchange administrator.

# General Principles

- In order to access the data from the <span style="color: #000000">Agiloft</span> synchronized accounts, the <span style="color: #000000">Agiloft</span> Exchange Synchronization setup user needs to be able to impersonate the accounts. In our example that user will be Administrator.
- All the accounts to be synchronized should be marked as allowed for impersonation by the Administrator.
- For more detailed information please refer to [Configuring Exchange Impersonation (Exchange Web Services)](http://msdn.microsoft.com/en-us/library/bb204095%28EXCHG.80%29.aspx).   
Note: For Exchange 2013 impersonation the procedure was changed. Please see [https://msdn.microsoft.com/en-us/library/office/dn722376(v=exchg.150).aspx](https://msdn.microsoft.com/en-us/library/office/dn722376(v=exchg.150).aspx)
- <span style="color: #000000">Agiloft</span> only synchronizes users with CN=Users inside the DN. In order to define the user's DN we recommend using a powershell script described at [https://gallery.technet.microsoft.com/scriptcenter/PowerShell-Script-Finding-3e18ca13](https://gallery.technet.microsoft.com/scriptcenter/PowerShell-Script-Finding-3e18ca13)

## Parameters

The following six parameters are required when using the Exchange ESA:

- **Microsoft Active Directory host** – the host server where Exchange is located; it should also contain AD (Active Directory).
- **Microsoft Active Directory port** – a port to access AD. For example, you can use port 389 (no-ssl) or 636 (ssl), or any re-mapped ports.
- **MASD user** **to perform CRUD actions on contacts **– a user name without domain or Domain Name (DN), since all these formats will be used to connect attempts between the provided domain and the base DN.
- **MASD domain** – a domain which the user belongs to.
- **Base DN** - A base DN for the AD. To define a base DN...
  - In the [Ldp tool](https://technet.microsoft.com/en-us/library/cc772839%28v=ws.10%29.aspx?f=255&MSPPError=-2147217396), connect to the host
  - Check the tree and find the proposed base DNs.
    
- **Organizational Unit** - a structure which contains the People or Contacts. In order to distinguish the synchronized users, it is useful to place them in an Organizational Unit; create one if needed.


# How to Check Connection to LDAP

Use [ldapsearch](https://linux.die.net/man/1/ldapsearch) from the OpenLDAP project to check the connection from <span style="color: #000000">Agiloft</span> to LDAP. The example below shows a connection to LDAP with different ports and user formats. <span style="color: #000000">Agiloft</span> can use all of these formats. 

<details>
<summary>LDAP Connection</summary>

```
user@userhome ~ $ 
LDAPTLS_REQCERT=allow ldapsearch -H "ldap://xwin.home.local:389" -D 
"Administrator" -w xxx -b "dc=home,dc=local" -s sub 
"(mail=Administrator@home.local)" mail
# extended LDIF
#
# LDAPv3
# base <dc=home,dc=local> with scope subtree
# filter: (mail=Administrator@home.local)
# requesting: mail
#

# Administrator, Users, home.local
dn: CN=Administrator,CN=Users,DC=home,DC=local
mail: Administrator@home.local

# search reference
ref: ldap://ForestDnsZones.home.local/DC=ForestDnsZones,DC=home,DC=local

# search reference
ref: ldap://DomainDnsZones.home.local/DC=DomainDnsZones,DC=home,DC=local

# search reference
ref: ldap://home.local/CN=Configuration,DC=home,DC=local

# search result
search: 2
result: 0 Success

# numResponses: 5
# numEntries: 1
# numReferences: 3
user@userhome
 ~ $ LDAPTLS_REQCERT=allow ldapsearch -H "ldaps://xwin.home.local:636"
 -D "Administrator" -w xxx -b "dc=home,dc=local" -s sub 
"(mail=Administrator@home.local)" mail
# extended LDIF
#
# LDAPv3
# base <dc=home,dc=local> with scope subtree
# filter: (mail=Administrator@home.local)
# requesting: mail
#

# Administrator, Users, home.local
dn: CN=Administrator,CN=Users,DC=home,DC=local
mail: Administrator@home.local

# search reference
ref: ldaps://ForestDnsZones.home.local/DC=ForestDnsZones,DC=home,DC=local

# search reference
ref: ldaps://DomainDnsZones.home.local/DC=DomainDnsZones,DC=home,DC=local

# search reference
ref: ldaps://home.local/CN=Configuration,DC=home,DC=local

# search result
search: 2
result: 0 Success

# numResponses: 5
# numEntries: 1
# numReferences: 3
user@userhome
 ~ $ LDAPTLS_REQCERT=allow ldapsearch -H "ldaps://xwin.home.local:636"
 -D "Administrator@home.local" -w xxx -b "dc=home,dc=local" -s sub 
"(mail=Administrator@home.local)" mail
# extended LDIF
#
# LDAPv3
# base <dc=home,dc=local> with scope subtree
# filter: (mail=Administrator@home.local)
# requesting: mail
#

# Administrator, Users, home.local
dn: CN=Administrator,CN=Users,DC=home,DC=local
mail: Administrator@home.local

# search reference
ref: ldaps://ForestDnsZones.home.local/DC=ForestDnsZones,DC=home,DC=local

# search reference
ref: ldaps://DomainDnsZones.home.local/DC=DomainDnsZones,DC=home,DC=local

# search reference
ref: ldaps://home.local/CN=Configuration,DC=home,DC=local

# search result
search: 2
result: 0 Success

# numResponses: 5
# numEntries: 1
# numReferences: 3
user@userhome
 ~ $ LDAPTLS_REQCERT=allow ldapsearch -H "ldap://xwin.home.local:389" 
-D "CN=Administrator,CN=Users,DC=home,DC=local" -w xxx -b 
"dc=home,dc=local" -s sub "(mail=Administrator@home.local)" mail
# extended LDIF
#
# LDAPv3
# base <dc=home,dc=local> with scope subtree
# filter: (mail=Administrator@home.local)
# requesting: mail
#

# Administrator, Users, home.local
dn: CN=Administrator,CN=Users,DC=home,DC=local
mail: Administrator@home.local

# search reference
ref: ldap://ForestDnsZones.home.local/DC=ForestDnsZones,DC=home,DC=local

# search reference
ref: ldap://DomainDnsZones.home.local/DC=DomainDnsZones,DC=home,DC=local

# search reference
ref: ldap://home.local/CN=Configuration,DC=home,DC=local

# search result
search: 2
result: 0 Success

# numResponses: 5
# numEntries: 1
# numReferences: 3
```
</details>

# Scripts

Run the following scripts in PowerShell:

## ms-Exch-EPI-Impersonation - Granting Impersonation Rights to the Administrator

The ms-Exch-EPI-Impersonation permission gives the administrator the ability to submit an impersonation call. 

```powershell
C:\>C:\WINDOWS\system32\windowspowershell\v1.0\powershell.exe -PSConsoleFile
"C:\Program Files\Microsoft\Exchange Server\bin\exshell.psc1" -command
"Get-ExchangeServer | where {$_.IsClientAccessServer -eq $TRUE} |
ForEach-Object {Add-ADPermission -Identity $_.distinguishedname -User
(Get-User -Identity Administrator | select-object).identity
-extendedRight ms-Exch-EPI-Impersonation}" 
Identity  User               Deny  Inherited Rights
--------  ----               ----  --------- ------
MYADM     HOME\Administrator False False     ms-Exch-EPI-Impersonation
```

## ms-Exch-EPI-May-Impersonate - Granting Permission to Impersonate a Specific User or Account

After impersonation permissions are established on a server, the administrator can be granted permission to impersonate a specific account or any account in a mailbox database.

The ms-Exch-EPI-May-Impersonate permission is used to grant the caller access to specific accounts.

The following script allows the administrator to impersonate any account found in the mailbox database at the time of the script run: 

```powershell
C:\>C:\WINDOWS\system32\windowspowershell\v1.0\powershell.exe -PSConsoleFile
"C:\Program Files\Microsoft\Exchange Server\bin\exshell.psc1" -command
"Get-MailboxDatabase | ForEach-Object {Add-ADPermission -Identity
$_.DistinguishedName -User Administrator -ExtendedRights
ms-Exch-EPI-May-Impersonate}" 
Identity        User               Deny  Inherited Rights
--------        ----               ----  --------- ------
MYADM\First ... HOME\Administrator False False     ms-Exch-EPI-May-Impersonate 
```

This script grants the same permission for a specific user: 

```powershell
 C:\>C:\WINDOWS\system32\windowspowershell\v1.0\powershell.exe -PSConsoleFile
"C:\Program Files\Microsoft\Exchange Server\bin\exshell.psc1" -command
"Add-ADPermission -Identity 'John Doe' -User Administrator
-extendedRight ms-Exch-EPI-May-Impersonate" 
Identity      User               Deny  Inherited Rights
--------      ----               ----  --------- ------
foe.local/... HOME\Administrator False False     ms-Exch-EPI-May-Impersonate 
```

You need to run these or similar scripts for new accounts when they are created with the need to be synchronized. It is possible to add this script to the scheduler to run periodically; for example as often as <span style="color: #000000">Agiloft</span> synchronization is run.

# Define and Restrict Impersonation Users in the Organization

Your company may not wish to sync all users of the organization to the impersonation user - in these cases, the user must not have the `ManagementRoleAssignment`<span style="color: #333333"> without any filter. </span>

1. To prevent this, use the `Get-ManagementRoleAssignment` and `Remove-ManagementRoleAssigned` commands if necessary to restrict the role assignment of the user with impersonation.
2. Next, create a custom filter for selected users. See [here ](https://msdn.microsoft.com/en-us/library/office/dd335137(v=exchg.150).aspx)for more information about the syntax.
  1. For example, to create a custom filter for all users apart from "QQQ", use `New-ManagementScope –Name:allExceptQQQ –RecipientRestrictionFilter:recipientFilter {Name -ne "QQQ"}.`
3. Introduce the ManagementRoleAssignment, using a defined custom restriction.
  1. Using the example above, this could be `New-ManagementRoleAssignment –Name:impersonationAssignmentName –Role:ApplicationImpersonation –User:serviceAccount –CustomRecipientWriteScope:allExceptQQQ`.

At this point, the <span style="color: #000000">Agiloft</span> Exchange ESA will be configured to impersonate all users in the organization apart from the user with name QQQ. Depending on the `SKIP_NON_IMPERSONIZED_USERS` configuration variable, the user "QQQ" will either be retrieved - without contacts and events - or just skipped at sync time. 

> Macro (hide-if)
> 
> #### Related articles
> 
> > Macro (contentbylabel)