Archibus Extension for Microsoft Exchange

Using Exchange Impersonation

Note: For information on not using impersonation, see Avoiding Impersonation with Microsoft Exchange and Summary of Mailbox and Impersonation Combinations.

Note: Setting up Exchange Impersonation via a service account is only required when authenticating to Exchange with basic authentication or NTLM authentication. The Archibus Extensions for Microsoft Exchange does not require a service account with impersonation rights when using OAuth2 authentication.

Exchange Impersonation is a mechanism that allows a single Windows Active Directory account to act on behalf of other users on a Microsoft Exchange mailbox, as if they were performing the action themselves.

To implement Exchange Impersonation:

1. Add the Active Directory Account for the Service Account. See Creating the Service Account later in this topic.
2. Apply permissions. See Applying Permissions later in this topic.

Note: Be aware that Exchange Impersonation works only via the Exchange Web Services API. This means that although the account is able to act on behalf of another user, it only works if it is done as an Exchange Web Service call; it does not work through Outlook, Outlook Web Access, or any other Exchange client.

User Accounts

The user has two accounts:

User Account	Purpose	Referred To As
Active Directory account	gives the user permission to log on to the domain	user's Active Directory Account (or AD Account)
Exchange Server Mailbox	pick up email and change the calendar	user's mailbox account

The AD account must have access rights to a corresponding mailbox account in order to receive mail, etc., but an AD account can exist without a corresponding mailbox account.

Service Account

Note: Creating a service account is not required when using OAuth authentication. Registering Archibus Web Central in Azure Active Directory grants the required impersonation rights.

The System Administrator creates an account that is referred to as the service account because it is used by the service to act on behalf of the user accounts. For example, you could name this account ewsproxy to help identify it as the service account. However, any valid user account can be used.

The System Administrator gives this service account Exchange Impersonation privileges for users. The service account will be assigned some permissions on both the service and the user accounts that allow the service account to act on behalf of the user accounts. The service account can then perform any action that users can perform on their mailboxes.

The service account does not need to have a mailbox account. Instead, it has only an Active Directory account.

Even if you have large, complex networks with multiple domains, one impersonation service account should be sufficient if the domains are configured on the same Exchange deployment. The application supports one impersonation account which needs access to the mailboxes of users of the Reservations application. They do not have to be on the same domain, but they must be part of the same Exchange "forest." The Exchange Client Access Server will route requests to the correct mailbox server containing the user's mailbox.

Adding the Active Directory Account for the Service Account

Adding the Active Directory account for the Service Account is equivalent to simply adding a normal user in the domain.

The steps are:

1. The System Administrator logs on to the Active Directory server and adds an account with the user name of the Service Account.
2. On the next page of the wizard, you are prompted for the password for this account. It's important to make this a strong password, and it's also recommended to set the 'Password never expires' flag. As this is intended to be a service account, changing the password will affect the service as well as the account.

Example PowerShell command to create the service account in Exchange Online

The service account can be an Active Directory account, without a mailbox: for example, archibus.svc@...

To create such an account on Exchange Online using PowerShell, enter the following command:

New-MailUser -Name "archibus.svc" -MicrosoftOnlineServicesID archibus.svc@alcm.onmicrosoft.com -Password (ConvertTo-SecureString -String 'dH#89opdk' -AsPlainText -Force)

Applying Exchange Impersonation Permissions on Exchange Server

Exchange Server enables fine-grained control of the application of permissions because it makes use of Role-Based Access Control (RBAC) to apply the permissions. Instead of applying the tokens to an account or a mailbox database, the System Administrator can define a scope to which the permission applies. This means that the administrator can get all the users in a group, for example, and set the permission for that group as a scope.

Exchange Server's Role-Based Access Control mechanism enables you as the System Administrator to define groups of users and assign those groups of users the ApplicationImpersonation role. Once that is done, any new users that are added to the group are automatically assigned the ApplicationImpersonation permission.

To set up permissions on Exchange Server:

• Create the service account. Reservations need one service account with the ApplicationImpersonation role.

• Define the users for this service account. The System Administrator can define a group of users that this service account can impersonate based on Active Directory properties. This ensures the service account can impersonate new users in that group without additional configuration.
• Define a management scope

  The next step is to assign the ApplicationImpersonation role to a ManagementScope.

  A management scope is a logical group of users that are defined by a common set of criteria. It is not necessarily an Active Directory Security Group. The System Administrator can define the scope to consist of users who meet a certain criteria, such as having a common manager.

  The System Administrator defines a management scope by using the New-ManagementScope commandlet. The RecipientRestrictionFilter parameter enables the System Administrator to define the criteria that select a list of users. The following command creates a management scope that will include only members of that group.

  New-ManagementScope -Name:"<group name>"
  -RecipientRestrictionFilter {memberofgroup -eq
  "cn=Sales,cn=Users,DC=procosgroup,DC=internal,DC=com"}

  The string at the end of the command line is a distinguished name string from the Active Directory that represents the security group. There are a number of different filters that can be applied to create a management scope. If the System Administrator adds or removes a user to or from the security group, the scope defined here will ensure that the permissions for the user are affected accordingly.

• Assign Roles

  Once the management scope exists, one or more management roles can be applied to the management scope. In this case, the System Administrator will assign the ApplicationImpersonation role for the service account user (such as ewsproxy) to the management scope that the System Administrator just created.

  New-ManagementRoleAssignment -Name:"<role name>"
  -Role:ApplicationImpersonation
  -User:"ewsproxy@procosgroup.com"
  -CustomRecipientWriteScope:"<group name>"

  So, in the command line above, the <role name> refers to the name of the management role assignment that is being created, while the <group name> refers to the name of the management scope that was created in the Defining a management scope section.