Manage role groups in Exchange Server
A management role group is a universal security group (USG) used in the Role Based Access Control (RBAC) permissions model in Exchange Server. A management role group simplifies the assignment of management roles to a group of users. All members of a role group are assigned the same set of roles. For more information about role groups in Exchange Server, see Understanding Management Role Groups.
For additional management tasks related to role groups, see Permissions.
Estimated time to complete each procedure: 5 to 10 minutes
To open the EAC, see Exchange admin center in Exchange Server. To open the Exchange Management Shell, see Open the Exchange Management Shell.
You need to be assigned permissions before you can perform this procedure or procedures. To see what permissions you need, see the "Role groups" entry in the Role management permissions topic.
For information about keyboard shortcuts that may apply to the procedures in this topic, see Keyboard shortcuts in the Exchange admin center.
Tip
Having problems? Ask for help in the Exchange forums. Visit the forums at: Exchange Server, Exchange Online, or Exchange Online Protection.
If you want to customize the permissions that you can assign to a group of users, create a new custom management role group.
In the Exchange admin center (EAC), navigate to Permissions > Admin Roles and then click Add .
In the New role group window, provide a name for the new role group.
You can either select the roles that you want to be assigned to the role group and the members you want to be added to the role group now, or you can do this at another time.
Select the write scope that you want to apply to the new role group.
Click Save to create the role group.
To create a role group, see the Examples section in New-RoleGroup.
To verify that you have successfully created a role group, do the following:
In the EAC, navigate to Permissions > Admin Roles.
Verify that the new role group appears in the role group list and then select it.
Verify that members, assigned roles, and scope that you specified on the new role group are listed in the role group details pane.
If you have a role group that contains the permissions you want to grant to users, but you want to apply a different management scope, or remove or add one or two management roles without having to add all the other roles manually, you can copy the existing role group.
Important
You can't use the EAC to copy a role group if you've used the Exchange Management Shell to configure multiple management role scopes or exclusive scopes on the role group. If you've configured multiple scopes or exclusive scopes on the role group, you must use the Exchange Management Shell procedures later in this topic to copy the role group. For more information about management role scopes, see Understanding Management Role Scopes.
In the EAC, navigate to Permissions > Admin Roles.
Select the role group you want to copy and then click Copy .
In the New role group window, provide a name for the new role group.
Review the roles that have been copied to the new role group. Add or remove roles as necessary.
Review the write scope, and change it as necessary.
Review the members that have been copied to the new role group. Add or remove members as necessary.
Click Save to create the role group.
Store the role group that you want to copy in a variable using the following syntax.
$RoleGroup = Get-RoleGroup <name of role group to copy>
Create the new role group, and also add members to the role group and specify who can delegate the new role group to other users, using the following syntax.
New-RoleGroup <name of new role group> -Roles $RoleGroup.Roles -Members <member1, member2, member3...> -ManagedBy <user1, user2, user3...>
For example, the following commands copy the Organization Management role group, and name the new role group "Limited Organization Management". It adds the members Isabelle, Carter, and Lukas and can be delegated by Jenny and Katie.
$RoleGroup = Get-RoleGroup "Organization Management" New-RoleGroup "Limited Organization Management" -Roles $RoleGroup.Roles -Members Isabelle, Carter, Lukas -ManagedBy Jenny, Katie
After the new role group is created, you can add or remove roles, change the scope of role assignments on the role, and more.
For detailed syntax and parameter information, see Get-RoleGroup and New-RoleGroup.
Store the role group that you want to copy in a variable using the following syntax.
$RoleGroup = Get-RoleGroup <name of role group to copy>
Create the new role group with a custom scope using the following syntax.
New-RoleGroup <name of new role group> -Roles $RoleGroup.Roles -CustomRecipientWriteScope <recipient scope name> -CustomConfigWriteScope <configuration scope name>
For example, the following commands copy the Organization Management role group and create a new role group called Vancouver Organization Management with the Vancouver Users recipient scope and Vancouver Servers configuration scope.
$RoleGroup = Get-RoleGroup "Organization Management"
New-RoleGroup "Vancouver Organization Management" -Roles $RoleGroup.Roles -CustomRecipientWriteScope "Vancouver Users" -CustomConfigWriteScope "Vancouver Servers"
You can also add members to the role group when you create it by using the Members parameter as shown in Use the Exchange Management Shell to create a role assignment with no scope earlier in this topic. For more information about management scopes, see Understanding Management Scopes.
After the new role group is created, you can add or remove roles, change the scope of role assignments on the role, and perform other tasks.
For detailed syntax and parameter information, see Get-RoleGroup and New-RoleGroup.
Store the role group that you want to copy in a variable using the following syntax.
$RoleGroup = Get-RoleGroup <name of role group to copy>
Create the new role group with a custom scope using the following syntax.
New-RoleGroup <name of new role group> -Roles $RoleGroup.Roles -RecipientOrganizationalUnitScope <OU name>
For example, the following commands copy the Recipient Management role group and create a new role group called Toronto Recipient Management that allows management of only users in the Toronto Users OU.
$RoleGroup = Get-RoleGroup "Recipient Management"
New-RoleGroup "Toronto Recipient Management" -Roles $RoleGroup.Roles -RecipientOrganizationalUnitScope "contoso.com/Toronto Users"
You can also add members to the role group when you create it by using the Members parameter as shown in Use the Exchange Management Shell to create a role assignment with no scope earlier in this topic. For more information about management scopes, see Understanding Management Scopes.
After the new role group is created, you can add or remove roles, change the scope of role assignments on the role, and more.
For detailed syntax and parameter information, see Get-RoleGroup and New-RoleGroup.
To verify that you have successfully copied a role group, do the following:
In the EAC, navigate to Permissions > Admin Roles.
Verify that the copied role group appears in the role group list, and then select it.
Verify that members, assigned roles, and scope that you specified on the copied role group are listed in the role group details pane.
If you no longer need a role group you created, you can remove it. When you remove a role group, the management role assignments between the role group and the management roles are deleted. The management roles aren't deleted. If a user depended on the role group for access to a feature, the user will no longer have access to the feature. You can't remove built-in role groups.
In the EAC, navigate to Permissions > Admin Roles.
Select the role group you want to remove and then click Delete .
Verify that you want to remove the selected role group, and if so, respond Yes to the warning.
To remove a role group, see the Examples section in Remove-RoleGroup.
You can view either a list of role groups or the detailed information about a specific role group that exists in your organization.
In the EAC, navigate to Permissions > Admin Roles. All of the role groups in your organization are listed here.
Select a role group to view the members, assigned roles, and scope that are configured on the role group.
To view a list of role groups, see the Examples section in Get-RoleGroup.
Adding a management role to a role group is the best and simplest way to grant permissions to a group of administrators or specialist users. If you want to give users that are members of a role group the ability to manage a feature, you add the management role that manages the feature to the role group. After the role is added, the members of the role group are granted the permissions provided by the role.
Important
You can't use the EAC to add roles to a role group if you've used the Exchange Management Shell to configure multiple management role scopes or exclusive scopes on the role group. If you've configured multiple scopes or exclusive scopes on the role group, you must use the Exchange Management Shell procedures later in this topic to add roles to the role group. For more information about management role scopes, see Understanding Management Role Scopes.
In the EAC, navigate to Permissions > Admin Roles.
Select the role group you want to add a role to, and then click Edit .
In the Roles section, select the roles you want to add to the role group.
When you've finished adding roles to the role group, click Save.
You can create a role assignment with no scope between a role and a role group. When you do this, the implicit read and implicit write scopes of the role apply.
Use the following syntax to assign a role without any scope to a role group. A role assignment name is created automatically if you don't specify one.
New-ManagementRoleAssignment -SecurityGroup <role group name> -Role <role name>
This example assigns the Transport Rules management role to the Seattle Compliance role group.
New-ManagementRoleAssignment -SecurityGroup "Seattle Compliance" -Role "Transport Rules"
For detailed syntax and parameter information, see New-ManagementRoleAssignment.
If a predefined scope meets your business requirements, you can apply that scope to the role assignment rather than create a new one. For a list of predefined scopes and their descriptions, see Understanding Management Role Scopes.
For more information about role assignments, see Understanding Management Role Assignments.
Use the following syntax to assign a role to a role group with a predefined scope. A role assignment name is created automatically if you don't specify one.
New-ManagementRoleAssignment -SecurityGroup <role group name> -Role <role name> -RecipientRelativeWriteScope < MyGAL | MyDistributionGroups | Organization | Self >
This example assigns the Message Tracking role to the Enterprise Support role group and applies the Organization predefined scope.
New-ManagementRoleAssignment -SecurityGroup "Enterprise Support" -Role "Message Tracking" -RecipientRelativeWriteScope Organization
For detailed syntax and parameter information, see New-ManagementRoleAssignment.
If you created a recipient filter-based scope, you need to include the scope in the command used to assign the role to a role group by using the CustomRecipientWriteScope parameter.
You can also include a configuration write scope when you create a role assignment that has a recipient write scope.
For more information about role assignments and scopes, see the following topics:
Use the following syntax to assign a role to a role group with a recipient filter-based scope. A role assignment name is created automatically if you don't specify one.
New-ManagementRoleAssignment -SecurityGroup <role group name> -Role <role name> -CustomRecipientWriteScope <role scope name>
This example assigns the Message Tracking role to the Seattle Recipient Admins role group and applies the Seattle Recipients scope.
New-ManagementRoleAssignment -SecurityGroup "Seattle Recipient Admins" -Role "Message Tracking" -CustomRecipientWriteScope "Seattle Recipients"
For detailed syntax and parameter information, see New-ManagementRoleAssignment.
If you created a server or database configuration filter or list-based scope, you need to include the scope in the command used to assign the role to a role group by using the CustomConfigWriteScope parameter.
You can also include a recipient write scope when you create a role assignment that has a configuration write scope.
For more information about role assignments and management scopes, see the following topics:
Use the following syntax to assign a role to a role group with a configuration scope. A role assignment name is created automatically if you don't specify one.
New-ManagementRoleAssignment -SecurityGroup <role group name> -Role <role name> -CustomConfigWriteScope <role scope name>
This example assigns the Databases role to the Seattle Server Admins role group and applies the Seattle Servers scope.
New-ManagementRoleAssignment -SecurityGroup "Seattle Server Admins" -Role "Databases" -CustomConfigWriteScope "Seattle Servers"
For detailed syntax and parameter information, see New-ManagementRoleAssignment.
If you want to scope a role's write scope to an OU, you can specify the OU in the RecipientOrganizationalUnitScope parameter directly.
For more information about role assignments and management scopes, see the following topics:
Use the following command to assign a role to a role group and restrict the write scope of a role to a specific OU. A role assignment name is created automatically if you don't specify one.
New-ManagementRoleAssignment -SecurityGroup <role group name> -Role <role name> -RecipientOrganizationalUnitScope <OU>
This example assigns the Mail Recipients role to the Seattle Recipient Admins role group and scopes the assignment to the Sales\Users OU in the Contoso.com domain.
New-ManagementRoleAssignment -SecurityGroup "Seattle Recipient Admins" -Role "Mail Recipients" -RecipientOrganizationalUnitScope contoso.com/sales/users
For detailed syntax and parameter information, see New-ManagementRoleAssignment.
To verify that you have successfully added roles to a role group, do the following:
In the EAC, navigate to Permissions > Admin Roles.
Select the role group you added roles to. In the role group details pane, verify that the roles that you added are listed.
Removing a role from a management role group is the best and simplest way to revoke permissions granted to a group of administrators or specialist users. If you don't want administrators or specialist users to have permissions to manage a feature, you remove the management role from the management role group that manages the permissions. After the role is removed, the members of the role group will no longer have permissions to manage the feature.
Note
Some role groups, such as the Organization Management role group, restrict what roles can be removed from a role group. For more information, see Understanding Management Role Groups. > If an administrator is a member of another role group that contains management roles that grants permissions to manage the feature, you need to either remove the administrator from the other role groups, or remove the role that grants permissions to manage the feature from the other role groups.
Important
You can't use the EAC to remove roles from a role group if you've used the Exchange Management Shell to configure multiple scopes or exclusive scopes on the role group. If you've configured multiple scopes or exclusive scopes on the role group, you must use the Exchange Management Shell procedures later in this topic to remove roles from the role group. For more information about management role scopes, see Understanding Management Role Scopes.
In the EAC, navigate to Permissions > Admin Roles.
Select the role group you want to remove a role from, and then click Edit .
In the Roles section, select the roles you want to remove from the role group.
When you've finished removing roles from the role group, click Save.
You can remove roles from role groups by retrieving the associated management role assignment using the Get-ManagementRoleAssignment cmdlet and then piping the role assignment returned to the Remove-ManagementRoleAssignment cmdlet. Unless you want to remove both delegating and regular role assignments at the same time, specify the Delegating parameter to specify whether you want to remove regular or delegating role assignments.
For more information about regular and delegating role assignments, see Understanding Management Role Assignments.
This procedure uses pipelining. For more information about pipelining, see about_Pipelines.
To remove a role from a role group, use the following syntax.
Get-ManagementRoleAssignment -RoleAssignee <role group name> -Role <role name> -Delegating <$true | $false> | Remove-ManagementRoleAssignment
This example removes the Distribution Groups role, which enables administrators to manage distribution groups, from the Seattle Recipient Administrators role group. Because we want to remove the role assignment that provides permissions to manage distribution groups, the Delegating parameter is set to $False
, which returns only regular role assignments.
Get-ManagementRoleAssignment -RoleAssignee "Seattle Recipient Administrators" -Role "Distribution Groups" -Delegating $false | Remove-ManagementRoleAssignment
For detailed syntax and parameter information, see Remove-ManagementRoleAssignment.
To verify that you have successfully removed roles from a role group, do the following:
In the EAC, navigate to Permissions > Admin Roles.
Select the role group you removed roles from. In the role group details pane, verify that the roles that you removed are no longer listed.
The management role assignments between a role group and a role contain management scopes, which determine what objects are made available to members of that role group. By changing the write scope on a role group, you can change what objects are made available to role group members to create, change, or remove. You can't change the read scope on a role group.
Exchange Server includes scopes that are applied by default to role assignments when no custom scopes are created. If you want to use a custom scope with a role assignment on a role group, you must create one first. For more information about creating custom scopes, which is an advanced task, see Create a Regular or Exclusive Scope.
For more information about management role scopes and assignments in Exchange Server, see the following topics:
When you use the EAC to change the scope on a role group, you're actually changing the scope on all the role assignments between the role group and each of the management roles assigned to the role group. If you want to change the scope on specific role assignments, you must use the Exchange Management Shell procedures later in this topic.
Important
You can't use the EAC to manage scopes on role assignments between roles and a role group if you've used the Exchange Management Shell to configure multiple scopes or exclusive scopes on those role assignments. If you've configured multiple scopes or exclusive scopes on those role assignments, you must use the Exchange Management Shell procedures later in this topic to manage scopes. For more information about management role scopes, see Understanding Management Role Scopes.
In the EAC, navigate to Permissions > Admin Roles.
Select the role group you want to change the scope on, and then click Edit .
Select one of the two following Write scope options:
A write scope from the drop-down box, where you can select either the default write scope or a custom write scope.
Organizational unit: Select this option and provide an organizational unit (OU) if you want to scope this role group to an OU.
Click Save to save the changes to the role group.
Use the Exchange Management Shell to change the scope of all role assignments on a role group at the same time
Role assignments between the role group and the roles assigned to it can use the implicit scope obtained from the roles themselves, the same custom scope, or different custom scopes. For more information about role assignments, see Understanding Management Role Assignments.
The scopes on the role assignments are managed using the Set-ManagementRoleAssignment cmdlet. You can't manage scopes using the Set-RoleGroup cmdlet.
To change the scope of all the role assignments between a role group and a set of management roles at the same time, you need to first retrieve the role assignments on the role group, and then set the new scope on each of the assignments. You can do this by using the Get-ManagementRoleAssignment cmdlet to retrieve the role assignments, and then pipe them to the Set-ManagementRoleAssignment cmdlet.
This procedure uses the concepts of pipelining and the WhatIf switch. For more information, see the following topics:
To set the scope on all of the role assignments on a role group at the same time, use the following syntax.
Get-ManagementRoleAssignment -RoleAssignee <name of role group> | Set-ManagementRoleAssignment -CustomRecipientWriteScope <recipient scope name> -CustomConfigWriteScope <configuration scope name> -RecipientRelativeScopeWriteScope < MyDistributionGroups | Organization | Self> -ExclusiveRecipientWriteScope <exclusive recipient scope name> -ExclusiveConfigWriteScope <exclusive configuration scope name> -RecipientOrganizationalUnitScope <organizational unit>
You use only the parameters you need to configure the scope you want to use. For example, if you want to change the recipient scope for all role assignments on the Sales Recipient Management role group to Direct Sales Employees, use the following command.
Get-ManagementRoleAssignment -RoleAssignee "Sales Recipient Management" | Set-ManagementRoleAssignment -CustomRecipientWriteScope "Direct Sales Employees"
Note
You can use the WhatIf switch to verify that only the role assignments you want to change are changed. Run the preceding command with the WhatIf switch to verify the results, and then remove the WhatIf switch to apply the changes.
For more information about changing management role assignments, see Change a Role Assignment.
For detailed syntax and parameter information, see Get-ManagementRoleAssignment.
Use the Exchange Management Shell to change the scope of individual role assignments on a role group
Role assignments between the role group and the roles assigned to it can use the implicit scope obtained from the roles themselves, the same custom scope, or different custom scopes. For more information about role assignments, see Understanding Management Role Assignments.
The scopes on the role assignments are managed using the Set-ManagementRoleAssignment cmdlet. You can't manage scopes using the Set-RoleGroup cmdlet.
This procedure uses the concepts of pipelining and the Format-List cmdlet. For more information, see the following topics:
To change the scope on a role assignment between a role group and a management role, you first find the name of the role assignment, and then set the scope on the role assignment.
To find the names of all the role assignments on a role group, use the following command. By piping the management role assignments to the Format-List cmdlet, you can view the full name of the assignment.
Get-ManagementRoleAssignment -RoleAssignee <role group name> | Format-List Name
Find the name of the role assignment you want to change. Use the name of the role assignment in the next step.
To set the scope on an individual assignment, use the following syntax.
Set-ManagementRoleAssignment <role assignment name> -CustomRecipientWriteScope <recipient scope name> -CustomConfigWriteScope <configuration scope name> -RecipientRelativeScopeWriteScope < MyDistributionGroups | Organization | Self> -ExclusiveRecipientWriteScope <exclusive recipient scope name> -ExclusiveConfigWriteScope <exclusive configuration scope name> -RecipientOrganizationalUnitScope <organizational unit>
You use only the parameters you need to configure the scope you want to use. For example, if you want to change the recipient scope for the Mail Recipients_Sales Recipient Management role assignment to All Sales Employees, use the following command.
Set-ManagementRoleAssignment "Mail Recipients_Sales Recipient Management" -CustomRecipientWriteScope "All Sales Employees"
For more information about changing management role assignments, see Change a Role Assignment.
For detailed syntax and parameter information, see Set-ManagementRoleAssignment.
To verify that you have successfully changed the scope of a role assignment on a role group, do the following:
If you used the EAC to configure the scope on the role group, do the following:
In the EAC, navigate to Permissions> Admin Roles. All the role groups in your organization are listed here.
Select a role group to view the scope that's configured on the role group.
If you used the Exchange Management Shell to configure the scope on the role group, do the following:
Run the following command in the Exchange Management Shell.
Get-ManagementRoleAssignment -RoleAssignee <role group name> | Format-Table *WriteScope
Verify that the write scope on the role assignments has been changed to the scope you specified.
Role group delegates are users or universal security groups (USGs) that can add or remove members from a role group or change the properties of a role group. By adding or removing role group delegates, you can control who is allowed to manage a role group.
Important
After you add a delegate to a role group, the role group can only be managed by the delegates on the role group, or by users who are assigned, either directly or indirectly, the Role Management management role. > If a user is assigned, either directly or indirectly, the Role Management role and isn't added as a delegate of the role group, the user must use the BypassSecurityGroupManagerCheck switch on the Add-RoleGroupMember, Remove-RoleGroupMember, Update-RoleGroupMember, and Set-RoleGroup cmdlets to manage a role group.
Note
You can't use the EAC to add a delegate to a role group.
To change the list of delegates on a role group, you use the ManagedBy parameter on the Set-RoleGroup cmdlet. The ManagedBy parameter overwrites the entire delegate list on the role group. If you want to add delegates to the role group rather than replace the entire list of delegates, use the following steps:
Store the role group in a variable using the following command.
$RoleGroup = Get-RoleGroup <role group name>
Add the delegate to the role group stored in the variable using the following command.
$RoleGroup.ManagedBy += (Get-User <user to add>).Identity
Note
Use the Get-Group cmdlet if you want to add a USG.
Repeat Step 2 for each delegate you want to add.
Apply the new list of delegates to the actual role group using the following command.
Set-RoleGroup <role group name> -ManagedBy $RoleGroup.ManagedBy
This example adds the user David Strome as a delegate on the Organization Management role group.
$RoleGroup = Get-RoleGroup "Organization Management"
$RoleGroup.ManagedBy += (Get-User "David Strome").Identity
Set-RoleGroup "Organization Management" -ManagedBy $RoleGroup.ManagedBy
For detailed syntax and parameter information, see Set-RoleGroup.
To change the list of delegates on a role group, you use the ManagedBy parameter on the Set-RoleGroup cmdlet. The ManagedBy parameter overwrites the entire delegate list on the role group. If you want to remove delegates from the role group rather than replace the entire list of delegates, use the following steps:
Store the role group in a variable using the following command.
$RoleGroup = Get-RoleGroup <role group name>
Remove the delegate from the role group stored in the variable using the following command.
$RoleGroup.ManagedBy -= (Get-User <user to remove>).Identity
Note
Use the Get-Group cmdlet if you want to remove a USG.
Repeat Step 2 for each delegate you want to remove.
Apply the new list of delegates to the actual role group using the following command.
Set-RoleGroup <role group name> -ManagedBy $RoleGroup.ManagedBy
This example removes the user David Strome as a delegate on the Organization Management role group.
$RoleGroup = Get-RoleGroup "Organization Management"
$RoleGroup.ManagedBy -= (Get-User "David Strome").Identity
Set-RoleGroup "Organization Management" -ManagedBy $RoleGroup.ManagedBy
For detailed syntax and parameter information, see Set-RoleGroup.
To verify that you have successfully changed the delegate list on a role group, do the following:
In the Exchange Management Shell, run the following command.
Get-RoleGroup <role group name> | Format-List ManagedBy
Verify that the delegates listed on the ManagedBy property include only the delegates that should be able to manage the role group.