Skip to main content
Skip table of contents

EWS Agent Configuration

This document describes what settings and permissions the Discover EWS Agent requires to successfully communicate with and manage mailboxes and archives in Exchange On-Premises using Basic Authentication. If your connecting to Microsoft365 or using Modern Authentication (OAuth) on-premises, please refer to the configuration steps outlined in the guide: OAuth_Configuration_Guide

Before getting started, you will need to obtain the following information:

  • The URL to the PowerShell interface on the Exchange Service, it should look something like one of the examples below:

For Exchange Online: https://outlook.office365.com/powershell-liveid/

For Exchange 2016/2019 On-Premises: https://[Exchange Server]/powershell| (where [Exchange Server] is the fully qualified domain name of the Exchange Server machine)

  • The authentication type used in Exchange (Basic, Kerberos, etc.)

  • Credentials to an Exchange Administrative Account with administrative rights to query the Exchange environment (see the section titled Active Directory and Exchange Server Permissions later in this document for specific details)

Supply these settings when you install the Discover EWS Agent.

Note: Please use the steps outlined in Section1 below, if you would like to verify the configuration before entering them into Discover or if you run into any errors with Discover.

Section 1: PowerShell Setup/Access

The steps in this section are optional, but can be useful in determining if the Agent server is able to successfully communicate with Microsoft Exchange.

Begin by logging into the machine where the Discover Connector and EWS Agent are installed. We recommend logging using the same account credentials that the EWS Agent service is registered with. After logging in, launch a Windows PowerShell session (note, this process should be performed with both 32 and 64-bit versions of PowerShell). Then enter the command that permits this server to issue remote PowerShell calls:

Set-ExecutionPolicy Unrestricted

After entering the command, PowerShell prompts you to confirm the setting. Type the letter Y to complete the command. This server now has permission to issue PowerShell commands to a remote server – in this case either the Exchange 2016/2019 on-premise or Office 365.

Manually Validating A PowerShell Connection

The Discover EWS Agent is designed to query Exchange via PowerShell in order to obtain a list of valid mailbox Data Targets. For troubleshooting purposes, it is sometimes helpful to issue the appropriate PowerShell commands manually in order to identify any permissions related issues. The steps for performing a manual query are listed below for both Basic and oAuth (Modern) authentication methods.

Using Basic Authentication

There are a series of steps in this process. Those steps begin with storing a set of connection credentials (username & password) in memory. Typically, these credentials will be the same ones that your Discover EWS Agent is registered with. From a PowerShell command line type:
$UserCredential = Get-Credential

This command will provide a login prompt where you can enter the credentials that you plan to use with the EWS agent

Type in the username (we recommend the format DOMAIN\USERNAME) and valid password then click the OK button. These credentials are now stored in a variable called $UserCredential.
Next, attempt to initiate a connection to the remote (Exchange 2016/2019 on-premise or Office 365) server. The PowerShell command line for this step is:

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri https://outlook.office365.com/powershell-liveid/ -Credential $UserCredential -Authentication Basic -AllowRedirection

OR

$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri http://[FQDN of Exchange Server]/powershell -Credential $UserCredential -Authentication Basic -AllowRedirection


The first command shown above is formatted for an Office 365 connection; likewise, the second command is formatted for Exchange 2016/2019 On-Premise connection. When attempting to connect on an Exchange 2016 or Exchange 2019 on-premises server, be sure to change the portion of the text highlighted in yellow to a URI string that is valid for your environment. Also, use the appropriate authentication mechanism as configured in your Exchange environment.

If the connection is successful and the credentials you entered are valid, you will see several PowerShell notifications as the Exchange commands are imported:

Once the commands are loaded, create a PowerShell session by using the command:


Import-PSSession $Session

After the session is established, you can request a list of mailboxes by issuing the command

Get-Mailbox

This command should display a list of the EWS mailbox accounts on the server.

After validating that you can successfully connect, don't forget to close the PowerShell session by issuing the command:

