Get-ManagementRoleAssignment
This cmdlet is available in on-premises Exchange and in the cloud-based service. Some parameters and settings may be exclusive to one environment or the other.
Use the Get-ManagementRoleAssignment cmdlet to retrieve management role assignments.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
Get-ManagementRoleAssignment
[[-Identity] <RoleAssignmentIdParameter>]
[-ConfigWriteScope <ConfigWriteScopeType>]
[-CustomConfigWriteScope <ManagementScopeIdParameter>]
[-CustomRecipientWriteScope <ManagementScopeIdParameter>]
[-Delegating <Boolean>]
[-DomainController <Fqdn>]
[-Enabled <Boolean>]
[-Exclusive <Boolean>]
[-ExclusiveConfigWriteScope <ManagementScopeIdParameter>]
[-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>]
[-GetEffectiveUsers]
[-RecipientAdministrativeUnitScope <AdministrativeUnitIdParameter>]
[-RecipientGroupScope <GroupIdParameter>]
[-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>]
[-RecipientWriteScope <RecipientWriteScopeType>]
[-RoleAssigneeType <RoleAssigneeType>]
[-WritableDatabase <DatabaseIdParameter>]
[-WritableRecipient <GeneralRecipientIdParameter>]
[-WritableServer <ServerIdParameter>]
[<CommonParameters>] Get-ManagementRoleAssignment
[-AssignmentMethod <AssignmentMethod[]>]
[-Role <RoleIdParameter>]
[-ConfigWriteScope <ConfigWriteScopeType>]
[-CustomConfigWriteScope <ManagementScopeIdParameter>]
[-CustomRecipientWriteScope <ManagementScopeIdParameter>]
[-Delegating <Boolean>]
[-DomainController <Fqdn>]
[-Enabled <Boolean>]
[-Exclusive <Boolean>]
[-ExclusiveConfigWriteScope <ManagementScopeIdParameter>]
[-ExclusiveRecipientWriteScope <ManagementScopeIdParameter>]
[-GetEffectiveUsers]
[-RecipientAdministrativeUnitScope <AdministrativeUnitIdParameter>]
[-RecipientGroupScope <GroupIdParameter>]
[-RecipientOrganizationalUnitScope <OrganizationalUnitIdParameter>]
[-RecipientWriteScope <RecipientWriteScopeType>]
[-RoleAssignee <RoleAssigneeIdParameter>]
[-RoleAssigneeType <RoleAssigneeType>]
[-WritableDatabase <DatabaseIdParameter>]
[-WritableRecipient <GeneralRecipientIdParameter>]
[-WritableServer <ServerIdParameter>]
[<CommonParameters>] Description
You can retrieve role assignments in a variety of ways including by assignment type, scope type, or name, and whether the assignment is enabled or disabled. You can also view a list of role assignments that provide access to a specified recipient, server, or database.
For more information about management role assignments, see Understanding management role assignments.
You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet.
Examples
Example 1
Get-ManagementRoleAssignment "Denver Help Desk" | Format-ListThis example retrieves the Denver Help Desk role assignment using the Get-ManagementRoleAssignment cmdlet and pipes the output to the Format-List cmdlet. For more information about the Format-List cmdlet, see Working with command output.
Example 2
Get-ManagementRoleAssignment -Enabled $true -Delegating $trueThis example retrieves all the role assignments that are enabled and have been designated as delegating role assignments.
Example 3
Get-ManagementRoleAssignment -RecipientWriteScope MyGALThis example retrieves all the role assignments that include the MyGAL recipient-based scope restriction type.
Example 4
Get-ManagementRoleAssignment -Role "Mail Recipients"This example retrieves all the role assignments associated with the Mail Recipients management role.
Example 5
Get-ManagementRoleAssignment -WritableRecipient Bob -GetEffectiveUsersThis example retrieves a list of all the users and the role assignments that can modify the recipient Bob.
Example 6
Get-ManagementRoleAssignment -ExclusiveConfigWriteScope "Redmond Executive Servers" -GetEffectiveUsersThis example retrieves a list of all exclusive scopes that can modify server objects that match Redmond Executive Servers. The command also lists the users who are effectively assigned the role assignments through role groups or USGs.
Example 7
Get-ManagementRoleAssignment -WritableDatabase "Contoso Sales"This example retrieves all the role assignments that can modify the database Contoso Sales.
Parameters
-AssignmentMethod
The AssignmentMethod parameter specifies the type of role assignment to include in the results returned by the cmdlet. You can specify one or more of the following values:
- Direct
- SecurityGroup
- RoleGroup
- RoleAssignmentPolicy
If you provide more than one value, separate each value with a comma.
You must specify a value with the RoleAssignee parameter if you use the AssignmentMethod parameter.
| Type: | AssignmentMethod[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-ConfigWriteScope
The ConfigWriteScope parameter specifies the type of management configuration scope to include in the results returned by the cmdlet. The valid values are None, OrganizationConfig, CustomConfigScope, and ExclusiveConfigScope.
| Type: | ConfigWriteScopeType |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-CustomConfigWriteScope
This parameter is available only in on-premises Exchange.
The CustomConfigWriteScope parameter returns only the regular role assignments that include the specified configuration-based regular scope.
This parameter can only be used to retrieve regular configuration-based scopes. To retrieve a list of exclusive configuration-based scopes, use the ExclusiveConfigWriteScope parameter instead.
If the scope name contains spaces, enclose it in quotation marks (").
| Type: | ManagementScopeIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019 |
-CustomRecipientWriteScope
The CustomRecipientWriteScope parameter returns only the regular role assignments that include the specified recipient-based regular scope.
This parameter can only be used to retrieve regular recipient-based scopes. To retrieve a list of exclusive recipient-based scopes, use the ExclusiveRecipientWriteScope parameter instead.
If the scope name contains spaces, enclose it in quotation marks (").
| Type: | ManagementScopeIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-Delegating
The Delegating parameter specifies whether delegating or regular role assignments should be returned.
By default, both delegating and regular scopes are returned. To return only delegating role assignments, specify a value of $true. To return only regular role assignments, specify a value of $false.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-DomainController
This parameter is available only in on-premises Exchange.
The DomainController parameter specifies the domain controller that's used by this cmdlet to read data from or write data to Active Directory. You identify the domain controller by its fully qualified domain name (FQDN). For example, dc01.contoso.com.
| Type: | Fqdn |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019 |
-Enabled
The Enabled parameter specifies whether enabled or disabled role assignments should be returned. To return enabled role assignments, specify a value of $true. To return disabled role assignments, specify a value of $false.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-Exclusive
The Exclusive parameter specifies whether exclusive or regular role assignments should be returned.
By default, both exclusive and regular scopes are returned. To return only exclusive role assignments, specify a value of $true. To return only regular role assignments, specify a value of $false.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-ExclusiveConfigWriteScope
This parameter is available only in on-premises Exchange.
The ExclusiveConfigWriteScope parameter returns only the exclusive role assignments that include the specified configuration-based exclusive scope.
This parameter can only be used to retrieve exclusive configuration-based scopes. To retrieve a list of regular configuration-based scopes, use the CustomConfigWriteScope parameter instead.
If the scope name contains spaces, enclose it in quotation marks (").
| Type: | ManagementScopeIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019 |
-ExclusiveRecipientWriteScope
The ExclusiveRecipientWriteScope parameter returns only the exclusive role assignments that include the specified recipient-based exclusive scope.
This parameter can only be used to retrieve exclusive recipient-based scopes. To retrieve a list of regular recipient-based scopes, use the CustomRecipientWriteScope parameter instead.
If the scope name contains spaces, enclose it in quotation marks (").
| Type: | ManagementScopeIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-GetEffectiveUsers
The GetEffectiveUsers switch specifies that the command should show the list of users in the role groups, role assignment policies, or USGs that are associated with the role assignment. You don't need to specify a value with this switch.
Effectively, users are associated with the role assignment through their role group, role assignment policy, or USG memberships.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-Identity
The Identity parameter specifies the name of the role assignment to retrieve. If the name of the role assignment contains spaces, enclose it in quotation marks ("). If the RoleAssignee parameter is used, you can't use the Identity parameter.
| Type: | RoleAssignmentIdParameter |
| Position: | 1 |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-RecipientAdministrativeUnitScope
This parameter is functional only in the cloud-based service.
The RecipientAdministrativeUnitScope parameter returns only the role assignments that include the specified administrative unit.
Administrative units are Microsoft Entra containers of resources. You can view the available administrative units by using the Get-AdministrativeUnit cmdlet.
| Type: | AdministrativeUnitIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-RecipientGroupScope
This parameter is available only in the cloud-based service.
The RecipientGroupScope parameter returns only the role assignments that are scoped to groups. You can use any value that uniquely identifies the group: Name, DistinguishedName, GUID, DisplayName.
| Type: | GroupIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Online, Exchange Online Protection |
-RecipientOrganizationalUnitScope
The RecipientOrganizationalUnitScope parameter returns only the role assignments that include the specified organizational unit (OU). If the OU tree contains spaces, enclose it in quotation marks (").
| Type: | OrganizationalUnitIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-RecipientWriteScope
The RecipientWriteScope parameter returns only the role assignments associated with the recipient scope restriction type specified. The valid values are None, MyGAL, Self, OU, CustomRecipientScope, MyDistributionGroups and ExclusiveRecipientScope.
| Type: | RecipientWriteScopeType |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-Role
The Role parameter returns only the role assignments associated with the specified management role. If the name of the role contains spaces, enclose it in quotation marks (").
| Type: | RoleIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-RoleAssignee
The RoleAssignee parameter specifies the role group, assignment policy, user, or universal security group (USG) for which you want to view role assignments. If the RoleAssignee parameter is used, you can't use the Identity parameter.
By default, the command returns both direct role assignments to the role assignee and indirect role assignments granted to a role assignee through role groups or assignment policies.
If the name of the user or USG contains spaces, enclose it in quotation marks (").
| Type: | RoleAssigneeIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-RoleAssigneeType
The RoleAssigneeType parameter specifies the type of role assignee to return. The valid values are User, SecurityGroup, RoleAssignmentPolicy, ForeignSecurityPrincipal, RoleGroup, LinkedRoleGroup and Computer.
| Type: | RoleAssigneeType |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-WritableDatabase
This parameter is available only in on-premises Exchange.
The WritableDatabase parameter specifies the database object you want to test to determine which role assignments allow it to be modified. The command takes into account the roles and scopes associated with each role assignment. You can use any value that uniquely identifies the database. For example:
- Name
- Distinguished name (DN)
- GUID
If you use this parameter with the GetEffectiveUsers switch, all the users who can modify the database object indirectly through role groups and USGs are also returned. Without the GetEffectiveUsers switch, only the role groups, users and USGs directly assigned the role assignment are returned.
| Type: | DatabaseIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019 |
-WritableRecipient
The WritableRecipient parameter specifies the recipient object you want to test to determine which role assignments allow it to be modified. The command takes into account the roles and scopes associated with each role assignment. If the recipient name contains spaces, enclose it in quotation marks (").
If this parameter is used with the GetEffectiveUsers switch, all of the users who can modify the recipient object indirectly through role groups and USGs are also returned. Without the GetEffectiveUsers switch, only the role groups, users and USGs directly assigned the role assignment are returned.
| Type: | GeneralRecipientIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019, Exchange Online, Exchange Online Protection |
-WritableServer
This parameter is available only in on-premises Exchange.
The WritableServer parameter specifies the server object you want to test to determine which role assignments allow it to be modified. The command takes into account the roles and scopes associated with each role assignment.
You can use any value that uniquely identifies the server. For example:
- Name
- FQDN
- Distinguished name (DN)
- Exchange Legacy DN
If this parameter is used with the GetEffectiveUsers switch, all of the users who can modify the server object indirectly through role groups and USGs are also returned. Without the GetEffectiveUsers switch, only the role groups, users and USGs directly assigned the role assignment are returned.
| Type: | ServerIdParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2010, Exchange Server 2013, Exchange Server 2016, Exchange Server 2019 |
Inputs
Input types
To see the input types that this cmdlet accepts, see Cmdlet Input and Output Types. If the Input Type field for a cmdlet is blank, the cmdlet doesn't accept input data.
Outputs
Output types
To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types. If the Output Type field is blank, the cmdlet doesn't return data.