exchange remove management role assignment

How To Add Or Remove Cmdlet Parameter From RBAC Management Role

In the previous posts on RBAC we have looked at customising various roles to ensure that the role contained the minimum amount of cmdlets.  RBAC provides even more granularity, and we can add or remove specific parameters from a cmdlet.  Since some folks asked for examples on this topic here are a couple of quick examples and some considerations….

If you want to use ECP, please read all the way down to the bottom.  The initial examples will work with the Exchange Management Shell but there are a couple of extra considerations for ECP.

Setting The Stage

As a scenario, let’s invent a crappy work task that some unlucky person could be asked to perform.  Let’s say there is a mobile phone management team within a large business and their sole responsibility is to assign mobile phones and numbers to people.  As part of this they need to be able to update the MobilePhone property of all users.  They should not be  able to modify any other attributes at all.

The cmdlet that we want is Set-User   and the MobilePhone parameter.

Locate The Cmdlets

This section builds and creates the custom RBAC role that we will use.  Firstly lets see where the relevant cmdlets and parameters live!

We can use the Get-ManagementRole cmdlet to see where the cmdlet lives using the -Cmdlet and -CmdletParameters respectively.  Below we can see where both the Set-User and MobilePhone exist:

Since the Set-User with the MobilePhone parameter exists in the Mail Recipients role, let’s use that role.  As before the built-in roles are read only and we cannot make any changes to them.  So we need to make a copy of the role, and since this copy is writable we can make the necessary changes.  Our custom role will be called Mobile-Phone-Jockeys .

If we check the contents of our new Management Role, we will see that it contains all the cmdlets and parameters present in the original parent role – not surprising since it was a copy….

We need to remove all the cmdlets that we do not want, so the quickest way to do this is to get a list of cmdlets that do not match Get-User and then once we check the list, remove them.

Note: Always check the objects returned are as expected prior to piping to the remove cmdlet!

So in this case we would run:

Only when we are happy with what is returned should we run:

If we check to see what’s now in the Mobile-Phone-Jockeys Role, it only contains the Get-User cmdlet.

Add A Single Parameter

At this point the Get-User cmdlet is the only entry left in the Management Role.

Let’s add back the Set-User cmdlet, with *ONLY* the ability to set the MobilePhone parameter, and the identity parameter.

This is a great example of adding in a specific parameter, when the cmdlet did not already exist.

If you are wondering about the Identity parameter that is also present with MobilePhone , keep reading!

Add Multiple Parameters

Taking the example above we could have specified multiple parameters in the same command.  if we deviate from the example above slightly and pretend that our Mobile-Phone-Jockey role has now become responsible for also assigning office phones then they need to also set the Phone attribute.  You can specify multiple parameters, separated with commas.

Changing Existing Parameters

If we want to go about modifying a cmdlet’s list of parameters, a good guess would be that we would use the Add-ManagementRoleEntry or Remove-ManagementRoleEntry but neither will do what we need.  They just add or remove the entire Management Role Entry.  In the case of changing the available parameters on an existing role entry we need to use the Set-ManagementRoleEntry cmdlet.  Its Parameters switch has the following modes:

• When used with the AddParameter parameter, the parameters you specify are added to the role entry.
• When used with the RemoveParameter parameter, the parameters you specify are removed from the role entry.
• When neither the AddParameter nor RemoveParameter parameters are used, only the parameters you specify are included in the role entry. If you specify a value of $Null and neither the AddParameter nor RemoveParameter parameters are used, all of the parameters on the role entry are removed.

So if we want to remove all parameters from the Set-User cmdlet apart from MobilePhone and Identity we could run:

An alternative would have be to remove just the Phone parameter:

The end result is the same in this case, and you can choose the  method that makes the most sense!

Want To Live Like Common People

< Common People courtesy of Pulp >

One interesting thing to note is that when we try to prune out the parameters that we do not want, the common ones should typically be left.  They are needed to ensure that we can perform the basic aspects of the cmdlet.  This includes parameters like WhatIf, DomainController or Verbose.  None of these apply changes to a mailbox or user, but they allow us to control how the operation is performed.

