Overview

This article outlines a set of permissions and requirements in order to use the Mailbox Folder Structure Retrieval (UMPolling) feature within GFI Archiver with Microsoft Exchange.  

Prerequisites

Folder structure retrieval can only be enabled in Microsoft Exchange based environments

Solution

Automatic Creation

The easiest way to handle setting the correct access permissions is to utilize the built in functionality within the Archiver Console directly. 

1. Launch the Archiver Console
2. Navigate to Configuration > Mailbox Folder Structure Retrieval
3. Select Change Settings
4. Check "Enable Folder Structure Retrieval"
5. Select Create a new user account and click Next
   
6. Provide credentials with Admin rights in the Admin Exchange Group and Select OK
   

This creates a new user with the appropriate access rights to perform Folder Structure Retrieval. If this process fails or you would like to manually create the account, see the steps below.

Exchange User Access:

The user has access to the users’ mailboxes in the Microsoft Exchange Store(s). This can be done by performing the following

Microsoft Exchange 2016 / 2013 / 2010 [EWS]

1. Open the ‘Exchange Management Shell’ on the Microsoft Exchange 2010 server
2. Run the following cmdlet:
   

   New-ManagementScope -name "MAUMPolling" -recipientrestrictionfilter {recipienttype -eq "UserMailbox"}

3. Once the above is complete, run the following cmdlet (the account used in this step cannot have domain administrator rights):
   

   New-ManagementRoleAssignment -name "MAUMPollingRA" -role:applicationimpersonation -user "masynch@domain.com" -customrecipientwritescope "MAUMpolling"
   

   Example: New-ManagementRoleAssignment -name "MAUMPollingRA" -role:applicationimpersonation -user "masynch@mydomain.com" -customrecipientwritescope "MAUMpolling"
   
   
   ​Notes

   • ​Some Exchange 2010 environments also required the Exchange 2007 scripts to be run
   • The ManagementScope might already exist and be named differently. You can confirm the existing scope using the cmdlet Get-ManagementScope. For example, if GFI MailEssentials is running in the same environment the scope might have already been created and with the name GFI_MA_UMP. In this case it is not needed to run New-ManagementScope again. But run:

     • New-ManagementRoleAssignment -name "MAUMPollingRA" -role:applicationimpersonation -user "masynch@mydomain.com" -customrecipientwritescope "GFI_MA_UMP"

Microsoft Exchange 2007 SP1, SP2, SP3 [EWS]

1. Open the ‘Exchange Management Shell’ on the Microsoft Exchange 2007 server
2. Run the following cmdlet (the account used in this step cannot have domain administrator rights): 
   

   Add-ADPermission -identity "Mailbox Store" -User "Trusted User" -AccessRights GenericAll
   

   Example:  Add-ADPermission –Identity “Mailbox Database” -User "master-domain\masynch" –AccessRights GenericAll
3. ​Run the following cmdlet:  
   

   foreach ($exchangeServer in Get-ExchangeServer){if ($exchangeServer.ServerRole -match 'ClientAccess'){Add-ADPermission -Identity $exchangeServer.DistinguishedName -User 'domain\user' -ExtendedRights ms-Exch-EPI-Impersonation}}
   

   Example: foreach ($exchangeServer in Get-ExchangeServer){if ($exchangeServer.ServerRole -match 'ClientAccess'){Add-ADPermission -Identity $exchangeServer.DistinguishedName -User 'master-domain\masynch' -ExtendedRights ms-Exch-EPI-Impersonation}}

Microsoft ​Office 365 [EWS] (GFI MailArchiver 2014 or newer only)

