24.14.PowerShell scripts for setting up Email archive
This section with PowerShell scripts will help you with setting up your Email archive and checking and granting necessary permissions for the superuser.
Permissions for Email archive
The Email archive is using one account (called “superuser” in this section) to connect to the Exchange resources.
The Email archive is accessing Exchange resources through remote PowerShell. It is necessary to enable remote PowerShell on the target Exchange server or Office 365.
There are multiple authentication possibilities when connecting to remote PowerShell:
- Kerberos
- Negotiate
- Digest
- Basic
The example below shows how to allow Basic authentication:
Get-PowerShellVirtualDirectory | fl *auth*
Set-PowerShellVirtualDirectory -Identity “PowerShell (Default Web Site)” -BasicAuthentication $true
Connecting to remote PowerShell
This section will help you with testing the connection to the remote PowerShell. You can use this connection to set up the permissions for the Email archive as well.
The following script prompts for credentials and connects to remote PowerShell. Do not forget to replace the
$UserCredential = Get-Credential
$Session = New-PSSession -ConfigurationName Microsoft.Exchange -ConnectionUri $ExServerPSURL -Credential $UserCredential -Authentication Basic -AllowRedirection
Import-PSSession $Session
If the connection was successful, it will be possible to execute commands. If the connection was not successful, try using other authentication method like Kerberos and check whether the credentials are correct. If the connection is no longer needed, it is highly recommended to close the session:
For more information about how to connect to Exchange using remote PowerShell, please check this page.
Access to resources
The email archive requires access to the following resources:
- Exchange groups and mailboxes
- Public folders (optional)
- Mailbox permissions
- Organization applications
The superuser account requires an active mailbox on the Exchange Server/Office 365 and the permissions included in the following role groups:
- View only organization management
- Public folder management
- Org Marketplace apps
These built-in role groups are allowing access to the complete address book information of Exchange and allowing to install/uninstall Mail apps for the whole organization.
Recommended permissions
For a smoother and more transparent configuration process, we recommend creating a new role group especially for contentACCESS, which will include all the necessary roles. The role group is merely a collection of the necessary permissions. If an account is assigned to this role group, the account automatically receives all permissions necessary for the Email archive.
The following script can be used to create the role group and add members to it:
On-premise Exchange Server
For on-premise Exchange Servers, the superuser requires additional access to the following resources:
- ActiveDirectory users and groups
The connection to the ActiveDirectory is configured in System –> Services -> System, scroll down to section Active Directory integration settings. It is possible to use the same superuser account or use a different account.
This account will connect to the configured domain controller or global catalog to access domain groups and users. The account requires read permission on groups and users. The account should be a member of Domain Administrators. If this is not possible, it is necessary to set up a Security group with the read permissions over the ActiveDirectory objects and add the account to this group.
Office 365 and Hybrid Exchange
These two do not have any special requirements.
Access to mailboxes
The Email archive requires access to mailboxes and optionally public folders.
contentACCESS can archive mailboxes using 2 different methods, both requiring different permissions:
- Delegation
- Impersonation
Delegation
When delegation is used, the superuser account requires full access permission to the archived mailboxes. The Exchange throttling is calculated for the superuser account and this might cause archive performance problems on Office 365.
The full access permission can be granted on individual mailboxes or on Mailbox databases. If permission is granted on individual mailboxes, the newly created mailboxes will not be accessible by the superuser. Therefore, the recommended approach is to set the permissions on mailbox database level (the process needs to be repeated for newly created mailbox databases).
On-premises Exchange Server
The following script grants access to all mailboxes in all mailbox databases:
#Set the permission for the superuser on all mailbox databases:
Get-MailboxDatabase | Add-ADPermission -User
The following script grants access to one specific mailbox:
Add-MailboxPermission -Identity mailbox@domain.com -User
Office 365
The following script grants access to all mailboxes currently available:
#Set the permission for the superuser on all mailboxes:
Get-Mailbox | Add-MailboxPermission -User superuser -AccessRights fullaccess -InheritanceType all
The following script grants access to one specific mailbox:
Add-MailboxPermission -Identity mailbox@domain.com -User superuser -AccessRights FullAccess -InheritanceType All -Automapping $false
Impersonation
Impersonation has multiple benefits:
- if a new user is added to Exchange, the superuser automatically has permissions to it
- it is easy to set up
Impersonation has big impact on Office 365 archiving. It allows to archive more emails/mailboxes, since the throttling is not calculated for one account, but for each archived mailbox individually. Therefore, if multiple mailboxes are archived, the throughput will be higher.
When impersonation is used, the superuser account requires one additional role: ApplicationImpersonation. With this role, the superuser account is able to access all the mailboxes in the organization. The Exchange throttling is calculated for each accessed mailbox individually. This method is recommended when archiving Office 365.
The following script grants ApplicationImpersonation role for the superuser: