Exchange Integration

Features

The Microsoft Exchange integration makes it possible to synchronize emails, calendar events, contacts, and tasks with Grape, and make them available in Grape Search.

When communicating with an Exchange server, the integration makes use of a special service account in Exchange, which is only used for synchronization with Grape, and has the permission to impersonate individual users.

Requirements

• Microsoft Exchange 2016
• The Exchange server needs to be reachable from the Grape server through HTTPS (port 443) with a valid certificate recognized by Grape. Specifically the EWS url must be reachable from the grape server.
• Impersonated users need to be imported from Active Directory.
• The service account needs to be created in Active Directory and have the necessary impersonation permission in Exchange.

Administrator Setup

In order to enable the Exchange integration in an on-premises environment without using a service account, please follow these steps:

1. Run grape configure --enable exchange.
2. Answer y to “Use exchange integration”.
3. Choose a strong random string for “Exchange password encryption key”. This string will be used as the encryption key for Exchange the passwords of the defined service accounts. Note that changing this setting later will invalidate all saved Exchange server definitions.
4. Restart the Grape server with grape install.
5. Ensure that the service account exists in your Active Directory, and that it has the necessary role in Exchange.
6. After the Grape server has started up successfully, navigate to the Django administration section, and in the section titled “Exchange Service Integration”, select “Add” next to “Exchange servers”.
7. As the Exchange URL, enter your Exchange server’s full EWS URL.
8. Enter a description – this will be displayed to the users in case there are multiple Exchange servers defined in their organization.
9. As the Exchange service username, enter the username, including the domain prefix (for example, DOMAINNAME\username).
10. Finally, enter the password of the service account, and choose a Grape organization which should have access to this Exchange server.

There are two possible ways to assign the impersonation role to an Active Directory account. In both cases, the account needs to be created in Active Directory first, and have a password configured. We recommend using a regular user account in your AD, not a managed service account.

Setting up a service account using the Exchange Admin Center

This option is convenient, if you want to allow the service account to impersonate all users in your organization.

1. Open the Admin Center (https://exchange-server/ecp/), and log in as an administrator.

2. Navigate to “admin roles” in the “permissions” section.

3. Create a new role assignment by clicking the + icon.

   

4. Enter a name (for example, “Grape Impersonation”), choose ApplicationImpersonation as the role, and select the service account.

   

Setting up a service account using Powershell

This option is necessary if you want to restrict the impersonation privilege only to a certain portion of your organization, such as a certain AD group. With this method we create a management scope which defines the group of users that our service account will be able to impersonate, and then assign the ApplicationImpersonation role to the service account with this scope.

1. Launch an Exchange Management Shell as an administrator.

2. Create a new management scope with the following command:

   New-ManagementScope -Name:"Grape Users" -RecipientRestrictionFilter {memberofgroup -eq "cn=GrapeUsers,DC=company,DC=com"}
   

   You will need to replace the distinguished name with one that applies to your organization.

3. Finally, assign the role to your service account:

   New-ManagementRoleAssignment -Name:"Grape Impersonation" -Role:ApplicationImpersonation -User:"GrapeServiceAccount" -CustomRecipientWriteScope:"Grape Users"
   

   Here, the -User argument will need to be the username of your service account, and -CustomRecipientWriteScope needs to be the same name that you gave to the new management scope in the previous command.

User Setup

If your organization has multiple Exchange servers configured, you will need to choose which one of them you want to use.

Afterwards, you will be asked to choose the folders you want to make available in Grape Search, as well as who is allowed to search the folders.

If your Grape is configured to use a service account, you should be immediately taken to the second page, where you can select folders for synchronization, without having to enter any authentication details.