Trying to see them can be a little tricky.  Look at the truncated display here indicated by the three periods:

To review all the parameters present in a Management Role Entry I like to do the following:

$Params.Parameters  will output the entire content of the attribute to the screen. If we split the  output to see what parameters are the common ones and what are specific to the Set-User cmdlet we will see:

Specific Parameters

AssistantName, CertificateSubject, City, Company, CountryOrRegion, Department, DisplayName, Fax, FirstName, HomePhone, Initials, LastName, Manager, MobilePhone, Name, Notes, Office, OtherFax. OtherHomePhone, OtherTelephone, Pager, Phone, PhoneticDisplayName, PostalCode, PostOfficeBox,  ResetPasswordOnNextLogon, SamAccountName, SeniorityIndex, SimpleDisplayName, StateOrProvince,  StreetAddress, TelephoneAssistant, Title, UserPrincipalName, WebPage, WindowsEmailAddress

Common Parameters

Confirm, Debug, DomainController, ErrorAction, ErrorVariable, Identity, IgnoreDefaultScope, LinkedCredential, LinkedDomainController, LinkedMasterAccount, OutBuffer, OutVariable, RemotePowerShellEnabled, Verbose, WarningAction, WarningVariable, WhatIf

Why is this worth mentioning, well if the necessary common parameters to run cmdlet are not present then it does not run, savvy?

If Identity is not specified for the Set-User cmdlet then you are going to see this fun error:

The operation couldn't be performed because object 'test-6' couldn't be found on 'exch-dc.tailspintoys.com'. + CategoryInfo          : NotSpecified: (0:Int32) [Set-User], ManagementObjectNotFoundException + FullyQualifiedErrorId : 98454A26,Microsoft.Exchange.Management.RecipientTasks.SetUser

Why can we not find the account? It is clearly there as we can see with the first command Get-User.

The identity parameter is not present on the Set-User cmdlet in the custom Management Role. This can be a little confusing as we can type "Set-user -Identity" so where is the Identity parameter coming from?   Note that the –identity parameter is visible since it is present within the Role Assignment Policy.  Role Assignment Policy is just for end user RBAC and is scoped to the individual user thus it cannot be used to modify other users. When we want to modify a user account that is not our own the Role Assignment Policy does not apply as it does not fall within  the scope of 'SELF", and we look to the other Management Role which is Mobile-Phone-Jockeys in this case.  Since Mobile-Phone-Jockeys does not have the Identity parameter the command fails to change the properties of user account Test-6".

Morale of the story?  Be sure to include the necessary common parameters else you will get some “interesting” results…

Testing time, and arguable the most important section!!   Let’s assign the Mobile-Phone-Jockeys management role to a test user called User-15.

And to confirm the Mobile-Phone-Jockeys management role contains:

Testing via Exchange Management Shell on User-15’s Windows 7 x64 desktop shows that RBAC is working and they can modify the Mobile number for a separate user (Test-6):

Happy days?  Well almost…

You think you are done, and the testing was OK.  But then you get a call saying that  ECP cannot be used, as the option to view other mailboxes is not present.  Huh?  Are the permissions not correct?  Permissions are correct as we tested them, so what gives?  This is what User-15 sees in ECP, note there is no Manage My Organization option along the top, and the shortcut on the right pane does not take us their either.  The shortcut has this link:

https://mail.tailspintoys.com/ecp/PersonalSettings/HomePage.aspx?showhelp=false&#

How to fix this? We need to make ECP display the Manage My organization option.  We do this by adding cmdlet(s) that will force the option to be displayed, and the in this case we will add Get-Mailbox and Get-Recipient .  Lets add them in:

With the modified Management Role Entries, User-15 now sees:

Note that the Manage My Organization is visible, and so are the mailboxes in the organization. The shortcut to Manage your organization link now takes us to the organization management page in ECP .

Double clicking to edit one shows that that User-15 has the permissions to edit the Mobile Phone field as it is not locked out.  Fields in grey are locked out.

Concluding Thoughts

