How to manually assign management roles
You want to assign only the minimum required management roles to the admin account used to run a migration.
Since CodeTwo migration tools use the Role Based Access Control (RBAC) permission model, we know exactly which roles need to be assigned to admin accounts that are used to connect to the source and target servers using EWS. That way, you don’t have to give these accounts more permissions than necessary. Read on to learn more about:
- the roles used by the software,
- assigning management roles in Exchange 2019/2016/2013/2010 and Exchange Online,
- assigning admin roles in Office 365.
The table below lists all the roles used by the software:
|Mail Recipient Creation||(**)|
|User management role or Global administrator||(***)|
(*) The Public Folders role is optional. You only need to assign it to the admin account if you plan to migrate public folders (applies only to Exchange Server 2013/2016/2019 and Exchange Online).
(**) The Mail Recipient Creation and Mail Recipients roles are optional if you migrate data to existing mailboxes. If you don't have any mailboxes on the target Exchange server and you want the program to create them, you need to assign these roles to the admin account.
(***) The User management administrator / Global administrator role is also optional if you don't need the program to create new mailboxes on your target Office 365 server.
So, for example, if you want to connect to a target on-premises Exchange server, the used admin account must be assigned the following roles: ApplicationImpersonation, View-Only Recipients, View-Only Configuration, and Mail Recipient Creation.
No matter if are using an existing account or creating a new one, it must fulfill these requirements:
- AD user account must be active with UPN address assigned,
- the account must be mailbox-enabled in Exchange.
Get-ManagementRoleAssignment -Role "<RoleName>"
where instead of <RoleName> you need to provide the name of the role, e.g. ApplicationImpersonation. This cmdlet will list all the users assigned the ApplicationImpersonation role.
To assign the management roles manually, you need to either use Exchange Management Shell (for on-premises environments), or connect to Exchange Online remotely (see this article to learn how to do that).
You need to be logged in as an administrator who belongs to the Organization Management role group to be able to use the cmdlets specified below.
Run Exchange Management Shell and type the following cmdlet:
New-ManagementRoleAssignment -Role "<RoleName>" -User "<UserName>"
where instead of <RoleName> you need to enter a specific role, as provided in the table above, and instead of <UserName> – a valid name or alias of your AD user. For example, if you want to assign the View-Only Configuration role to user Anna White, use the following cmdlet:
New-ManagementRoleAssignment -Role "View-Only Configuration" -User "Anna White"
You can check if the assignment was successful via the following cmdlet:
Get-ManagementRoleAssignment -RoleAssignee "<UserName>"
You can also use this cmdlet to see all the roles assigned to any user. By default, each Exchange user is assigned some roles that begin with My*. They simply allow users to manage their mailboxes.
Additionally, the User management administrator or Global administrator roles can be assigned either in the Microsoft 365 admin center (Office 365 admin center) or via PowerShell (check our blog entry for more information on how to connect and remotely manage Office 365).
- Log in to Microsoft 365 admin center.
- On the Home page, click Users.
- From Active users select the user to whom you want to assign an administrator role.
On the page that opens, click Edit in the Roles row (Fig. 1.).
Select either Global administrator or click the Customized administrator option first and then select User management administrator (Fig. 2.).
- Click Save when finished.
PowerShell and the Office 365 use different names for the admin roles. When you're assigning admin role in PowerShell, remember to use the appropriate name (see the table below).
|Microsoft 365 admin center||PowerShell|
|User management administrator||User account administrator|
|Global administrator||Company administrator|
To assign an admin role to a user, type the following cmdlet:
Add-MsolRoleMember -RoleName "<AdminRoleName>" -RoleMemberEmailAddress "<UserUPN>"
where instead of <AdminRoleName> you need to enter the name of the admin role as it is used in PowerShell, and instead of <UserUPN> provide the name of a system user in an email address format. So if you want to assign the User management administrator role to Anna White, whose UPN is firstname.lastname@example.org, use the following cmdlet:
Add-MsolRoleMember -RoleName "User account administrator" -RoleMemberEmailAddress "email@example.com"
To verify the assignment, or check which admin role is assigned to your user, enter the following cmdlet:
Get-MsolUserRole -UserPrincipalName "<UserUPN>"