Why Do PowerShell-Based Exchange Online Cmdlets Often Fail?

Image showing some code on a computer screen
It gets frustrating having to deal with failing cmdlets!
Source: Pexels on Pixabay

The Exchange Admin Center allows you to perform basic Exchange Online management tasks. However, advanced or large-scale management operations sometimes require admins to delve into PowerShell. Moreover, Exchange Online admins often find that the PowerShell cmdlets they need to use to manage Exchange Online simply don’t work. When this happens, it’s almost always caused by insufficient permissions.

So, in this article, I’ll show you how you can determine if you have the right permissions required to manage Exchange Online. Without further ado, let’s get started.

Verifying Your Permissions

Evaluating individual permissions is a good place to start if you’re having issues with cmdlets failing in Exchange Online. To clarify, if you suspect you lack the required permissions, it’s important to take a look at your account’s role assignments.

Role Assignments

To know which roles you have, enter the following command:

Get-ManagementRoleAssignment -RoleAssignee <user> -Delegating $False | Format-Table Role, RoleAssigneeName, RoleAssigneeType

When executing this command, replace <user> with the user ID of the Microsoft 365 user whose role assignments you wish to verify. You can see an example of this command and its output in the screenshot below:

Screenshot showing PowerShell running a command to show the roles assigned to a network's users.
This is how you can find out the assigned roles.

That’s a lot of roles! So how can you check for a specific one?

How to Check for a Specific Role 

In the screenshot above, you can see that I have many roles assigned to my account. In this situation, it might be easier to check who has access to a specific role rather than trying to find it in a huge list. Thankfully, Microsoft makes it easy to do this. You just need to know the exact name of the role you want to inspect. Here’s what the basic command structure looks like:

Get-ManagementRoleAssignment -Role “<Role name>” -GetEffectiveUsers -Delegating $false | Where-Object {$_.EffectiveUserName -ne “All Group Members”} | Select-Object  EffectiveUserName,Role,RoleAssigneeName,AssignmentMethod

Suppose, for example, I wanted to see who has the “Reset Password” role in my organization. To do this, I’d use the command above but replace <Role name> with “Reset Password”. The resulting command would be:

Get-ManagementRoleAssignment -Role “Reset Password” -GetEffectiveUsers -Delegating $false | Where-Object {$_.EffectiveUserName -ne “All Group Members”} | Select-Object  EffectiveUserName,Role,RoleAssigneeName,AssignmentMethod

Looking at the screenshot below, you can see that after I run this command, I’m presented with a list of the two users with the “Reset Password” role.

Screenshot showing PowerShell running a command to show who has the Reset Password role.
Two users have permission to reset passwords.

Consider how evaluating role assignments in this way might be helpful when your PowerShell cmdlets fail. In this case, if an admin was having issues resetting a password, you could check to see if they had the “Reset Password” role assigned to them.

While it can be useful to check individual role assignments to see if a user has the required permissions to run a cmdlet, you can also do the opposite.

How to Check the Permissions Required to Run a Cmdlet

If an administrator is having issues running a PowerShell cmdlet, you can check what permissions they need to run it. Once you’ve done that, you can simply compare the required permissions with the ones they currently have.

You’ll need to enter two commands to check the permissions required to run a cmdlet. Here’s the basic command structure:

$A=Get-ManagementRole -Cmdlet <the PowerShell cmdlet that you want to evaluate>

$A | ForEach {Get-ManagementRoleAssignment -Role $_.Name -Delegating $False | Select-Object Role, RoleAssigneeType, RoleAssigneeName}

The first cmdlet creates a remote PowerShell session where you can evaluate the specified cmdlet. The second cmdlet parses the returned data and displays the role name, how it assigns the role, and to who it assigns it.

We can see how this works with an example. Let’s say that an admin is having trouble using the New-Mailbox cmdlet to create a new mailbox in Exchange Online. In this situation, one can use the above command structure to evaluate the New-Mailbox cmdlet:

$A=Get-ManagementRole -Cmdlet New-Mailbox

$A | ForEach {Get-ManagementRoleAssignment -Role $_.Name -Delegating $False | Select-Object Role, RoleAssigneeType, RoleAssigneeName}

Screenshot showing PowerShell running a command to show the roles required to use the New-Mailbox cmdlet.
These are the roles that allow users to use the New-Mailbox cmdlet.

Running this command yields the following result, as shown in the screenshot above. You can now see the permissions required to run the New-Mailbox cmdlet. It’s as simple as that! 

Let’s wrap up now, shall we?

The Bottom Line

To conclude, when an Exchange Online admin can’t complete a management task through PowerShell, it’s likely due to them having inadequate permissions. When this happens, you can check which roles have permission to use the cmdlet in question. You can also check the admin’s role assignments to see if they have any assigned supporting roles. I hope this article helped you out in some way. Feel free to refer back to it in the future if you need to.

Do you have more questions about PowerShell or Exchange Online? Check out the FAQ and Resources sections below!

FAQ

Can I evaluate a cmdlet when someone uses it in the real world, including its parameters?

The Get-ManagementRole cmdlet supports the use of a CmdletParameters switch. Therefore, simply specify this switch after the name of the cmdlet you’re evaluating and append any parameters that you want to test. You should also separate the parameters from one another using a comma. Incidentally, you’ll only see a role supporting the cmdlet if the role supports the cmdlet and all the specified parameters.

Why did the Get-ManagementRole cmdlet not return any results?

The Get-ManagementRole cmdlet will only return results for supported cmdlets. Some cmdlets are available to all Microsoft 365 users and therefore don’t display any results. For example, the Set-MsolUserPassword cmdlet used to reset a password has no role groups associated with it.

Can I make the results returned by the Get-ManagementRole cmdlet less verbose?

Yes, you can enter $A=Get-ManagementRole -cmdlet <cmdlet>. This writes the role assignment data to the $A variable. You can then type $A and press Enter to see an unfiltered and uncluttered list of roles.

When using the Get-ManagementRole cmdlet, what happens if I misspell the name of the PowerShell cmdlet that I’m evaluating? 

If you enter the -Cmdlet switch and then misspell the name of the PowerShell cmdlet that you want to check, you’ll receive no results. This is because PowerShell doesn’t display an error message or a warning telling you that you’ve made a mistake.

What should I do if I don’t get any results after entering a complex command with many parameters?

Do what you can to simplify the command. Specifically, start by checking the cmdlet by itself without any parameters. If that works, try adding the parameters to the command one at a time. Chances are that you entered one of the parameters incorrectly, or it’s unsupported.

Resources

TechGenix: Article on PowerShell and RBAC Assignments

Learn how to use PowerShell to query RBAC assignments.

TechGenix: Article on PowerShell Default Parameters

Read more on PowerShell default parameters.

TechGenix: Article on Multi-Factor Authentication (MFA)

Find out why MFA is a critical part of Microsoft 365 security.

TechGenix: Article on Role-Based Access Control (RBAC)

Discover the basics of role-based access control.

TechGenix: Article on Microsoft 365 and Old Messages

Educate yourself on how to stop Microsoft 365 from purging your old messages.

Leave a Comment

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

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Scroll to Top