We can see that RBAC allows for a great deal of customisation, right down to the individual parameters that are available!  This is an amazing amount of flexibility, and there is one glaring thing that should be striking Exchange 2003 and 2007 admins at this point.  Did we change a single ACL to the objects in AD?  NO!  Not a single one.  We focussed on the business requirement, which was to allow the phone team to update the mobile number assigned to users, and did not have to think about ACLs.  This is a huge win as having to get change records cut to modify AD ACLs is a challenge.

This is made possible by the Exchange Trusted Subsystem universal security group as it is that group that has the permissions to the AD objects.  RBAC enforces and controls the cmdlets and parameters that you can see and thus use thereby controlling what changes are made to the Exchange objects.

Rhoderick Milne [MSFT]

Leave a reply 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.

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 PowerShell: Flow Control

In this edition of Practical PowerShell, Michel De Rooij discusses the code flow constructs available in PowerShell regarding looping and how to use them.

Restricted SharePoint Search is The Legacy of Previous Microsoft Collaboration Strategies

Microsoft has been forced to introduce restricted SharePoint search to allow customers to deploy Copilot for Microsoft 365 projects without worrying that Copilot will find and reuse information from across the entire tenant. It's a sad legacy of previous Microsoft collaboration strategies, notably the decision to allow users to create groups without hindrance.

• SharePoint Online

Migrate from EWS Application Access Policy to RBAC for Applications

On February 20, Microsoft announced their intention to remove Application Impersonation for EWS from Exchange Online. If you have existing management role assignments, this article explains how to make the transition to RBAC-based assignments.

• Exchange Online

This browser is no longer supported.

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

Remove-Role Assignment Policy

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 Remove-RoleAssignmentPolicy cmdlet to remove existing management role assignment policies from your organization.

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

Description

The assignment policy you want to remove can't be assigned to any mailboxes or management roles. Also, if you want to remove the default assignment policy, it must be the last assignment policy. Do the following before you attempt to remove an assignment policy:

• Use the Set-Mailbox cmdlet to change the assignment policy for any mailbox assigned the assignment policy you want to remove.
• If the assignment policy is the default assignment policy, use the Set-RoleAssignmentPolicy cmdlet to select a new default assignment policy. You don't need to do this if you're removing the last assignment policy.
• Use the Remove-ManagementRoleAssignment cmdlet to remove any management role assignments assigned to the policy.

For more information about assignment policies, see Understanding management role assignment policies .

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 removes the role assignment policy named End User.

Find all mailboxes that have the End User policy assigned to them.

Assign a different role assignment policy to the mailboxes. The example uses the policy named Seattle End User.

Remove all management role assignments that are assigned to the End User policy.

Remove the End User role assignment policy.

For more information about the Where cmdlet and pipelining, see Working with command output and About Pipelines .

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.

-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.

The DomainController parameter isn't supported on Edge Transport servers. An Edge Transport server uses the local instance of Active Directory Lightweight Directory Services (AD LDS) to read and write data.

