Exchange Setup Instructions for Grip Integration

Overview

This document provides step-by-step instructions for setting up your Exchange environment to allow Grip to access and interact with your mail system. The setup involves configuring the Exchange Web Services (EWS) endpoint, creating a dedicated service account, and setting up impersonation permissions. These steps ensure that Grip can authenticate and read information from your Exchange server securely.

The purpose of this guide is to assist technical users in integrating their Exchange server with Grip to facilitate enhanced security monitoring and operations.

Understanding The Technology

For further reading about the functionalities we are leveraging in EWS, you can read the following articles:

• EWS operations in exchange.

• Impersonation and EWS in exchange.

• Securing on-premises service accounts

• Discovery management.

Prerequisites

• Administrator access to the Exchange server.

• Familiarity with Exchange Management Shell commands.

• Access to Active Directory for creating and configuring service accounts.

Step 1 – Configure EWS Endpoint

To retrieve your EWS endpoint run the following command on your exchange server, in the Exchange Management Shell:

Get-WebServicesVirtualDirectory |Select name, *url* | fl

Step 2– Create Service Account

1. To open the Active Directory Users and Computers (ADUC) Microsoft Management Console (MMC) console, on the Active Directory server click Start > Run, enter dsa.msc, and press Enter.

2. Right-click the folder where you want to create the new account and select New > User.

3. Complete the following fields:

• First name

• Last name

• User logon name (For example: svc-GripSA)

• User logon name (pre-Windows 2000) — Optional. Modify the automatically generated name if necessary.

4. Click Next.

5. Complete the Password and Confirm Password fields and clear the User must change password at next logon check box.

We recommend selecting Password never expires to avoid interruptions. You can update the service account credential regularly.

6. Click Next and then click Finish.

Now that you’ve created the SA user, you must enable it in the exchange for it to be accessible to the exchange.

7. On your on-prem exchange server, open the Exchange Management Shell, on the exchange server click Start and search “Exchange Management Shell”, and press Enter.

8. Run the following command to enable the new user to be exchange user as well:
   

   Enable-Mailbox -Identity <GRIP_SERVICE_ACCOUNT_USERNAME>

9. Add the user to the role group “Discovery Management”:well:
   

   Add-RoleGroupMember -Identity "Discovery Management" -Member <GRIP_SERVICE_ACCOUNT_USERNAME>

Step 3 – Set Up Impersonation Permissions

You have three options to configure the exchange impersonation for the Grip SA:

• Configure the impersonation for all users in the organization.

• Configure the impersonation for specific users or a group of users.

• Configure the impersonation for a security group.

To configure Exchange Impersonation for all users in an organization

1. To open the Exchange Management Shell, on the exchange server click Start, search for “Exchange Management Shell”, and press Enter.

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

New-ManagementRoleAssignment -Name:<NAME_FOR_MANAGEMENT_ROLE_ASSIGNMENT> -Role:ApplicationImpersonation -User:<GRIP_SERVICE_ACCOUNT_USERNAME>

For Example

New-ManagementRoleAssignment -Name:gripImpersonationRoleAssignment -Role:ApplicationImpersonation -User:svc-GripSA

To configure Exchange Impersonation for specific users or groups of users

1. Open the Exchange Management Shell.

2. Run the New-ManagementScope cmdlet to create a scope to which the impersonation role can be assigned. The following example shows how to create a management scope for a specific group.

New-ManagementScope -Name:<SCOPE_NAME>
-RecipientRestrictionFilter:<RECIPIENT_FILTER>

The RecipientRestrictionFilter parameter of the New-ManagementScope cmdlet defines the members of the scope. You can use 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 mail address "test@exchange.com".

UserPrincipalName –eq "test@exchange.com"

For example:

# Specific User

New-ManagementScope -Name:gripImpersonationScope 

-RecipientRestrictionFilter:’UserPrincipalName –eq "test@exchange.com"’

# Specific User

New-ManagementScope -Name:gripImpersonationScope 

-RecipientRestrictionFilter:’UserPrincipalName –eq "test@exchange.com"’

# All Users with mailboxes

New-ManagementScope -Name:gripImpersonationScope 

-RecipientRestrictionFilter:’RecipientType -eq “UserMailbox”’

# Based on department

New-ManagementScope -Name:gripImpersonationScope 

-RecipientRestrictionFilter:’Department -Eq “Executives”’

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 Exchange Impersonation to enable a service account to impersonate all users in a scope.

New-ManagementRoleAssignment -Name:<NAME_FOR_MANAGEMENT_ROLE_ASSIGNMENT> 

-Role:ApplicationImpersonation -User:<GRIP_SERVICE_ACCOUNT_USERNAME> -CustomRecipientWriteScope:<SCOPE_NAME>

For example:

New-ManagementRoleAssignment -Name:gripImpersonationRoleAssignment 

-Role:ApplicationImpersonation -User:svc-GripSA 

-CustomRecipientWriteScope:gripImpersonationScope

To configure Exchange Impersonation for a security group defined in the AD

1. Create a security group in your active directory and add all the desired users for the scope to that group. You can add or remove users later on and the scope will change accordingly.

Note.

Note: You must declare the security group as Universal for the exchange to recognize and mirror it. For more information: https://learn.microsoft.com/en-us/windows-server/identity/ad-ds/manage/understand-security-groups

2. Open the Exchange Management Shell.

3. Run the Enable-DistributionGroup cmdlet to mail-enables existing universal security group.

Enable-DistributionGroup -Identity <SECURITY_GROUP_NAME>

For example:

Enable-DistributionGroup -Identity GripScopeGroup

Now we’ll continue in similar steps to the specific users flow:

4. Run the Get-DistributionGroup cmdlet to retrieve the full object of the distribution group we created in the previous steps. Then, run the New-ManagementScope cmdlet to create a new scope that will include only the users from the group.

$DG = Get-DistributionGroup -Identity <SECURITY_GROUP_NAME> 
New-ManagementScope -Name: -RecipientRestrictionFilter:"MemberOfGroup -eq '$($DG.DistinguishedName)'" 

For example:

$DG = Get-DistributionGroup -Identity GripScopeGroup 

New-ManagementScope -Name:gripImpersonationScope -RecipientRestrictionFilter:"MemberOfGroup -eq '$($DG.DistinguishedName)'"  

5. Run the New-ManagementRoleAssignment cmdlet to add the permission to impersonate the members of the specified scope (exactly as previously). xyz

New-ManagementRoleAssignment -Name:<NAME_FOR_MANAGEMENT_ROLE_ASSIGNMENT> -Role:ApplicationImpersonation -User:<GRIP_SERVICE_ACCOUNT_USERNAME> -CustomRecipientWriteScope:<SCOPE_NAME> 

For example:

https://outlook.office.com/bookwithme/user/c7735c2f5a5e45ffafb3b02036bbe9c0%40kovai.co?anonymous

Summary

After following these instructions will have successfully integrated your Exchange server with Grip. For any questions, contact your Grip representative.