Configure impersonation

Learn how to grant the impersonation role to a service account by using the Exchange Management Shell.

Impersonation enables a caller, such as a service application, to impersonate a user account. The caller can perform operations by using the permissions that are associated with the impersonated account instead of the permissions associated with the caller's account.

Exchange Online, Exchange Online as part of Office 365, and versions of Exchange starting with Exchange 2013 use role-based access control (RBAC) to assign permissions to accounts. Your Exchange server administrator will need to grant any service account that will be impersonating other users the ApplicationImpersonation role by using the New-ManagementRoleAssignment cmdlet.

Configuring the ApplicationImpersonation role

When you or your Exchanger server administrator assigns the ApplicationImpersonation role, use the following parameters of the New-ManagementRoleAssignment cmdlet:

  • Name – The friendly name of the role assignment. Each time that you assign a role, an entry is made in the RBAC roles list. You can verify role assignments by using the Get-ManagementRoleAssignment cmdlet.

  • Role – The RBAC role to assign. When you set up impersonation, you assign the ApplicationImpersonation role.

  • User – The service account.

  • CustomRecipientScope – The scope of users that the service account can impersonate. The service account will only be allowed to impersonate other users within the specified scope. If no scope is specified, the service account is granted the ApplicationImpersonation role over all users in an organization. You can create custom management scopes by using the New-ManagementScope cmdlet.

Before you can configure impersonation, you need:

  • Administrative credentials for the Exchange server.

  • Domain Administrator credentials, or other credentials with the permission to create and assign roles and scopes.

  • Exchange management tools. These are installed on the computer from which you will run the commands.

To configure impersonation for all users in an organization

  1. Open the Exchange Management Shell. From the Start menu, choose All Programs > Microsoft Exchange Server 2013.

  2. Run the New-ManagementRoleAssignment cmdlet to add the impersonation permission to the specified user. The following example shows how to configure impersonation to enable a service account to impersonate all other users in an organization.

    New-ManagementRoleAssignment -name:impersonationAssignmentName -Role:ApplicationImpersonation -User:serviceAccount 
    

To configure impersonation for specific users or groups of users

  1. Open the Exchange Management Shell. From the Start menu, choose All Programs > Microsoft Exchange Server 2013.

  2. Run the New-ManagementScope cmdlet to create a scope to which the impersonation role can be assigned. If an existing scope is available, you can skip this step. The following example shows how to create a management scope for a specific group.

     New-ManagementScope -Name:scopeName -RecipientRestrictionFilter:recipientFilter
    

    The RecipientRestrictionFilter parameter of the New-ManagementScope cmdlet defines the members of the scope. You can use the properties of the Identity object to create the filter. The following example is a filter that restricts the result to a single user with the user name "john."

    Name -eq "john"
    
  3. Run the New-ManagementRoleAssignment cmdlet to add the permission to impersonate the members of the specified scope. The following example shows how to configure a service account to impersonate all users in a scope.

     New-ManagementRoleAssignment -Name:impersonationAssignmentName -Role:ApplicationImpersonation -User:serviceAccount -CustomRecipientWriteScope:scopeName
    
    

After your administrator grants impersonation permissions, you can use the service account to make calls against other users' accounts. You can verify role assignments by using the Get-ManagementRoleAssignment cmdlet.

See also