CodeTwo Base.title

Create RBAC-compliant account for CodeTwo Software


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.


The CodeTwo software listed on the right (in the Applies to section) requires credentials to a user account on the target Exchange Server that meets the following criteria:

  • AD user account is active with 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 Target server 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.

You may ignore the wizard failure and start using the software, if you are sure that the account you configured the connection with meets all the requirements above.

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. In your Exchange on-premises, start the ems Exchange Management Shell or - in a similar way as with Exchange Online (Office 365) - connect to it remotely.
  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.

    • In Exchange on-premises (2010, 2013, 2016):
      Get-ManagementRoleEntry "c2role\*" | Where-Object {($_.Name -ne "Get-Mailbox") -and ($_.Name -notlike "*ManagementRoleAssignment")} | Remove-ManagementRoleEntry
    • In Exchange Online (Office 365):
      Get-ManagementRoleEntry "c2role\*" | Where-Object {($_.Name -ne "Get-Mailbox") -and ($_.Name -notlike "*ManagementRoleAssignment")} | Foreach-Object {Remove-ManagementRoleEntry -Identity "$($_.Role)\$($_.Name)" -Confirm:$False}
    • WARNING! When configured for Exchange Online (Office 365), CodeTwo Out of Office Manager and CodeTwo Email Signatures for Email Clients require additional permissions to run the Get-User cmdlet. Please use the following cmdlet instead:
      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, the CodeTwo software also requires the ApplicationImpersonation rights. This is a separate administrative role that includes only one cmdlet, so you do not need to create a new tailored child role. Simply assign your user to this role.
    New-ManagementRoleAssignment –Name "c2assignment2" –Role "ApplicationImpersonation" –User "c2user"
  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.

See also:

Our Clients: