Role assignment policies in Exchange Online

A role assignment policy is a collection of one or more end-user roles that enable users to manage their mailbox settings and distribution groups in Exchange Online. End-users roles are part of the role based access control (RBAC) permissions model in Exchange Online. You can assign different role assignment policies to different users to allow or prevent specific self-management features in Exchange Online.

In Exchange Online, a default role assignment policy named Default Role Assignment Policy is specified by the mailbox plan that's assigned to users when their account is licensed. For more information about mailbox plans, see Mailbox plans in Exchange Online.

Role assignment policies are how end-user roles (as opposed to management roles) are assigned to users in Exchange Online. There are several ways you can use role assignment policies to assign permissions to users:

• New users:

  • Change the end-user roles that are assigned to the default role assignment policy.
  • Create a custom role assignment policy and set it as the default. Note that this method only affects mailboxes that you create without specifying a role assignment policy or assigning a license (the license specifies the mailbox plan, which specifies the role assignment policy).
  • Specify a custom role assignment policy in the mailbox plan. For more information, see Use Exchange Online PowerShell to modify mailbox plans.

• Existing users:

  • Assign a different license to the user. This will apply the settings of the different mailbox plan, which specifies the role assignment policy to apply.
  • Manually assign a custom role assignment policy to mailboxes.

The available end-user roles that you can assign to mailbox plans are described in the following table:

^*This feature isn't available in all regions or organizations.

What do you need to know before you begin?

• Estimated time to complete each procedure: less than 5 minutes.

• The procedures in this topic require the Role Management RBAC role in Exchange Online. Typically, you get this permission via membership in the Organization Management role group. For more information, see Manage role groups in Exchange Online.

• To open the Exchange admin center (EAC), see Exchange admin center in Exchange Online. To connect to Exchange Online PowerShell, see Connect to Exchange Online PowerShell.

• Changes to permissions take effect after the user logs out and logs in again.

View roles assigned to a role assignment policy

Use the EAC to view roles assigned to a role assignment policy

1. In the EAC, click Roles > Admin roles. All of the role groups in your organization are listed here.

2. Select a role group. The details pane shows the Name, Description, and add the Permissions of the role group.

Use Exchange Online PowerShell to view roles assigned to a role assignment policy

To view the roles assigned to a role assignment policy, use the following syntax:

Get-ManagementRoleAssignment -RoleAssignee "<RoleAssignmentPolicyName>" | Format-Table Name,Role -Auto

This example returns the roles that are assigned to the policy named Default Role Assignment Policy.

Get-ManagementRoleAssignment -RoleAssignee "Default Role Assignment Policy" | Format-Table Name,Role -Auto

For detailed syntax and parameter information, see Get-ManagementRoleAssignment.

Note: To return a list of all available end-user roles, run the following command:

Get-ManagementRole | Where {$_.IsEndUserRole -eq $true} | Format-Table Name,Parent

Add or remove roles from a role assignment policy

Use the EAC to add or remove roles from a role assignment policy

1. In the EAC, click Roles > User roles, select the role assignment policy, and then click Edit .

2. In the policy properties window that opens, do one of the following steps:

   • To add a role, select the check box next to the role.

   • To remove a role that's already assigned, clear the check box.

   If you select a check box for a role that has child roles, the check boxes for the child roles are also selected. If you clear the check box of the parent role, the check boxes for the child roles are also cleared. You can select a child role by clearing the check box of the parent role and then selecting the individual child role.

3. When you're finished, click Save.

Use Exchange Online PowerShell to add roles to a role assignment policy

Adding a role to a role assignment policy creates a new role assignment with a unique name that's a combination of the names of the role and the role assignment policy.

To add roles to a role assignment policy, use the following syntax:

New-ManagementRoleAssignment -Role <RoleName> -Policy "<RoleAssignmentPolicyName>"

This example adds the role MyMailboxDelegation to the role assignment policy named Default Role Assignment Policy.

New-ManagementRoleAssignment -Role MyMailboxDelegation -Policy "Default Role Assignment Policy"

For detailed syntax and parameter information, see New-ManagementRoleAssignment.

Use Exchange Online PowerShell to remove roles from a role assignment policy

1. Use the procedure from the Use Exchange Online PowerShell to view roles assigned to a role assignment policy section earlier in this topic to find the name of the role assignment for the role that you want to remove (it's a combination of the names of the role and the role assignment policy).

2. To remove the role from the role assignment policy, use this syntax:

   Remove-ManagementRoleAssignment -Identity "<RoleAssignmentName>"
   

   This example removes the MyDistributionGroups role from the role assignment policy named Default Role Assignment Policy.

   Remove-ManagementRoleAssignment -Identity "MyDistributionGroups-Default Role Assignment Policy"
   

For detailed syntax and parameter information, see Remove-ManagementRoleAssignment.

Create role assignment policies

Use the EAC to create role assignment policies

1. In the EAC, go to Roles > Admin roles and then click Add role group.

2. In the Add role group window, click Set up the basics section, configure the following settings and click Next:

   • Name: Enter a unique name for the role group.

   • Description: Enter an optional description for the role group.

   • Select the roles that you want to assign to the policy.

3. In the Add permissions section, select the roles and click Next. Roles define the scope of the tasks that the members assigned to this role group have permission to manage.

4. In the Assign admins section, select the users to assign to this role group and click Next. They'll have permissions to manage the roles that you assigned.

5. In the Review role group and finish section, verify all the details, and then click Add role group.

6. Click Done.

Use Exchange Online PowerShell to create role assignment policies

To create a role assignment policy, use the following syntax:

New-RoleAssignmentPolicy -Name <UniqueName> [-Description "<Descriptive Text>"] [-Roles "<EndUserRole1>","<EndUserRole2>"...] [-IsDefault]

This example creates a new role assignment policy named Contoso Contractors that include the specified end-user roles.

New-RoleAssignmentPolicy -Name "Contoso Contractors" -Description "Limited self-management capabilities for contingent staff."] -Roles "MyBaseOptions","MyContactInformation","MyProfileInformation"

