Find the permissions required to run any Exchange cmdlet

You can use PowerShell to find the permissions required to run any Exchange or Exchange Online cmdlet. This procedure shows the role-based access control (RBAC) management roles and role groups that give you access to a specified cmdlet—even if your organization has custom roles, custom role groups, or custom role assignments.

What do you need to know before you begin?

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

  • You can only use PowerShell to perform these procedures.

  • Basically, you need to be an administrator to complete this procedure. Specifically, you need access to the Get-ManagementRole and Get-ManagementRoleAssignment cmdlets. By default, access to these cmdlets is granted by the View-Only Configuration or Role Management roles, which are only assigned to the View-Only Organization Management and Organization Management role groups by default.

  • The procedures in this article don't work in Security & Compliance Center PowerShell or standalone Exchange Online Protection (EOP) PowerShell (Microsoft 365 organizations without Exchange Online mailboxes). For more information about permissions in these environments, see the following articles:

Tip

Having problems? Ask for help in the Exchange forums. Visit the forums at: Exchange Server or Exchange Online.

Use PowerShell to find the permissions required to run a cmdlet

  1. If you haven't already, open the Exchange PowerShell environment that you're interested in:

  2. Replace <Cmdlet> and optionally, <Parameter1>,<Parameter2>,... with the values that you want to use, and run the following command:

    $Perms = Get-ManagementRole -Cmdlet <Cmdlet> [-CmdletParameters <Parameter1>,<Parameter2>,...]
    

    Note: If you specify multiple parameters, only roles that include the cmdlet with all of the parameters are returned.

  3. Run the following command:

    $Perms | foreach {Get-ManagementRoleAssignment -Role $_.Name -Delegating $false | Format-Table -Auto Role,RoleAssigneeType,RoleAssigneeName}
    

Interpreting the results

The results contain the following information:

  • Role: Indicates the role that gives access to the cmdlet or the combination of cmdlet and parameters. Note that role names that begin with "My" are user roles that allow regular users to operate on objects they own (for example, their own mailbox or their distribution groups).

  • RoleAssigneeType and RoleAssigneeName: These values are inter-related:

    • RoleAssigneeType is the type of object that has the role assigned to it. For administrator roles, this value is typically a role group, but it can also be a role assignment policy, a security group, or a user.
    • RoleAssigneeName is the name of the role group, role assignment policy, security group, or user.

Troubleshooting

What if there are no results?

  • Verify that you entered the cmdlet and parameter names correctly.

  • The parameters that you specified are actually available for a cmdlet in a single role. Try specifying only the cmdlet name in the first command before you run the second command. Then, add the parameters one at a time to the first command before you run the second command.

Otherwise, no results are likely caused by one of the following conditions:

  • The cmdlet or parameters are defined in a role that isn't assigned to any role groups by default.
  • The cmdlet or parameters aren't available in your environment. For example, you specified an Exchange Online cmdlet or Exchange Online parameters in an on-premises Exchange environment.

To find the roles in your environment (if any) that contain the cmdlet or parameters, replace <Cmdlet> and optionally, <Parameter1>,<Parameter2>,... with the values that you want to use and run the following command:

Get-ManagementRoleEntry -Identity *\<Cmdlet>  [-Parameters <Parameter1>,<Parameter2>,...]

Note: You can use wildcard characters (*) in the cmdlet and parameter names (for example, *-Mailbox*).

If the command returns an error saying the object couldn't be found, the cmdlet or parameters aren't available in your environment.

If the command returns results, the cmdlet or parameters are available in your environment, but the required role isn't assigned to any role groups. To find roles that aren't assigned to any role groups, run the following command:

$na = Get-ManagementRole; $na | foreach {If ((Get-ManagementRoleAssignment -Role $_.Name -Delegating $false) -eq $null) {$_.Name}}

Include management role scopes

Management role scopes (in particular, write scopes) define where cmdlets can operate. For example, the entire organization or only on specific user objects.

To include scope information in the Use PowerShell to find the permissions required to run a cmdlet output, add *Scope* to the second command:

$Perms | foreach {Get-ManagementRoleAssignment -Role $_.Name -Delegating $false | Format-List Role,RoleAssigneeType,RoleAssigneeName,*Scope*}

For detailed information about management role scopes, see Understanding management role scopes.

Find all roles assigned to a specific user

To see all roles that are assigned to a specific user, replace <UserIdentity> with the name, alias, or email address of the user and run the following command:

Get-ManagementRoleAssignment -RoleAssignee <UserIdentity> -Delegating $false | Format-Table -Auto Role,RoleAssigneeName,RoleAssigneeType

For example:

Get-ManagementRoleAssignment -RoleAssignee julia@contoso.com -Delegating $false | Format-Table -Auto Role,RoleAssigneeName,RoleAssigneeType

Note: The RoleAssignee parameter returns both direct role assignments to users (uncommon) and indirect role assignments granted to the user through their membership in role groups.

Find all users who have a specific role assigned

To see all users who have a specific role assigned to them, replace <Role name> with the name of the role and run the following command:

Get-ManagementRoleAssignment -Role "<Role name>" -GetEffectiveUsers -Delegating $false | Where-Object {$_.EffectiveUserName -ne "All Group Members"} | Format-Table -Auto EffectiveUserName,Role,RoleAssigneeName,AssignmentMethod

For example:

Get-ManagementRoleAssignment -Role "Mailbox Import Export"  -GetEffectiveUsers -Delegating $false | Where-Object {$_.EffectiveUserName -ne "All Group Members"} | Format-Table -Auto EffectiveUserName,Role,RoleAssigneeName,AssignmentMethod

Find the members of a role group

To see the members of a specific role group, replace <Role group name> with the name of the role group and run the following command:

Get-RoleGroupMember "<Role group name>"

For example:

Get-RoleGroupMember "Organization Management"

Note: To see the names of all available role groups, run Get-RoleGroup.