set management role assignment

This browser is no longer supported.

Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.

Set-Management Role Assignment

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 Set-ManagementRoleAssignment cmdlet to modify existing management role assignments.

For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax .

Description

When you modify a role assignment, you can specify a new predefined or custom management scope or provide an organizational unit (OU) to scope the existing role assignment.

You can create custom management scopes using the New-ManagementScope cmdlet and can view a list of existing scopes using the Get-ManagementScope cmdlet. If you choose not to specify an OU, predefined scope, or custom scope, the implicit write scope of the role applies to the role assignment.

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 .

This example disables the Mail Recipients_Denver Help Desk role assignment. When a role assignment is disabled, the users assigned the role can no longer run cmdlets granted by the role.

This example changes the recipient scope for the MyGAL_KimA role assignment to MyGAL. When the recipient scope is changed to a predefined value, any previously defined OUs or custom scopes are overwritten.

This example restricts the Mail Recipients_Marketing Admins role assignment to the contoso.com/North America/Marketing/Users OU. Users who are members of the Marketing Admins role group assigned the role assignment can create, modify, and remove objects only in the specified OU. When the RecipientOrganizationalUnitScope parameter is used, any predefined or custom scopes on the role assignment are overwritten.

This example restricts the Distribution Groups_Cairns Admins role assignment using the Cairns Recipients custom recipient management scope. Users that are members of the Cairns Admins role group assigned the role assignment can create, modify, and remove only the distribution group objects that match the Cairns Recipients custom recipient management scope.

The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.

• Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: -Confirm:$false .
• Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.

-CustomConfigWriteScope

This parameter is available only in on-premises Exchange.

The CustomConfigWriteScope parameter specifies the existing configuration management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the CustomConfigWriteScope parameter, you can't use the ExclusiveConfigWriteScope parameter.

To remove a scope, specify a value of $null.

-CustomRecipientWriteScope

The CustomRecipientWriteScope parameter specifies the existing recipient-based management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the CustomRecipientWriteScope parameter, you can't use the RecipientOrganizationalUnitScope, RecipientRelativeWriteScope, or ExclusiveRecipientWriteScope parameters, and any configured OU or predefined scope on the role assignment is overwritten.

-CustomResourceScope

This parameter is available only in the cloud-based service.

The CustomResourceScope parameter specifies the custom management scope to associate with this management role assignment. You can use any value that uniquely identifies the management scope. For example:

• Distinguished name (DN)