For detailed syntax and parameter information, see New-RoleAssignmentPolicy.

Modify role assignment policies

You can use the EAC or Exchange PowerShell to Add or remove roles from a role assignment policy.

You can only use Exchange Online PowerShell to specify the default role assignment policy that's applied to new mailboxes that aren't assigned a license or a role assignment policy when they're created.

Otherwise, all you can do in the EAC or Exchange Online PowerShell is modify the name and description of the role assignment policy.

Use Exchange Online PowerShell to specify the default role assignment policy

To specify the default role assignment policy, use the following syntax:

Set-RoleAssignmentPolicy -Identity "<RoleAssignmentPolicyName>" -IsDefault

This example configures Contoso Users as the default role assignment policy.

Set-RoleAssignmentPolicy -Identity "Contoso Users" -IsDefault

Note: The IsDefault switch is also available on the New-RoleAssignmentPolicy cmdlets.

For detailed syntax and parameter information, see Set-RoleAssignmentPolicy.

Remove role assignment policies

You can't remove the role assignment policy that's currently specified as the default. You first need to specify another role assignment policy as the default before you can delete the policy.

You can't remove a role assignment policy that's assigned to mailboxes. Use the procedures described in the Use Exchange Online PowerShell to modify role assignment policy assignments on mailboxes section to replace the role assignment policy that's assigned to mailboxes.

Use the EAC to remove role assignment policies

1. In the EAC, go to Roles > Admin roles.

2. Select the role group and click Delete.

3. Click Confirm in the confirmation window.

Use Exchange Online PowerShell to remove role assignment policies

To remove a role assignment policy, use the following syntax:

Remove-RoleAssignmentPolicy -Identity "<RoleAssignmentPolicyName>"

This example removes the role assignment policy named Contoso Managers.

Remove-RoleAssignmentPolicy -Identity "Contoso Managers"

For detailed syntax and parameter information, see Remove-RoleAssignmentPolicy.

View role assignment policy assignments on mailboxes

Use the EAC to view role assignment policy assignments on mailboxes

1. In the EAC, go to Recipients > Mailboxes, select the mailbox, and click Edit .

2. In the mailbox properties window that opens, click Mailbox features. The role assignment policy is shown in the Role assignment policy field.

3. When you're finished, click Save.

Use Exchange Online PowerShell to view role assignment policy assignments on mailboxes

To see the role assignment policy assignment on a specific mailbox, use the following syntax:

Get-Mailbox -Identity <MailboxIdentity> | Format-List RoleAssignmentPolicy

This example returns the role assignment policy for the mailbox named Pedro Pizarro.

Get-Mailbox -Identity "Pedro Pizarro" | Format-List RoleAssignmentPolicy

To return all mailboxes that have a specific role assignment policy assigned, use the following syntax:

$<VariableName> = Get-Mailbox -ResultSize unlimited

$<VariableName> | where {$_.RoleAssignmentPolicy -eq '<RoleAssignmentPolicyName>'}

This example returns all mailboxes that have the role assignment policy named Contoso Managers assigned.

$Mgrs = Get-Mailbox -ResultSize unlimited

$Mgrs | where {$_.RoleAssignmentPolicy -eq 'Contoso Managers'}

Modify role assignment policy assignments on mailboxes

A mailbox can have only one role assignment policy assigned. The role assignment policy that you assign to the mailbox will replace the existing role assignment policy that's assigned.

Use the EAC to modify role assignment policy assignments on mailboxes

In the EAC, click Recipients > Mailboxes, and do one of the following steps:

• Individual mailboxes: Select the mailbox > click Edit > click Mailbox features in the window that opens > click the dropdown next to Role assignment policy > select a new role assignment policy > click Save.

• Multiple mailboxes: Select multiple mailboxes of the same type (for example, User) by selecting a mailbox, holding down the Shift key, and select another mailbox farther down in the list or by holding down the Ctrl key as you select each mailbox. In the details pane (that's now titled Bulk Edit): click More options > click Update. In the Role Assignment Policy section, select the role assignment policy in the window that appears > click Save.

Use Exchange Online PowerShell to modify role assignment policy assignments on mailboxes

To change the role assignment policy assignment on a specific mailbox, use this syntax:

Set-Mailbox -Identity <MailboxIdentity> -RoleAssignmentPolicy "<RoleAssignmentPolicyName>"

This example applies the role assignment policy named Contoso Managers to the mailbox named Pedro Pizarro.

Get-Mailbox -Identity "Pedro Pizarro" -RoleAssignmentPolicy "<RoleAssignmentPolicyName>"

To change the assignment for all mailboxes that have a specific role assignment policy assigned, use the following syntax:

$<VariableName> = Get-Mailbox -ResultSize unlimited

$<VariableName> | where {$_.RoleAssignmentPolicy -eq '<CurrentRoleAssignmentPolicyName>'} | Set-Mailbox -RoleAssignmentPolicy '<NewRoleAssignmentPolicyName>'

This example changes the role assignment policy from Default Role Assignment Policy to Contoso Staff for all mailboxes that currently have Default Role Assignment Policy assigned.

$Users = Get-Mailbox -ResultSize unlimited

$Users | where {$_.RoleAssignmentPolicy -eq 'Default Role Assignment Policy'} | Set-Mailbox -RoleAssignmentPolicy 'Contoso Staff'