Create an RBAC-compliant account for CodeTwo Software

Problem:

You need your CodeTwo software to use the credentials of an account that has only the minimum required permissions, following the Role Based Access Control (RBAC) approach.

Solution:

To connect to your on-premises Exchange server in CodeTwo software listed below this article (in the Related products section), you need to provide credentials of a user account from that server. This account needs to meet the following criteria: 

• the AD user account is active and has UPN address assigned,
• the account is mailbox-enabled in Exchange,
• the account is assigned the ApplicationImpersonation role in Exchange,
• the account is assigned any role that can execute the Get-Mailbox cmdlet for all users.

These criteria are the absolute minimum. However, providing the credentials of an account that meets only the above-listed requirements will cause the software's Exchange connection wizard to fail. This is because the wizard attempts to execute additional PowerShell cmdlets to self-check if the ApplicationImpersonation role has been assigned to it already, removes the old assignment if there is one, and attempts to create a new assignment.

However, if for some reason you need the wizard to finish the connection with no failures (with all checks green), the target account must not only meet the requirements above, but you also have to assign it to any role that has rights to execute the following cmdlets: Get-ManagementRoleAssignment, New-ManagementRoleAssignment, Remove-ManagementRoleAssignment. The role named Role Management is probably the best choice. You can either use an account that is a member of the Organization Management group or is assigned to Role Management.

How to create an account with minimum required permissions

The steps below explain how to create an account that meets the CodeTwo software requirements and is assigned only the absolutely necessary permissions. In this instruction some exemplary names are used (e.g. c2role, c2user, c2assignment1, c2assignment2). You can customize them to suit your needs.

1. Create a new user in your Active Directory and make sure you assign a UPN address and create a mailbox for this user. In the case of Exchange Online, you must also make sure the account has been assigned a license.
2. Start the  Exchange Management Shell.
3. Create a new role that would be a child of Role Management. It must be this particular role so you have access to all the required cmdlets. Make sure to create a new, child role and not a direct assignment of this role, so you can remove any unnecessary cmdlets for security purposes.

   New-ManagementRole -Parent "Role Management" -Name "c2role"

4. Run the following cmdlet to remove all unnecessary cmdlets from your newly created child role. This is to ensure the security of your environment - the account used on the target server should have access only to the cmdlets it actually needs.

   Get-ManagementRoleEntry "c2role\*" | Where-Object {($_.Name -ne "Get-Mailbox") -and ($_.Name -notlike "*ManagementRoleAssignment")} | Remove-ManagementRoleEntry
   

   Older products

   If you configure CodeTwo Out of Office Manager or CodeTwo Email Signatures for Email Clients (both of which are now discontinued) for Exchange Online (Office 365), you need to assign the Get-User execution rights instead of Get-Mailbox rights. So, instead of the cmdlet above, use the following cmdlet:

   Get-ManagementRoleEntry "c2role\*" | Where-Object {($_.Name -ne "Get-Mailbox") -and ($_.Name -ne "Get-User") -and ($_.Name -notlike "*ManagementRoleAssignment")} | Foreach-Object {Remove-ManagementRoleEntry -Identity "$($_.Role)\$($_.Name)" -Confirm:$False}

5. Run this cmdlet to confirm that after successful execution of the previous commands your new custom role includes only the cmdlets related to ManagementRoleAssignment and Get-Mailbox.

   Get-ManagementRoleEntry "c2role\*"

6. Now assign your desired user account to this custom role.

   New-ManagementRoleAssignment -Name "c2assignment1" -Role "c2role" -User "c2user"

7. As mentioned before, you also need to assign the ApplicationImpersonation role to the user. This is a separate management role that includes only one cmdlet, so you don't have to create a new tailored child role. If you want the user to be able to impersonate all users in your organization, use the following cmdlet:

   New-ManagementRoleAssignment -Name "c2assignment2" -Role "ApplicationImpersonation" -User "c2user"

   However, if you want to limit the number of users that can be impersonated to a specific distribution group (e.g. c2group), you first need to define a custom management scope that will only include users belonging to that group.

   $DistGroup = Get-DistributionGroup -Identity "c2group"
   New-ManagementScope "C2 Distribution Group" -RecipientRestrictionFilter "MemberOfGroup -eq '$($DistGroup.DistinguishedName)'"
   

   Having done so, use the following cmdlet to assign the ApplicationImpersonation role again. This time, the user assigned this role will only be able to manage the specified scope of users.

   New-ManagementRoleAssignment -Name "c2assignment2" -Role "ApplicationImpersonation" -User "c2user" -CustomRecipientWriteScope "C2 Distribution Group"

8. You can see all roles assigned to your user by running the following cmdlet:

   Get-ManagementRoleAssignment -RoleAssignee "c2user"

9. You will notice that apart from your newly created c2assignments, there are some others whose names start with "My*". Those are the roles which are assigned automatically when a mailbox is created in Exchange, following your Default Role Assignment Policy (assuming you are using the default settings; it may look differently in environments with already customized policies). It is not possible to manually remove those roles. In Exchange Server on-premises, however, it is possible to simply remove the aforementioned policy assignment. This step is not required but the default policy assigns roles that allow, for example, logging in to OWA. Some organizations require such permissions to be revoked for service accounts. If you run the cmdlet below, all policy assignments will be removed for your user.

   Set-Mailbox "c2user" -RoleAssignmentPolicy $null

   In the case of Exchange Online (Office 365), every mailbox must always be assigned to one policy and therefore the cmdlet above will not work. You might want to check this article to find out how to work with role assignment policies in Office 365.