If the value contains spaces, enclose the value in quotation marks (").

You use this parameter with the App parameter to assign permissions to service principals. For more information, see For more information about service principals, see Application and service principal objects in Microsoft Entra ID .

-DomainController

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.

The Enabled parameter specifies whether the management role assignment is enabled or disabled. The valid values are $true and $false.

-ExclusiveConfigWriteScope

The ExclusiveConfigWriteScope parameter specifies the existing configuration exclusive management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the ExclusiveConfigWriteScope parameter, you can't use the CustomConfigWriteScope parameter.

-ExclusiveRecipientWriteScope

The ExclusiveRecipientWriteScope parameter specifies the existing recipient-based exclusive management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the ExclusiveRecipientWriteScope parameter, you can't use the CustomRecipientWriteScope, RecipientOrganizationalUnitScope, or RecipientRelativeWriteScope parameters and any configured OU or predefined scope on the role assignment is overwritten.

The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.

You can use this switch to run tasks programmatically where prompting for administrative input is inappropriate.

The Identity parameter specifies the name of the management role assignment to modify. If the name of the management role contains spaces, enclose it in quotation marks (").

-RecipientAdministrativeUnitScope

This parameter is functional only in the cloud-based service.

The RecipientAdministrativeUnitScope parameter specifies the administrative unit to scope the role assignment to.

Administrative units are Microsoft Entra containers of resources. You can view the available administrative units by using the Get-AdministrativeUnit cmdlet.

You can't use this parameter with any of the other scope parameters.

-RecipientGroupScope

The RecipientGroupScope parameter specifies a group to consider for scoping the role assignment. Individual members of the specified group (not nested groups) are considered as in scope for the assignment. You can use any value that uniquely identifies the group: Name, DistinguishedName, GUID, or DisplayName.

-RecipientOrganizationalUnitScope

The RecipientOrganizationalUnitScope parameter specifies the OU to scope the new role assignment to. If the OU name contains spaces, enclose the domain and OU in quotation marks (").

If you use the RecipientOrganizationalUnitScope parameter, you can't use the CustomRecipientWriteScope, ExclusiveRecipientWriteScope, or RecipientRelativeWriteScope parameters and any predefined scopes or custom scopes on the role assignment are overwritten.

To specify an OU, use the syntax: domain/ou. To remove an OU, specify a value of $null.

-RecipientRelativeWriteScope

The RecipientRelativeWriteScope parameter specifies the type of restriction to apply to a recipient scope.

If you use the RecipientRelativeWriteScope parameter, you can't use the CustomRecipientWriteScope, ExclusiveRecipientWriteScope, or RecipientOrganizationalUnitScope parameters.

The available types are: None, Organization, MyGAL, Self and MyDistributionGroups. If you specify a predefined scope, any custom scope or configured OU on the role assignment is overwritten.

Even though the NotApplicable, OU, MyDirectReports, CustomRecipientScope, MyExecutive, MailboxICanDelegate, and ExclusiveRecipientScope values appear in the syntax block for this parameter, they can't be used directly on the command line. They're used internally by the cmdlet.

The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.

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.

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.

Was this page helpful?

Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback .

Submit and view feedback for

Additional resources

Navigation Menu

Search code, repositories, users, issues, pull requests..., provide feedback.

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly.

To see all available qualifiers, see our documentation .

• Notifications

Set-ManagementRoleAssignment.md

Latest commit, file metadata and controls, set-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 Set-ManagementRoleAssignment cmdlet to modify existing management role assignments.

For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax .

RelativeRecipientWriteScope

Customrecipientwritescope, recipientorganizationalunitscope, exclusivescope, recipientadministrativeunitscope, recipientgroupscope, description.

When you modify a role assignment, you can specify a new predefined or custom management scope or provide an organizational unit (OU) to scope the existing role assignment.

You can create custom management scopes using the New-ManagementScope cmdlet and can view a list of existing scopes using the Get-ManagementScope cmdlet. If you choose not to specify an OU, predefined scope, or custom scope, the implicit write scope of the role applies to the role assignment.

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 .

This example disables the Mail Recipients_Denver Help Desk role assignment. When a role assignment is disabled, the users assigned the role can no longer run cmdlets granted by the role.

This example changes the recipient scope for the MyGAL_KimA role assignment to MyGAL. When the recipient scope is changed to a predefined value, any previously defined OUs or custom scopes are overwritten.

This example restricts the Mail Recipients_Marketing Admins role assignment to the contoso.com/North America/Marketing/Users OU. Users who are members of the Marketing Admins role group assigned the role assignment can create, modify, and remove objects only in the specified OU. When the RecipientOrganizationalUnitScope parameter is used, any predefined or custom scopes on the role assignment are overwritten.

This example restricts the Distribution Groups_Cairns Admins role assignment using the Cairns Recipients custom recipient management scope. Users that are members of the Cairns Admins role group assigned the role assignment can create, modify, and remove only the distribution group objects that match the Cairns Recipients custom recipient management scope.

The Identity parameter specifies the name of the management role assignment to modify. If the name of the management role contains spaces, enclose it in quotation marks (").

-RecipientAdministrativeUnitScope

This parameter is functional only in the cloud-based service.

The RecipientAdministrativeUnitScope parameter specifies the administrative unit to scope the role assignment to.

Administrative units are Microsoft Entra containers of resources. You can view the available administrative units by using the Get-AdministrativeUnit cmdlet.

You can't use this parameter with any of the other scope parameters.

-RecipientGroupScope

This parameter is available only in the cloud-based service.

The RecipientGroupScope parameter specifies a group to consider for scoping the role assignment. Individual members of the specified group (not nested groups) are considered as in scope for the assignment. You can use any value that uniquely identifies the group: Name, DistinguishedName, GUID, or DisplayName.

The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.

• Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: -Confirm:$false .
• Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.

-CustomConfigWriteScope

This parameter is available only in on-premises Exchange.

The CustomConfigWriteScope parameter specifies the existing configuration management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the CustomConfigWriteScope parameter, you can't use the ExclusiveConfigWriteScope parameter.

To remove a scope, specify a value of $null.

-CustomRecipientWriteScope

The CustomRecipientWriteScope parameter specifies the existing recipient-based management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the CustomRecipientWriteScope parameter, you can't use the RecipientOrganizationalUnitScope, RecipientRelativeWriteScope, or ExclusiveRecipientWriteScope parameters, and any configured OU or predefined scope on the role assignment is overwritten.

-CustomResourceScope

The CustomResourceScope parameter specifies the custom management scope to associate with this management role assignment. You can use any value that uniquely identifies the management scope. For example:

• Distinguished name (DN)

If the value contains spaces, enclose the value in quotation marks (").

You use this parameter with the App parameter to assign permissions to service principals. For more information, see For more information about service principals, see Application and service principal objects in Microsoft Entra ID .

-DomainController

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.

The Enabled parameter specifies whether the management role assignment is enabled or disabled. The valid values are $true and $false.

-ExclusiveConfigWriteScope

The ExclusiveConfigWriteScope parameter specifies the existing configuration exclusive management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the ExclusiveConfigWriteScope parameter, you can't use the CustomConfigWriteScope parameter.

-ExclusiveRecipientWriteScope

The ExclusiveRecipientWriteScope parameter specifies the existing recipient-based exclusive management scope to associate with this management role assignment. If the management scope name contains spaces, enclose it in quotation marks (").

If you use the ExclusiveRecipientWriteScope parameter, you can't use the CustomRecipientWriteScope, RecipientOrganizationalUnitScope, or RecipientRelativeWriteScope parameters and any configured OU or predefined scope on the role assignment is overwritten.

The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.

You can use this switch to run tasks programmatically where prompting for administrative input is inappropriate.

-RecipientOrganizationalUnitScope

The RecipientOrganizationalUnitScope parameter specifies the OU to scope the new role assignment to. If the OU name contains spaces, enclose the domain and OU in quotation marks (").

If you use the RecipientOrganizationalUnitScope parameter, you can't use the CustomRecipientWriteScope, ExclusiveRecipientWriteScope, or RecipientRelativeWriteScope parameters and any predefined scopes or custom scopes on the role assignment are overwritten.

To specify an OU, use the syntax: domain/ou. To remove an OU, specify a value of $null.

-RecipientRelativeWriteScope

The RecipientRelativeWriteScope parameter specifies the type of restriction to apply to a recipient scope.

If you use the RecipientRelativeWriteScope parameter, you can't use the CustomRecipientWriteScope, ExclusiveRecipientWriteScope, or RecipientOrganizationalUnitScope parameters.

The available types are: None, Organization, MyGAL, Self and MyDistributionGroups. If you specify a predefined scope, any custom scope or configured OU on the role assignment is overwritten.

Even though the NotApplicable, OU, MyDirectReports, CustomRecipientScope, MyExecutive, MailboxICanDelegate, and ExclusiveRecipientScope values appear in the syntax block for this parameter, they can't be used directly on the command line. They're used internally by the cmdlet.

The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters .

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.

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.

RELATED LINKS

Subscribe for Practical 365 updates

Please turn off your ad blocker and refresh the page to subscribe.

You may withdraw your consent at any time. Please visit our Privacy Statement for additional information

Exchange Online / Exchange Server

How to report on exchange rbac assignments.

Exchange Server and its cloud sibling are well-known for their robust administrative controls, powered by the RBAC model. Designed with great attention to detail, the RBAC model allows you to granularly control what each admin or user can do, down to the individual cmdlet or even parameter level. While this is extremely useful, because of the flexibility of the model, sometimes it can be a bit hard to keep track of just what permissions have been granted in the organization.

To address this issue, you can use PowerShell to prepare detailed reports of the roles assigned. One such example script is provided by Paul here at Practical 365, and many admins have already made a habit of running it periodically against their environments. The script, however, relies on the AD PowerShell cmdlets and as such cannot be run against Exchange Online, so in this article, we will introduce an updated/alternative approach. We will also discuss some potential improvement areas, and of course, provide you with the actual solution.

A quick refresher on Exchange RBAC

As the name suggests, Exchange’s Role-based Access Control (RBAC) permission model has management roles as its building blocks. A role represents a set of tasks or cmdlets, granted to a role assignee . The role assignee can be a user, a security group or a role group (or a role assignment policy, which we don’t cover here). The link between the role and its assignees is called a management role assignment . Role assignments, in turn, can be regular or delegating. The former is used when you grant someone access to the management tools and features. On the other hand, delegating role assignments don’t grant access to the management tools, but are used to grant someone the ability to assign a given role to others. Lastly, we have the concept of management scopes , which can be used to limit the effect of the role to a subset of the objects in your organization.

While this all might sound very confusing at first, once you understand the basic principles behind the RBAC model, you will certainly appreciate its robustness and customizability. Even more so if you come to compare it with other workloads such as SharePoint or Skype for Business. In Exchange Online, the RBAC model is a bit more limited compared to on-premises versions, but it’s still well ahead of what we get in other parts of the service, including Azure AD.

How to find out who has permissions

Just because some admin functionality exists, it doesn’t mean it’s in use. The same goes for any Exchange management roles. Role assignments effectively represent the “link” between a role and the security principals who have been granted permissions to access the cmdlets, scripts or tools available as part of the role. If no role assignment exists for a given role, then no one in the organization has access to the management tasks it enables. Generally speaking, you can omit such roles from your report. But if you want to be thorough, or are just curious, here’s how to list any (admin) roles that have no corresponding role assignments:

In the above, we are listing all roles, then for each role checking whether any role assignments exist. We are also excluding any “end user” roles, such as the ones that govern different OWA features. The resulting list will return just the “unassigned” roles if any. Again, as no one is currently assigned to said roles, they are not “in use” and you can simply ignore them. The bottom line here is that if you want to get an overview of what permissions are granted in the company at present, the Get-ManagementRoleAssignment cmdlet is your natural starting point.

We now know how to list assignments for a given role. However, this doesn’t completely answer the question of who has been granted access, as roles can be delegated to security groups, or bundled in role groups and role assignment policies. If we want to list the individual users, we have to further “expand” the corresponding object, which is effectively what Paul’s script does for Role Groups. We are trying to address a broader scenario, however, so we need to also account for assignments of type User , SecurityGroup and PartnerLinkedRoleGroup. In turn, where needed we should aim to expand group membership and list individual users.

In the on-premises world, group expansion is easily performed via the AD tools. In Office 365, however, things aren’t that straightforward, and in general, we have to use solutions such as the one described in this article . Luckily, in the case of role assignments, the good folks at Microsoft have given us an easier method, namely the -GetEffectiveUsers switch parameter. What the switch does is to recursively process each nested group and return a list of the individual user entries. Here’s an example:

The first cmdlet lists just the direct assignees to the Journaling role. Three of those entries, namely the “Compliance management” and “Organization management” role groups and the “MESGtop” security group have additional members and even some nested groups. The full list of members is returned when we rerun the cmdlet with the – GetEffectiveUsers switch, one entry per user. Which is practically all we need to generate the report.

Another approach would be to use the Get-ManagementRoleAssignment cmdlet against specific security principal entry. The cmdlet is intelligent enough to not only list direct assignments, but also any assignments corresponding to security or role groups that have the given security principal as a member, including nested groups. However, since the number of such objects in most companies is larger than the number of role assignments, this method might be slower. Just in case, here’s an example:

Preparing the output

Now that we know how to list each individual user and each role they have been assigned, all we need to do is prepare the output. One approach is to just dump all this information into a CSV file, then use Excel to filter/sort it as needed. However, as you can see from the above screenshot, some of the data presented is quite ambiguous as objects are listed by their display name. We can improve the quality of the output by finding the corresponding object and return a unique identifier. Unfortunately, this might not always be possible, but for most scenarios, we should be able to identify the correct object.

The getUPN and getGroup helper function will try to “convert” a given DisplayName to the corresponding object and return a unique identifier for it. Since there can be multiple entries matching a given display name, the functions will call the Get-ManagementRoleAssignment and use the – Role and – RoleAssignee parameters to find out which entry corresponds to the actual role assignment. If they cannot find a match or multiple matches remain even after these additional checks, the display name will be returned as is.

Apart from providing additional information about each assignee, we can also use the native PowerShell capabilities to group the output by user. This might or might not be more convenient, but as mentioned above you can also use tools such as Excel to perform any grouping, sorting and filtering operations. The output returned from the script is sampled below:

For each user, group, or role group object, the object type, and unique identifier are returned (UPN or PrimarySMTPAddress where available, GUID otherwise). Then, a list of the individual Roles assigned to the given security principal is listed, and an indicator of the type of assignment. For objects with multiple roles assigned, we can have multiple values for the assignment type. Because we are grouping results, only unique role entries will be returned, if that’s not what you expect, edit the code on line 161.

Additional parameters

The script features a few additional parameters that govern the output. The first parameter is – IncludeDelegatingAssignments , which signals the script to also return details on any non-default Delegating Role Assignments. By non-default we mean delegating role assignments outside of those assigned to the “Organization Management” role group. If you don’t agree with the logic used here, feel free to adjust the filter on line 79.

The – IncludeRoleGroups parameter will force the script to return entries for “parent” role group assignments in the output. Since we are using the – GetEffectiveUsers parameter, any individual user that’s a direct member of the role group or member of any nested group within it is returned, so you might not want to see the “parent” entry as well. This is the default behavior, but if you do want to see such entries, you can specify the – IncludeRoleGroups parameter when invoking the script. No entries will be returned in the output for any nested groups, just the user objects within them! This is a limitation of using the – GetEffectiveUsers switch, but we plan to present an alternative solution in a future article.

Lastly, the – IncludeUnassignedRoleGroups switch governs whether to return entries for role groups that don’t have any role assignments. As discussed above, any cmdlets included in such role groups are effectively in “no use”, but you might want to include the role groups for completeness. This parameter can only be used when – IncludeRoleGroups is set to $true.

Here’s how the console output will look like when all these parameters are used. In the highlighted entries, you can see an object with a duplicate display name, but thanks to the additional checks performed by the script, a unique identifier is returned. You can also see users and groups with direct role assignments, including delegating ones; role groups with no assignments; “parent” groups.

The output will also be stored in the global variable $ varRoleAssignments so it can be easily reused. Don’t forget that the script will also save the “raw” output to a CSV file!

Download the script from the TechNet Gallery or GitHub , and don’t forget to send us your comments.

About the Author

Vasil Michev

Hi, Could you please test it in your environment and let me know if it works for you ? Regards

Forget this i have achieved with using parameters , but my next question is, the output of the Assignee is with ID instead of username, how can i get this with username ?

what kind of ID? A GUID? Can you do Get-Recipient -Id $Value to see what $Value (the identifier) resolves to?

Hi, this code doesn’t return any output. What could be the reason ? Thanks in advance. regards

No idea. Have you debugged it? The code is PowerShell after all, so you can step through it to discover where problems might lie.

One basic problem I see is that the script in GitHub attempts to connect to Exchange Online via basic auth. Have you tried changing the script so that it uses a simple Connect-ExchangeOnline instead of running the Check-Connectivity function?

Leave a Reply Cancel reply

Latest articles.

Practical Sentinel: A Practical Look at the Unified SecOps Experience

In this blog, we take a look at the Unified Security Operations Platform, review what is available right now, discuss what Microsoft is building, and ask whether you need this functionality.

Microsoft 365 Archive Could Help SharePoint Online Cope with Digital Debris

Microsoft 365 Archive is a solution to move SharePoint Online sites from hot to cold (less expensive) storage. It works well, and it comes with an added benefit in that archived sites are inaccessible to Copilot. In other words, you can make sure that Copilot doesn't process old and obsolete material by archiving sites that contain this type of content. Seems like a no-brainer.

Practical Protection: Copying Microsoft’s Secure Future Initiative

Microsoft recently released a memo from Security VP, Charlie Bell. In this blog, we recap the memo and discuss some of the new security initiatives Microsoft is working towards.

• Whitepapers
• Write for Us!
• Cloud Computing
• Virtualization
• all Topics...

Lead Image © Isaac Marzioli, 123RF.com

Hands-on Exchange rights management

Rigorous rights.

Starting with Exchange 2013, Microsoft changed its messaging server to role-based access control (RBAC). Among other things, this approach makes it easier for Windows administrators to manage user rights.

Two types of roles can be assigned: end user and administrator. Administrator roles include permissions that can be assigned to administrators who manage a particular area of the Exchange organization. If a user is a member of several role groups, Exchange grants the user the privileges of these groups.

End-user roles begin with a prefix of My . For example, members of the MyDistributionGroups user role are allowed to create their own distribution groups and delete their own groups. This is not always desirable in an enterprise environment. By modifying the permissions, you can revoke these rights for normal users. The easiest way is to create a new role based on the existing MyDistributionGroups user role, then revoke the rights and assign the role to your users.

For existing role groups, whether administrative or end-user, you can add or remove roles and add or remove members.

When you copy a role group, you create a new name and optionally add or remove roles to the new group, all without affecting the original role group.

For standard groups, it makes sense to make copies before you change the groups.

In Exchange Server 2013, the administrative role groups are located in the Permissions area. The Get-RoleGroup commandlet (cmdlet) lets you check out the various groups in the management shell. Get-RoleGroupMember shows the members of a group (e.g., Get-RoleGroupMember "Organization Management" ). To add a user to a group, you can use the Exchange Management Console ( Figure 1 ) or the Exchange Management Shell:

To remove members from a management role group, you also use the Exchange Management Console or issue the following Exchange Management Shell cmdlet:

If you click on a group in the management console, you can see on the right-hand side which rights the group has and which members are assigned to it. To add a user to a group, double-click the group. You can then add new Members or removing existing ones.

Management roles summarize the cmdlets used to manage Exchange components ( Figure 2 ). Users who are members of a management role group are allowed to use the cmdlets stored in the administrative roles, which in turn are part of the management role groups.

Delegating Maintenance

Management role group substitutes can add or remove members from management role groups and modify the properties of a role group, but they do not have the right to use the functions of the management role group themselves.

The substitute configuration is handled by the ManagedBy option in the Set-RoleGroup or New-RoleGroup cmdlets. If you want to assign the user the rights to the group as well, you need to include them as a member of the role group. The ManagedBy option for the Set-RoleGroup cmdlet always overwrites the entire managed-by list for a role group.

To add individual substitutes to a role group without deleting the entire proxy list, you must save existing members, add the new member, and then save the list again ( Figure 3 ):

1. $RoleGroup = Get-RoleGroup "<management role group>" saves the role group settings in a variable.

2. $RoleGroup.ManagedBy += <Get-User mailbox to add>.Identity adds the substitute to the role group you saved as a variable in step 1. To add a universal group, use the Get-Group cmdlet.

3. Repeat step 2 for each substitute you want to add.

4. Set-RoleGroup "<management role group>" -ManagedBy $RoleGroup.ManagedBy adds the list of variables to the real management role group.

To view the users who are allowed to manage the group, you can use the cmdlet:

In addition to the default groups, you can create your own management role groups and assign users to them. New management role groups are created with the New-RoleGroup cmdlet ( Listing 1 ).

New Management Role Group

If you want to create role groups that apply limited rights, you can copy existing role groups. Again, it is best to use the Exchange Management Shell for the copy.

In the first step, save the role group in a variable:

To create a new role group, add the role group members and define who can delegate the new role group to other users with:

For example, you can copy the Organization Management role group with

to create a new group with fewer rights.

RBAC Manager

If you want a more convenient management option, the RBAC Manager [1] is your choice. It requires no installation and comprises a single EXE file and an XML control file. If the Exchange Management Tools are installed on a workstation, you can use RBAC Manager on a workstation ( Figure 4 ).

RBAC Manager lets you manage management roles, management role assignment policies, and management groups. Once the program is started, you can type the name of the server with which you want to connect and your credentials. Subsequently, the RBAC Manager connects to the Exchange organization and uses the logged-in user's rights. You have to install .NET Framework 3.5 on the server.

On Windows Server 2012, you can use the Server Manager for this. In the upper area, you can switch between managing management roles, assignment policies, management role groups, and management scopes. Role Groups let you manage the members, management roles, and role assignments.

You can create your own role groups or modify existing ones. RBAC Manager saves the changes to a logfile, which you can access from the Tools menu. In the logfile, you can see the PowerShell cmdlet that RBAC Manager uses to handle configuration tasks.

Monitoring the Management of Role Groups

In the Exchange Management Console, you can see who has made changes to the rights – that is, who has assigned administrator rights to other users – by:

• selecting Compliance management | Auditing | Run an administrator role group report ,
• choosing the role group you want to monitor, and clicking Search .

In the window, you will see all the changes. In the Exchange Management Shell, you can view the administrators and their permissions. The GetEffectiveUsers option for the Get-ManagementRoleAssignment cmdlet shows you the rights:

Use the call

to view a specific user, or use

if you want to view all the management roles for a user.

1 2 3 Next »

Buy ADMIN Magazine

US / Canada

UK / Australia

Related content

Subscribe to our ADMIN Newsletters Subscribe to our Linux Newsletters Find Linux and Open Source Jobs

Most popular.

• Secure microservices with centralized zero trust
• Discover vulnerabilities with Google Tsunami
• Security analysis with Security Onion
• Pentest your web server with Nikto
• Passkeys eliminate the need for password-based authentication

Support Our Work

ADMIN content is made possible with support from readers like you. Please consider contributing when you've found an article to be beneficial.

Manage Azure Role Assignments Like a Pro with PowerShell

Today’s blog post is a little bit different. I have a couple of examples of how you can use PowerShell snippets and simple commandlets to get or set role assignmnets in your Azure Subscriptions.

PowerShell examples for managing Azure Role assignments

List all role assignments in a subscription, get all role assignments for a specific resource group, get all role assignments for a specific user, add a role assignment to a user, remove a role assignment for a user, remove all role assignments for a specific user, list all built-in roles, list all custom roles, create a custom role, update a custom role, delete a custom role, list all users or groups assigned to a specific role, list all permissions granted by a specific role, list all resource groups that a user has access to, create a role assignment for a service principal, powershell script to manage azure role assignments.

And now there is a script that combines some of these examples into one usable function:

I hope this was useful. Let me know if you liked the format of this blog and if you want me to include more of these examples.

Vukasin Terzic

Recent Update

• Writing your first Azure Terraform Configuration
• Transition from ARM Templates to Terraform with AI
• Getting started with Terraform for Azure
• Terraform Configuration Essentials: File Types, State Management, and Provider Selection
• Dynamically Managing Azure NSG Rules with PowerShell

Trending Tags

Retrieve azure resource group cost with powershell api.

The Future Of Azure Governance: Trends and Predictions

Further Reading

In my previous blog posts, I wrote about how simple PowerShell scripts can help speed up daily tasks for Azure administrators, and how you can convert them to your own API. One of these tasks is...

Azure Cost Optimization: 30 Ways to Save Money and Increase Efficiency

As organizations continue to migrate their applications and workloads to the cloud, managing and controlling cloud costs has become an increasingly critical issue. While Azure provides a robust s...

Custom PowerShell API for Azure Naming Policy

To continue our PowerShell API series, we have another example of a highly useful API that you can integrate into your environment. Choosing names for Azure resources can be a challenging task. ...

• Active Directory Reporting
• Office 365 Reporting
• Azure AD Monitoring
• Managing Azure AD Roles and Permissions with PowerShell

• August 24, 2023

Managing Azure AD Roles and Permissions with PowerShell. Do you need help managing and automating Azure AD Roles and Permissions with Windows PowerShell? This article explains the typical scenarios for automating Azure Role Based Access Control (RBAC) using PowerShell.

To lay the foundation and prepare to manage Azure roles and permissions, we start with an overview of Azure role-based access control (RBAC). Following that, we explain the three elements of role assignment.

There is also a section that explains the prerequisites for managing Azure AD roles and permissions with Windows PowerShell.

The next sections are dedicated to explaining the steps for assigning Azure AD roles using PowerShell. 

Finally, we explain how to list roles assigned to users and groups using PowerShell .

Also Read  Azure AD Privileged Roles: Manage & Monitor Privileged Access

What is Azure Role-Based Access Control (RBAC)

Azure role based access control (RBAC) allows administrators to do fine grained access control to resources . In other words, Azure RBAC allows admins to control who has access to resources.

Additionally, RBAC controls the level of access to resources in Azure.  

At the core of RBAC is role assignments. Azure has hundreds of built-in roles with pre-defined permissions that are assigned to users, groups, or service principals . 

The existence of built-in roles with pre-defined permissions makes role assignments easy, as admins do not have to grant permissions to objects directly. 

However, there are instances where the built-in roles may not be suitable for an organization’s needs. In this situation, custom roles are created. 

This article covers the steps to assign existing roles and also create and assign custom Azure AD roles. 

Azure Role Assignment Elements

Assigning role assignments involves 3 elements – security principal, role definition, and scope. The security principal is the Azure Active Directory object to be assigned the role.

On the other hand, the role definition is the built-in or custom Azure AD role that is being assigned while the scope is level the role is assigned. There are 4 scopes of that roles are assigned in Azure.

Specifically, Azure roles are assigned to a resource, a resource group, a subscription, and a management group. To assign a role to a resource, you require the resource ID.

However, assigning a role to a resource group scope requires the name of the resource group. Running the Get-AzResourceGroup command returns all resource groups, including their names in the current subscription.

If assigning a role at the subscription scope, you need the subscription ID. To list all subscriptions in the tenant, run the Get-AzSubscription command.

Finally, roles are assigned a management group scope which requires the name of the management group. To get the name of a management group, run the Get-AzManagementGroup command.

Understanding these elements is important to managing Azure AD roles and permissions  with PowerShell. In the remaining part of the article, we explore how the security principal, role definition, and scope are used to assign and manage roles in Azure AD using PowerShell.

Also Read  Deploy InfraSOS Office 365 Reporting & Auditing SaaS Tool

Try our Active Directory & Office 365 Reporting & Auditing Tools

Try us out for Free .  100’s of report templates available. Easily customise your own reports on AD, Azure AD & Office 355.

Prerequisites for Managing Azure AD Roles and Permissions with PowerShell

Before an admin assigns roles, they must meet the following requirements:

• The user must be assigned the roles with Microsoft.Authorization/roleAssignments/write permissions. Sole roles with this permission are User Access Administrator , Owner, or Global Administrator. 
• Secondly, you require access to Azure Cloud Shell or Azure PowerShell . 
• The user account running the PowerShell commands must have the the Microsoft Graph Directory.Read.All permission. 
• Finally, to perform some of the tasks in this article, your account requires a minimum Azure AD Premium P1 license .

As we progress in this article, we explain the steps to assign these permissions as required. 

Also Read  Azure AD Roles & Privileges: Azure AD RBAC Model

Steps to Assign Built-in Azure AD Roles Using PowerShell

I’ll be running the PowerShell commands in this and subsequent sections from Azure Cloud Shell , a browser-based shell that allows running Azure CLI or PowerShell commands . However, I’ll be running the commands from my computer. 

If you click the cloud shell link above and sign in with your Azure account, it displays a screen like the one in the screenshot below. The benefit of Azure Cloud Shell is that it does not require installing any PowerShell modules on your PC. 

Step 1: Determine the Object ID

You need to get the object ID before assigning a role to an Azure resource. Follow these steps to determine the object ID for a user, group, or subscription. 

1. Open the Azure Cloud Shell – shell.azure.com and sign in with your Azure account.

If you’re opening Azure Cloud Shell for the first time, it requires you to create a storage account.

2. Run the commands below to get the ID of the user or group you need to assign a role. In the first command, I an returning the ID of a user that begins with 

The first command saves the ID of the user in the userid variable, while the second one saves the group ID of the group to the grouped variable. Before running the commands remember to change the UserPrincipalName and the DisplayName. 

Also Read  Try InfraSOS Office 365 Reporting & Auditing Solution

Step 2: Get the Role to Assign

The next step for managing Azure AD roles and permissions with PowerShell is determining the role to assign. Start by listing all the available roles in your Azure AD tenant using the following command.

The command displays the Name , and Id of all roles in the tenant. Additionally, it returns True or False in the IsCustom column. 

To demonstrate, I want to assign the Security Admin role to the user and group I determined in Step 1. To display the name of the role, I pipe the output of the Get-AzRoleDefinition command to Where-Object as shown in this command. 

Step 3: Identify the Role to Assignment Scope

The command below returns the ResourceID of a storage account (resource scope) and saves it in the ResourceID variable. 

Later, I assign the user in step 1 the “Security Admin” role in this storage account resource. 

Also Read  Azure AD Role-Based Access Control Best Practices: How to Use Azure AD Roles and Privileges Effectively

Step 4: Assign the Azure Role

Using the information in steps 1 to 3, run the command below to assign the role to the user . Before running the command, the role is not assigned to this storage account, as shown in the screenshot below. 

The first command assigns the “Security Admin” role to a user saved in the $userid variable. Similarly, the second command assigns the same role to a group saved in the $groupid variable. 

After running the above commands, refreshing the storage accounts displays the Security Admin role, and the user and group assigned the role. 

Also Read  Implement Azure AD Role Based Access Control Policies

Display Azure AD Role Assignment Using PowerShell

Earlier, I assigned the “Security admin” role to a user with UPN, [email protected]. If you recall,  the userId for the user was saved in the $userid variable. 

Similarly, the scope ID of the storage account was saved in the $scoperesourceID variable. To display the role assignment for the user, I run the command below. 

The command displays the role assignment details, including the RoleAssignmentName, and scope. 

You display the same information for the group by running this command. 

Also Read  Try InfraSOS Azure AD Reporting & Auditing Tool

Managing Azure AD Roles and Permissions with PowerShell Conclusion

Administering Azure roles requires knowledge of the role based access control model . Additionally, understanding Azure role assignment elements – security principal, role definition, and scope – is essential to manage role assignments with PowerShell effectively. 

Not only that, but an account assigning roles has to meet some prerequisites such as such as configuring PowerShell with the required modules and ensuring appropriate administrative privileges.

The step-by-step guide provided in this article offers a clear roadmap to follow when assigning built-in Azure AD roles using PowerShell. From determining the Object ID to identifying the scope for role assignment, each stage is meticulously outlined, facilitating a seamless and controlled role allocation process.

Try InfraSOS for FREE

Try InfraSOS Active Directory, Azure AD & Office 365 Reporting & Auditing Tool

• Free 15-Days Trial
• SaaS AD Reporting & Auditing Solution

Related posts:

• Azure AD Roles and Permissions: Assign & Manage Roles for Users & Groups
• Office 365 Identity & Access: Manage Users & Permissions
• Azure AD Custom Roles: Create & Manage Custom Roles for Azure AD
• Azure AD Privileged Roles: Manage & Monitor Privileged Access
• Azure Storage Security: Secure Accounts with Encryption & Access Policies

• Victor Ashiedu
• No Comments

Leave a comment Cancel reply

Your email address will not be published. Required fields are marked *

Save my name, email, and website in this browser for the next time I comment.

Stefanos Cloud

How to manage Microsoft 365 user role assignments and administrative units

• Role assignments
• Administrative Units

This article provides guidance on how to manage Microsoft 365 user role assignments and administrative units. The article is also available on my podcast and Youtube channel .

View this article as a how-to video on Youtube.

You need to manage existing user roles, create new custom user roles and assign users and groups to existing roles in Microsoft 365 . You need to also manage Microsoft 365 administrative units.

In this how-to article, we will show you how to manage Microsoft 365 user role assignments and administrative units.

Role assignments #

From within the Microsoft 365 Admin Center portal, you can assign ‎ Azure AD‎ built-in roles to users who need access to other admin centers and resources in ‎ Azure Active Directory‎, such as users, groups, and apps which use ‎Microsoft Graph‎ API. The following groups of user role assignments can be made from the Admin Center portal.

• Azure AD role assignments
• Exchange Online role assignments
• Intune role assignments

In the next steps, we will show you how to assign the Global Administrator Azure AD role to a user and group. Follow the steps below to assign the Global Administrator role to a user or group.

• Navigate to https://admin.microsoft.com and authenticate as a global admin user.
• On the left pane, expand the "Roles" section and click on "Role assignments". On the main section click on the "Global Administrator" role. On the popup form on the right, you should be able to review the general properties of the role in question. On the permissions tab, the system lists details of the permissions which are assigned with the role in question.
• On the "Assigned" tab, you can assign users or groups to the role in question. Click on "Add Users" and then "Add Groups" to add a user and group respectively to the specific role.
• To run the Azure portal as a specific Azure AD user role, tick on the checkbox next to the role and click "Run As". This will show you the view of the Azure portal as if you had logged in via a user with the role in question.
• To compare permissions of user roles, tick on two or more roles and then click on "Compare Roles". In the next screen, you should see a tabular comparison of the permissions assigned to each of the compared roles. You can also click on "Export comparison" to export the comparison matrix of the selected roles.

In the next steps, we will show you how to assign the Or gan ization Management Exchange Online role to a user and group, as well as how to create a new custom Exchange Online role. Follow the steps below.

• Navigate to the "Exchange" tab under the "Role Assignments" section.
• Click on the "Or gan ization Management" role. On the popup form on the right, you can review the general settings of the role under the "general" tab. Under the "Permissions" tab, you can review in detail the available permissions of the role in question.
• Under the "Assigned" tab, you can assign a user or group to the role in question. Click "Add" and choose the user or group to assign to the role.
• You can also create a custom Exchange Online role by ticking the checkbox next to the role which will be used as the template for the new role. Then click on "Copy role group". This will take you to a wizard to create your new custom role. On the "Set up the b asic s" page, fill-in the name, description and write scope of the new role and click Next.
• Select the roles to add to the ‎new custom role group. Roles define the scope of the tasks that the members assigned to this role group have permission to manage.
• Select the users to assign to this role group. They'll have permissions to manage the roles that you assigned in the previous step.
• Review your selections and click Finish.

In the next steps, we will show you how to assign Intune roles. Assign ‎Intune‎ roles to specialists who need to view or manage ‎Intune‎ data, devices, or services. These roles can only be assigned to users who have a license that includes ‎Intune‎. Follow the steps below.

• Under the "Role assignments" section, navigate to the "Intune" tab. If you need to export existing assignments, click on the "Export assignments" button.
• Click on the Intune role you wish to edit assignments of. On the "General tab" you can review the general settings of the role in question. On the "Permissions" tab you can see in detail all permissions of the role in question.
• To assign users to the Intune role, under the "Assigned" tab click on "Add". This will take you to the "Set up the b asic s" wizard. Fill-in a name and description and click Next.
• Select the security groups that contain the users you want to become admins for the role. Click Next.
• Select a built-in security group like 'All users', or search for and select security groups which contain the users and devices that the ‎Intune role can manage.
• You can optionally add tabs which limit the specific Intune policies, apps and devices that the admins can see. Click "Next".
• Review all your assignment settings and click "Finish".

Administrative Units #

Now we will move on to show you how to create and manage Microsoft 365 Administrative Units. Units let you sub-divide your or gan ization into any unit that you want, and then assign specific administrators that can only manage that unit. For example, you can assign the Helpdesk Administrator role to a regional support specialist, so they can manage users only in that region.

Carry out the following steps:

• Under the "Roles" section, click on "Administrative Units". Click on "Add Unit" to add a new administrative unit.
• Provide a name and Description of the new administrative unit and click "Next". Administrative units let you limit admins to manage users for a specific department, region, or any segment that your or gan ization defines. Start by giving the administrative unit a name and description that will let other admins know its purpose.
• Choose "Add up to 20 users and groups" or "Upload users" if you need to bulk upload a large number of users to be linked to the new administrative unit. If you choose "Add up to 20 users and groups", then click on "Add Users" or "Add Groups" to add the desired users to the administrative unit and click Next. The administrators assigned to this unit will manage the settings for these users and groups. Adding groups doesn't add users to the unit, it lets the assigned admins manage group settings. You can only add up to ‎20‎ members individually or you can bulk upload up to ‎200‎ users. If you need to add more, you can edit this unit to add them.
• Assign admins to scoped roles. The following roles are the only roles that support administrative units. Authentication Administrator Cloud Device Administrator Groups Administrator Helpdesk Administrator License Administrator Password Administrator SharePoint Administrator Teams Administrator Teams Device Administrator User Administrator.

Select a role and then assign admins to it. The admins that you assign to roles in this step will manage the members of this administrative unit.

• Review your selections and click "Finish". The new administrative unit has been created. You can always edit its properties by clicking on the Administrative Unit name. From that page you can edit the administrative unit's members and role assignments.
• You can also edit the name and description of an administrative unit by ticking the checkbox next to the administrative unit name and clicking on "Edit name and description".

What are your Feelings

Share this article :, how can we help.

Powered by BetterDocs

Get-ManagementRoleAssignment

Module: ExchangePowerShell

Official Documentation: https://learn.microsoft.com/en-us/powershell/module/exchange/get-managementroleassignment

Back to the module overview  |  Back to the list of cmdlets

The Get-ManagementRoleAssignment cmdlet in PowerShell is used to retrieve the management role assignments in an Exchange organization. It allows administrators to view the roles assigned to individual users or groups within the organization. Without providing an example, the cmdlet retrieves the existing management role assignments by querying the Exchange organization's configuration data. It retrieves information such as the user or group to whom the role is assigned, the assigned role(s), and the scope at which the assignment applies. The Get-ManagementRoleAssignment cmdlet is typically used in conjunction with other cmdlets to manage and monitor role assignments in an Exchange environment.

Some code snippets about this cmdlet from our scripts:

. $PSScriptRoot\00_Configuration.ps1 $allRoles = Get-ManagementRoleAssignment -GetEffectiveUsers | Where-Object {$_.EffectiveUserName -eq $migAdminUserName } | select-object Role -Unique $allAssignees = Get-ManagementRoleAssignment -GetEffectiveUsers | Where-Object {$_.EffectiveUserName -eq $migAdminUserName } | select-object RoleAssigneeName -Unique $orgRole = $allAssignees | Where-Object { $_.RoleAssigneeName -eq "Organization Management" } if (-Not $orgRole) Connect-ExchangeOnline -ShowProgress $true $allRoles = Get-ManagementRoleAssignment -GetEffectiveUsers | Where-Object {$_.EffectiveUserName -eq $migAdminUserName } | select-object Role -Unique $allAssignees = Get-ManagementRoleAssignment -GetEffectiveUsers | Where-Object {$_.EffectiveUserName -eq $migAdminUserName } | select-object RoleAssigneeName -Unique $orgRole = $allAssignees | Where-Object { $_.RoleAssigneeName -eq "Organization Management" } if (-Not $orgRole)

This Cmdlet is used in following scripts:

• \scripts\exchange\publicFolderMig\01_Check-MyOnPremRole.ps1
• \scripts\exchange\publicFolderMig\11_Check-MyOnlineRole.ps1

This page was generated automatically and may contain errors. It does not claim to be complete or correct. All information without guarantee.