Remove-PSSession $Session

Using oAuth (Modern) Authentication

The three PowerShell commands shown below are issued by the EWS Agent when it attempts to obtain a list of Microsoft 365 mailboxes using oAuth (Modern) authentication. To manually run these commands in a PowerShell session, replace the values in { } with the appropriate values for your environment:

$Secure_String_Pwd = ConvertTo-SecureString "{CERTIFICATE PASSWORD}" -AsPlainText -Force

Connect-ExchangeOnline -CertificateFilePath "{FULL PATH TO APP REGISTRATION CERTIFICATE}" -CertificatePassword $Secure_String_Pwd -AppID "{AZURE APPLICATION (CLIENT) ID}" -Organization "{AZURE TENANT ID}"

get-mailbox -ResultSize unlimited | fl UserPrincipalName,PrimarySmtpAddress,ServerName,Database 

Section 2: Windows Remote Management (WinRM) Configuration:

If you are using Basic Authentication to connect to the Exchange PowerShell interface, you will need to enable 'Allow Basic Authentication'. If you are using HTTP (instead of HTTPS) to access the PowerShell interface, you will need to enable 'Allow unencrypted Traffic'.
NOTE: If you are using one of the encrypted authentication types (anything other than Basic) then no changes need to be made to the WinRM Configuration.
These settings are configured through the Windows Group Policy applet. Typically, that applet can be accessed by typing the Windows Key+R then entering gpedit.msc. Once the editor is available, browse to the following location:
Computer Configuration  Administrative Templates  Windows Components  Windows Remote Management (WinRM)  WinRM Client:

After completing the Group Policy edit those changes must be distributed. To do this, open a command prompt (CMD) as administrator and issue this command:

gpupdate /force

Section 3: AD and Exchange Permissions if using Basic Authentication:

Active Directory Users and Computers:

In Active Directory Users and Computers, the service account being used for the EWS Agent needs to be added to the Exchange security group 'Organization Management'. Here is a description of that security group:

  • Organization Management = Administrative access to the entire Exchange Server organization and can perform almost any task against any Exchange Server object (Mailboxes, Archives, etc.). This group grants Administrative rights required by PowerShell.

https://docs.microsoft.com/en-us/exchange/permissions/permissions?view=exchserver-2016

Exchange Server:

In the Exchange Administrative Center (EAC), the service account that the Discover EWS Agent is using will need to have FULL ACCESS permissions to any mailbox that you would like it to manage. Also, it will need to be added to the Application Impersonation admin role. Here is a more detailed description of those access levels:

  • Full Access = Access granted via EAC or PS Command: Add-MailboxPermission -Identity "User MB" -User service account -AccessRights Fullaccess -AutoMapping $False

    • Definition - Allows the delegate to open the mailbox, and view, add and remove the contents of the mailbox.

https://docs.microsoft.com/en-us/exchange/recipients/mailbox-permissions?view=exchserver-2016

  • Application Impersonation Role = Access granted via EAC or PS Command: New-ManagementRoleAssignment -name:impersonationAssignmentName -Role:ApplicationImpersonation -User:serviceAccount

    • Definition - Management role that enables applications to impersonate users to perform actions on their behalf using EWS. The role can be granted only to one user on the account. Access granted via EAC or PS Command

https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-configure-impersonation
For more information about connecting to Microsoft Online with remote PowerShell, please refer to Microsoft TechNet. The page Connect To Exchange Online PowerShell may be a good place to start.

Section 4: Exchange Online and Azure AD Permissions:

Credential Configuration

To access and enable the Agent authentication fields, perform the following steps on the server where the EWS Agent Service is running:

  • Double click on the Connector Status Tool application shortcut on the desktop. If the shortcut does not exist, this utility may be found here:

C:\Program Files (x86)\Sherpa Software\Sherpa Connector\ SherpaConnectorStatus.exe

Once the application is open, click on the 'CrConfigure the EWS tab for oAuth:

  • Check the 'Use Azure Registration Credentials' box, this will gray out the Basic Authentication fields and enable OAuth Authentication. The fields listed in the screenshots below will need to be filled out with the IDs obtained during the App Registration process.

  • For the tenant ID you will need to input the company domain from AZURE (e.g. sherpasoftware.onmicrosoft.com), then copy/paste the client ID into their respective fields.

  • Click on the browse button to navigate to the folder path where the certificate file is stored. Please note that this cert file has an extension of (.pfx), NOT (.cer).

  • Lastly please enter the password which was assigned to the certificate at the time of creation and click SAVE to exit the window.edentials' link in the status tool window:

Configure the EWS tab for oAuth:

  • Check the 'Use Azure Registration Credentials' box, this will gray out the Basic Authentication fields and enable OAuth Authentication. The fields listed in the screenshots below will need to be filled out with the IDs obtained during the App Registration process.

  • For the tenant ID you will need to input the company domain from AZURE (e.g. sherpasoftware.onmicrosoft.com), then copy/paste the client ID into their respective fields.

  • Click on the browse button to navigate to the folder path where the certificate file is stored. Please note that this cert file has an extension of (.pfx), NOT (.cer).

  • Lastly please enter the password which was assigned to the certificate at the time of creation and click SAVE to exit the window.

Configure the EWS tab for Basic Authentication:

Do not check the "Use Azure Registration credentials" box, simply enter valid credentials into the two areas shown below:

The EWS agent may also be used to obtain a list of Data Owners from Azure AD. If you plan to use this feature, please complete the additional configuration steps described in Azure AD Certificate Installation

Verify Required PowerShell Modules are Installed

The remote PowerShell commands issued by Discover require these modules to be installed on the Agent server:

  • MSOnline

  • AzureAD

  • PowerShellGet

  • ExchangeOnlineManagement

  • PackageManagement

You can determine what modules are installed by launching a PowerShell session and issuing the command get-installedmodule as shown below:

If you do not have all of the required modules, they can be installed by issuing the commands listed below in a PowerShell session. If you encounter an error, please verify the version of TLS as described in Appendix A.

  • Install-Module -Name MSOnline

  • Install-Module -Name AzureAD

  • Install-Module -Name PowerShellGet -RequiredVersion 2.2.5 -Force -allowclobber

  • Install-Module -Name ExchangeOnlineManagement -RequiredVersion 2.0.4

  • Install-Module -Name PackageManagement (note: this module may be installed automatically)

Appendix A: TLS Configuration

If the connector server is running an older version of Microsoft Windows (2010 R2 or lower) it may not have the required support for TLS1.2. This Microsoft link provides more details on TLS dependencies and adding TLS support to older versions of Microsoft Windows:

 https://docs.microsoft.com/en-us/security/engineering/solving-tls1-problem

The versions of TLS currently installed on the server can be verified using this PowerShell command:

[Net.ServicePointManager]::SecurityProtocol

If TLs12 is not shown in the list, it will need to be installed on this server using one of these Microsoft methods. Option 2 (below) is the preferred method since it adds Tls12 to the whole system, where option 1 only persists for the current PS session.

  1. Modify the script in question to include the following:    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12; 

  2. Add a system-wide registry key (e.g. via group policy) to any machine that needs to make TLS 1.2 connections from a .NET app. This will cause .NET to use the "System Default" TLS versions which adds TLS 1.2 as an available protocol AND it will allow the scripts to use future TLS Versions when the OS supports them. (e.g. TLS 1.3). Registry keys are shown for both 64 and 32 bit systems:

reg add HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 /v SystemDefaultTlsVersions /t REG_DWORD /d 1 /f /reg:64 

reg add HKLM\SOFTWARE\Microsoft\.NETFramework\v4.0.30319 /v SystemDefaultTlsVersions /t REG_DWORD /d 1 /f /reg:32


JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close