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:
- Run
grape configure --enable exchange
. - Answer
y
to “Use exchange integration”. - 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.
- Restart the Grape server with
grape install
. - Ensure that the service account exists in your Active Directory, and that it has the necessary role in Exchange.
- 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”.
- As the Exchange URL, enter your Exchange server’s full EWS URL.
- Enter a description – this will be displayed to the users in case there are multiple Exchange servers defined in their organization.
- As the Exchange service username, enter the username, including the
domain prefix (for example,
DOMAINNAME\username
). - 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.
Open the Admin Center (
https://exchange-server/ecp/
), and log in as an administrator.Navigate to “admin roles” in the “permissions” section.
Create a new role assignment by clicking the
+
icon.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.
Launch an Exchange Management Shell as an administrator.
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.
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.