1. Open a Power Shell with the Azure module (if not installed please refer to http://technet.microsoft.com/en-us/library/jj151815.aspx#bkmk_installmodule) or use the "Import-Module MSOnline" cmdlet
2. Execute the following commands

Set-ExecutionPolicy RemoteSigned

$O365Cred = Get-Credential

$O365Session = New-PSSession –ConfigurationName Microsoft.Exchange -ConnectionUri https://ps.outlook.com/powershell -Credential $O365Cred -Authentication Basic -AllowRedirection

Import-PSSession $O365Session

Connect-MsolService –Credential $O365Cred

Enable-OrganizationCustomization

New-ManagementScope -name "MAUMPolling" -recipientrestrictionfilter {recipienttype -eq "UserMailbox"}

New-ManagementRoleAssignment -name "MAUMPollingRA" -role:applicationimpersonation -user "masynch@mydomain.com" -customrecipientwritescope "MAUMpolling"

1. On-premise Active Directory requirements:
   • An on-premise Active Directory is required
   • Users which are to be folder synchronized in Office365 must be added into the local on-premise Active Directory
   • Users in Active Directory must have the MAIL field set which must map to the same email address of the corresponding user in Microsoft Office 365

Domain User Access:

The user must have specific accesses in the domain provided by the following steps. 

• Logon Rights Assignment: The user needs to have logon rights on the GFI Archiver machine. This can be achieved by performing the following:

Member Server

1. Login onto the Domain Controller and ensure that you are logged on as Administrator or you are using an account with domain administrative privileges
2. Enter the ‘Control Panel’ and select ‘Administrative Tools’ 
3. Open the ‘Active Directory Users and Computers’ console
4. Locate the user which was configured in the GFI Archiver Mailbox Folder Structure Retrieval
5. Right Click on the user and select ‘Properties’
6. Click on the ‘Account Tab’ and then click on the ‘Log On To…’ button
7. If you have selected the ‘The Following Computers’ option, then enter the computer name of the GFI Archiver server and click on the ‘Add’ Button
8. Click the ‘Ok’ button to save changes

Domain Controller 

If you installed GFI Archiver on a domain controller, by default only Domain Administrators have logon rights on domain controllers. You are able to add a user to the domain controller security policy by performing the following:

Microsoft Windows Server

1. Open the 'Group Policy Manager' from 'Administrative Tools'
2. Expand the 'Forest' > 'Domains' > 'domain.com'
3. Expand the 'Domain Controllers' node
4. Right click on the 'Default Domain Controller Policy' and select 'Edit'
5. Expand 'Computer Configuration' > 'Policies' > 'Windows Settings' > 'Security Settings' > 'Local Policies'
6. Click on 'User Rights Assignment'
7. In the right pane double click on the policy ‘Allow log on locally’
8. Click on the ‘Add User or Group’ and enter the user which you have configured in the GFI Archiver Mailbox Synchronization configuration

• The user does not use a roaming profile
  
  
• Ensure that the user has Full Control rights for the GFI Archiver installation folder. You can do this by performing the following:

1. Open Windows Explorer
2. Browse to and right click on the ‘Archiver’ Folder and select ‘Properties’
3. Click on the ‘Security’ Tab
4. Select a listed user from ‘Group or user names’ or click ‘Add’… to add the user to whom you granted special authority on the GFI Archiver directory
5. In the permissions list, click ‘Allow’ next to ‘Full Control’ to grant full control permissions to the user that you just created

Archiver Access Requirements: 

The following steps provide GFI Archiver with the access requirements for folder structure retrieval

1. You can test that the user is able to access the mailboxes on Microsoft Exchange using Outlook Web Access from the GFI Archiver server. You are able to test this by logging onto a machine using the Mailbox Folder Structure Retrieval user and configuring Microsoft Outlook to open a different mailbox. You are able to do this by performing the following:
   
   
   1. Open Microsoft Outlook with the Mailbox Folder Structure Retrieval user account
   2. Click on ‘Tools’ and select ‘Email Accounts’
   3. Select ‘View or change existing email accounts’ and click on next to proceed
   4. Click on the ‘Change’ button and then select ‘More Settings’ from the next screen
   5. Under the ‘Advanced’ Tab, click on the ‘Add’ button and enter the name of the mailbox you wish to add
   6. Click ‘Ok’ to save your changes
      
      
2. Ensure that no Archive Stores in GFI Archiver are marked as read only. GFI Archiver would need to modify the Archive Store when an email is matched and assign it to the correct folder. To remove the read only attribute on a GFI Archiver Archive Store perform the following:
   1. Open GFI Archiver
   2. Navigate to Configuration > Archive Stores
   3. Click on the 'Edit Settings' Icon near the locked Archive Store
   4. Untick ‘Read-only access’
   5. Click 'Finish' to complete wizard
      
      
3. GFI Archiver will not retrieve the Mailbox Folder structure for a user's mailbox if that user is defined in the GFI Archiver User Exclude Options. You can ensure that a user is not listed in the user exclude options by performing the following:
   
   1. Open the GFI Archiver Configuration
   2. Expand 'Configuration' and click on the 'Archive Restrictions'
   3. If 'Enable Archiving Restriction' is enabled, ensure that the user is not defined in the user exclusion list
      
      
4. When configuring the GFI Archiver Mailbox Folder Structure Retrieval you might encounter the error message 'No Mailboxes found to Synchronize’. For further information, review the following: http://www.gfi.com/support/products/gfi-archiver/KBID003417
   
   
5. If you are running the GFI Archiver services under a user account (this is an unusual setup and not recommended - the services should run under "local system") you need to make sure that the account you are running the services has Full Access permissions granted under Configuration > Roles and Permissions in the GFI Archiver web page
   
   
6. In mixed environments (for example in which mailboxes reside on Exchange 2003 and Exchange 2010) Mailbox Folder Structure Retrieval cannot work correctly against all mailboxes. GFI Archiver can only use one protocol (either MAPI or EWS) at a time, but in this scenario both would be needed.