The Identity parameter specifies the assignment policy to remove. If the assignment policy name has spaces, enclose the name in quotation marks (").

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

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 Organization 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 "Organization 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 basics" 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 basics" 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 organization 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 organization 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

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

All about Microsoft 365

Remove user from all Microsoft 365 groups and roles (and more) via the Graph API (non-interactive)

The script to remove users from all groups across Microsoft 365 has been one of the more popular entries in my GitHub repo for a while now. It is also generating a lot of improvement requests, the most common one being to be able to run the script in an automated fashion. I can certainly understand the desire and use cases for a fully automated solution, but at the same time I am always a bit reluctant to recommend and support such approach, due to the greater potential of unwanted changes being performed. And considering the script allows for bulk execution, it has some resume-generating potential 🙂

With that in mind, I always advertise a more cautious approach and try to include a lot of additional/verbose information for my script samples, as well as leverage PowerShell’s ShouldProcess where it makes sense. We will follow the same approach in this article, where I will introduce you to a new version of the script, with support for automated execution. But that’s just one of many improvements made, so let’s dig in!

The script now leverages the Graph API

The new script uses the Graph API methods, which has some pros and cons. The biggest downside of going the Graph route is that it has almost no support for Exchange objects and operations. Thus, while the Graph will happily return you a list of groups that includes Exchange distribution groups and mail-enabled security groups, it will refuse to make any changes to such objects. For that reason, the script also leverages Exchange Online methods, but more on that a bit later. Another downside is that the Graph almost exclusively works with GUIDs, and you can rarely use any human-readable identifier.

In terms of pros, the Graph API certainly performs faster compared to Exchange Online, in most cases. It allows you to use a unified endpoint and methods to work across a variety of objects, i.e. you don’t have to use one method to remove a member from Security group and another one for Microsoft 365 Groups. It also gives you “fuller” picture, as Exchange Online only cares about mail-enabled (recipient) objects.

Another pro, or an inconsistency if you will, comes from the way Graph processes Microsoft 365 Group members. Unlike the Exchange Online cmdlets, it will happily allow you to remove a given user from the group’s membership list, even if said user is designated as an Owner as well. Both APIs will prevent you from removing the last Owner of an M365 Group though, thus the script allows you to designate a “substitute owner” in order to address such scenarios. Due to “owner” having a different meaning in Exchange Online, the script will not make any “ownership” changes to Exchange objects though!

Anatomy of the script

Let’s describe the anatomy of the script. Two thirds of the code is taken by helper functions that help us handle various tasks, such as processing the input or handling errors. Within the “main” section of the script, we first handle authentication, then proceed with validating the input values. As the script supports bulk processing, we want to get  rid of any duplicate values, as well as remove entries that do not correspond to a valid object within the organization. After that, the script will process each user.

In order to fetch the membership of the user, we call the Graph’s memberOf method, which has the added benefit of also returning any Directory role and Administrative unit the user is assigned to. So, it’s only natural for the script to support removal from such as well. Extending this approach, the script will also make a call to the ownedObjects method and fetch all directory objects “owned” by the user. This in turn allows us to remove any “owner” assignments from group , application and service principal objects. The “substitute owner” value is also validated at this point. Do note that we only leverage it for group ownership.

As already mentioned above, the script will also make calls to Exchange Online in order to remove the user from distribution and mail-enabled security groups. So why not also remove the user from any Exchange role assignments then? Boom, done! While there is certainly more we can do on the Exchange front, tasks like removing mailbox- or folder-level permissions are best handled with dedicated script instead, so for this version at least, the script will only remove Exchange group and role group membership, as well as any direct role assignments.

To finish up on the privileged access scenarios, the script will also process any scoped Directory role assignments. This type of role assignment is however not returned by the memberOf call. While we can leverage the scopedRoleMemberOf endpoint instead, the only way to remove scoped assignments is via the PIM methods , which is what we end up with. This has the added benefit of also allowing us to cover any e ligible role assignments. We can also handle PIM Groups in similar way, however the corresponding LIST method does not seem to work correctly with filters based solely on the user ID, which is unfortunate. We can iterate over each PIM group instead, but that’s just stupid… so support for this scenario will have to wait until Microsoft fixes the filtering capabilities.

Roles are however not the only way a user can get access, so the script will also go over any delegate permissions granted to/by the user and remove them. This is done by leveraging the /user/{userId}/oauth2PermissionGrants endpoint to get any potential grants, then removing them via the directory-wide /oauth2PermissionGrants endpoint. Do have in mind that this does not cover delegate permissions for which an admin has granted tenant-wide consent.

While the script does support unattended execution, we’ve still made sure that it can output a report of any changes made, so the rest of the script is dedicated to helper functions, error handling and handling the output. Nothing fancy really, but once you add all these bits together, you end up with 900 lines of code. Sheesh!

Parameters and permission requirements

Here is the set of parameters the script supports:

• Identity – A comma-separated list of users to process. Only GUIDs and UPNs are supported. Mandatory.
• Exceptions – A comma-separated list of directory objects to exclude from processing. GUIDs only. Maximum of 1000 entries are supported, as we use a single call against the getByIds method to validate the values. This in turn means that only objects supported by said call can be excluded!
• ProcessOwnership – Switch parameter, indicates whether to remove the user from any “ownership” assignments.
• SubstituteOwner –  The UPN or GUID of the user to use as a substitute owner for groups where the user we are removing is the only owner.
• ProcessExchangeGroups – Switch parameter, indicates whether to perform operations against any Exchange groups and roles. Comes with additional permission requirements (more details below).
• ProcessOauthGrants – Switch parameter, indicates whether to remove any delegate permission grants for the user.
• IncludeDirectoryRoles – Switch parameter, indicates whether to remove the user from any Entra ID Directory roles he is currently assigned to. Requires RoleManagement.ReadWrite.Directory permissions. Can be combined with the – ProcessExchangeGroups switch to ensure removal from any Exchange Online roles, too.
• IncludeAdministrativeUnits – Switch parameter, indicates whether to remove the user from any Administrative units .
• Quiet – switch parameter, used to suppress output to the console window.

In addition, the script supports the set of “common” parameters, such as – Verbose , – WhatIf , – OutVariable , etc. More importantly, it supports PowerShell’s “risk management” parameter, – Confirm . I know, I know, it breaks automation. Still, it’s important to have it when needed. I’d even recommend always using – Verbose as well, as it gives you a lot more context. By default, no confirmation will be required, so you can still execute the script without any interaction.

Before we move on to examples on how to run the script, we need to discuss authentication and permission requirements. As we want the script to run without any interaction, we leverage the client credentials flow. Thus, application permissions are required (as opposed to delegate permissions). For best results with “get” operations, the Directory.Read.All role is recommended. For removal, Directory.ReadWrite.All will do, but you still need Application.ReadWrite.All if you want to remove Owner assignments for application objects and RoleManagement.ReadWrite.Directory for managing directory role assignments. If you want to go granular (and you should!), you’d need the following:

• Group.ReadWrite.All for removal of group members/owners (mandatory)
• RoleManagement.ReadWrite.Directory for removal of Entra ID role membership (only needed if you use the IncludeDirectoryRoles switch)
• DelegatedPermissionGrant.ReadWrite.All for removal of delegate permission grants (only needed if you use the ProcessOauthGrants switch)
• AdministrativeUnit.ReadWrite.All for removal of AU membership (only needed if you use the IncludeAdministrativeUnits switch)
• Application.ReadWrite.All for removal of application/service principal owners (only needed if you use the ProcessOwnership switch)
• Exchange.ManageAsApp and the Exchange administrator role assigned to the service principal (needed for processing Exchange objects)

Read the next section and the references therein for details on how to grant granular permissions for Exchange scenarios.

How to run the script

OK, now that you understand what the script does, you can download it from GitHub . Make sure to configure the required variables (lines 707-709) and that the application used has been granted all the required permissions. For example, here are the permissions I used when testing the script:

To better illustrate how the script works, our first example will leverage (almost) all its parameters. Adding the – Verbose switch will cause it to spill detailed information as it progresses, so we can get a clue about its inner workings. And, the – WhatIf switch will ensure that no changes are actually committed. It also has the added benefit of generating a “report” of all the relevant permission our selected user(s) have. And yes, the script supports bulk processing, so we can enter a list of GUIDs or UPNs:

On the screenshot above, we’ve highlighted few important bits. First, the Identity values were resolved, invalid entries and duplicates removed. Same for the SubstituteOwner value. Next, an eligible Directory role assignment has been detected, before processing Exchange role assignments. Ownership and membership is processed next (output is trimmed), before moving to the next user. Here, ownership of an application object is found. Lastly, an exception is encountered. At the end of the run, the output is dumped to the console and a CSV file, allowing you to review all the “access” info.

I would strongly recommend running the script few times with – Verbose and – WhatIf switches, until you are familiar with it. Even then, I’d still recommend always using the – Confirm switch, as the script will NOT ask for confirmation otherwise! And, as it only terminates on errors related to missing permissions, a whoopsie can be costly. Just saying.

Without further ado, here is how you can run the script in a fully-automated manner:

If you do not specify the – Quiet parameter, output will still be dumped to the screen even in this scenario. Which gives us the opportunity to address few more things. First, when users are added to roles such as Exchange admin or Security reader, on Exchange Online’s side of things this is “translated” into membership of “managed” role groups. There is no good way to filter out such entries, unless you want to hardcode the group names, so we process them instead. As you cannot process any Exchange roles without doing Directory roles first, this should not be a problem – removing the Entra ID role membership will ensure the membership of the Exchange role group is also updated (hence the warning).

Another thing to note on the screenshot above is processing the scenario where the user is the sole owner of a group. As we use the – SubstituteOwner parameter, the removal operation is retried only after we add the designate “substitute owner”. Thus, we get the “Owner add” entry in the output as well. This logic applies only to the removal of owners of security groups and Microsoft 365 Groups, no other objects!

As mentioned above, output is also exported to a CSV file. This happens regardless of the parameters you invoked the script with, so you have a proper record of any changes that were made (or failed to be made). So as our next example, here’s how to run the script non-interactively and without any additional output (just the CSV file).

While there isn’t much to show as a output from this example, we can still leverage the resulting CSV file, where all the changes should be diligently noted. I’ve tried to use human-readable identifiers where possible, but you might see a GUID every now and then, mostly because I didn’t want to include any additional Graph API calls to resolve such. Whenever we try to make a change in the ownership of some object, its name will be prefixed with “[Owner]” and we’re also adding “owner” string to the Result column. Some of the directory role entries will also have a prefix, which uses the “[ scope]: roleId ” format. As role assignments can be scoped to AUs or even individual objects, I thought this is important information to display. Thus a “[/]” prefix indicates directory-wide assignment, “[/GUID]” indicated application-scoped one, and so on. Oh, and as roleId cannot be resolved by a call to the getByIds method, I again decided against making additional calls… enjoy those GUIDS!

Lastly, for the sake of completeness, and to justify the name of the script, here’s how to run it to simply remove a given user from any groups he is in:

And because I know I will inevitably get this asked, here’s how to use a CSV file as input:

Additional notes

So now that we know what the script does and run some examples, let’s also talk about what the script does NOT do. It does not process or remove any of the following:

• AppRole assignments – I simply do not consider them important enough.
• PIM eligible group membership – this one I do consider important enough, however the corresponding Graph API endpoints currently have some issues and the workaround requires iterating over all PIM provisioned groups… which is something I want to avoid.
• Exchange mailbox-level permissions (Full access, send as, send on behalf of) – again important, but falls into the “avoid” category. Use dedicated scripts instead.
• Exchange folder-level permissions – as above, inefficient. Use dedicated scripts instead.
• Site/file level permissions – even more inefficient.
• Device ownership (and registered devices) – this one I’m not so sure about… it’s relatively easy to address – let me know if you consider it important!
• Dynamic groups – instead of outright skipping them, should we do something else?
• Access packages – lots of things can be done via Entitlement management, good suggestion for future improvements.
• Teams RSC permission grants – easy enough to get… just not sure if important enough to consider.

The above list reminds me of another point – we do not explicitly address group-based Directory role assignments. Such are not directly returned via the /memberOf query, but we can cover them via the PIM endpoints. As however we already remove the user from all groups, privileged ones included, this scenario should already be covered. Let me know if my logic is faulty on this!

While the Graph API does have some support for Exchange Online role assignments now, said functionality is only available under the /beta endpoints. Moreover, it only allows for management of direct role assignments, as it does not currently support management of Exchange Online Role groups. In other words, you cannot use the Graph API to remove a role that is made available to the user thanks to its membership to a Role Group, unless you want to remove the assignment completely, and cause all other members of the Role Group to lose access. For this reason, we stick to using the good old Exchange cmdlets instead.

The requirements for using Exchange Online’s InvokeCommand endpoint closely resemble those for accessing Exchange Online PowerShell via app-only authentication , albeit if you have already created an app registration to leverage the Graph API, you can skip some of the steps. Do make sure to assign the necessary permissions though: the Exchange.ManageAsApp role and either an Entra ID admin role or Exchange Online Role group with sufficient permissions to perform the removal operations. At minimum, access to the Remove-DisitrbutionGroupMember cmdlet is required. As the script can also be used to remove Exchange Online management role assignments, both the Remove-ManagementRoleAssignment and Remove-RoleGroupMember cmdlets might also be called.

The script assumes that you will be leveraging a single service principal for performing both the Graph API and Exchange Online REST API operations. This is not a hard requirement, though it simplifies the connectivity block a bit. As an added benefit, using a single service principal can relax the permission requirements a bit, at least when using Entra ID roles. On that note, be warned that the script does not validate the access token(s) for the presence of the relevant permissions. Which means that the removal operation will be tried regardless, and will fail if permissions have not been granted. The script has some error handling that should detect such scenarios and terminate any further processing, but I’m sure there are many corner cases that it does not account for.

One more note on permissions. As we are leveraging the application permissions model, assigning an Entra ID role to the service principal enables our app to run queries against the Graph API, without explicitly granting consent to say Directory.Read.All . For example, while testing the script I had the Exchange administrator role assigned to the SP, which allowed him to remove Microsoft 365 Group members and owners without any additional grants. In production scenarios however you should be following the principle of least privilege, so consider using (custom) Role groups instead.

Another thing to mention here is that the script leverages the client credentials flow to obtain an access token, in other words requires you to enter a client secret value. DO NOT use this approach in your own solution! Make sure to replace the connectivity bits with your own preferred method instead. At the very least, do not store any credentials in plain text. Better, use a certificate to obtain the access token. And never trust a piece of code you’ve downloaded from the Internet 🙂

As always, do let me know if you find the script useful, any issues you run into and send me any potential improvement suggestions.

1 thought on “ Remove user from all Microsoft 365 groups and roles (and more) via the Graph API (non-interactive) ”

• Pingback: Microsoft Roadmap, messagecenter en blogs updates van 26-04-2024 - KbWorks - SharePoint & Teams Specialist

Leave a Reply 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.

This site uses Akismet to reduce spam. Learn how your comment data is processed .

Contribute to the Microsoft 365 and Office forum! Click  here  to learn more  💡

April 9, 2024

Contribute to the Microsoft 365 and Office forum!

Click  here  to learn more  💡

• Search the community and support articles
• Microsoft 365 and Office
• Search Community member

Ask a new question

How can I create a new admin role group with ApplicationImpersonation permission?

I am attempting to create a new role group with ApplicationImpersonation permissions per https://answers.microsoft.com/en-us/msoffice/forum/all/exchange-impersonation-error-unable-to-open-user/834c4ea9-6cb5-4df4-9011-433ba501f6d2 .

When I do so in https://admin.exchange.microsoft.com/#/adminRoles I click Add role group, then name it CloudMigratorImpersonation with default write scope.

Next I add ApplicationImpersonation and Mailbox Import Export permissions, and attempt to assign myself (global admin) to the new role group.

When I click Add Role Group, I get:

Error executing request. You don't have access to create, change, or remove the "professionalartists.onmicrosoft.com\ApplicationImpersonation-CloudMigratorImpersonation" management role assignment. You must be assigned a delegating role assignment to the management role or its parent in the hierarchy without a scope restriction.

Report abuse

Reported content has been submitted​

Replies (1) 

• Microsoft Agent |

Dear Ryan Link1, Good day!

Your understanding and cooperation are greatly appreciated. wish you all the best.

Winter| Microsoft Community Moderator

Was this reply helpful? Yes No

Sorry this didn't help.

Great! Thanks for your feedback.

How satisfied are you with this reply?

Thanks for your feedback, it helps us improve the site.

Thanks for your feedback.

Question Info

• For business
• Norsk Bokmål
• Ελληνικά
• Русский
• עברית
• العربية
• ไทย
• 한국어
• 中文(简体)
• 中文(繁體)
• 日本語