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

Get-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 Get-ManagementRoleAssignment cmdlet to retrieve management role assignments.

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

Description

You can retrieve role assignments in a variety of ways including by assignment type, scope type, or name, and whether the assignment is enabled or disabled. You can also view a list of role assignments that provide access to a specified recipient, server, or database.

For more information about management role assignments, see Understanding management role assignments .

You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet .

This example retrieves the Denver Help Desk role assignment using the Get-ManagementRoleAssignment cmdlet and pipes the output to the Format-List cmdlet. For more information about the Format-List cmdlet, see Working with command output .

This example retrieves all the role assignments that are enabled and have been designated as delegating role assignments.

This example retrieves all the role assignments that include the MyGAL recipient-based scope restriction type.

This example retrieves all the role assignments associated with the Mail Recipients management role.

This example retrieves a list of all the users and the role assignments that can modify the recipient Bob.

This example retrieves a list of all exclusive scopes that can modify server objects that match Redmond Executive Servers. The command also lists the users who are effectively assigned the role assignments through role groups or USGs.

This example retrieves all the role assignments that can modify the database Contoso Sales.

-AssignmentMethod

The AssignmentMethod parameter specifies the type of role assignment to include in the results returned by the cmdlet. You can specify one or more of the following values:

• SecurityGroup
• RoleAssignmentPolicy

If you provide more than one value, separate each value with a comma.

You must specify a value with the RoleAssignee parameter if you use the AssignmentMethod parameter.

-ConfigWriteScope

The ConfigWriteScope parameter specifies the type of management configuration scope to include in the results returned by the cmdlet. The valid values are None, OrganizationConfig, CustomConfigScope, and ExclusiveConfigScope.

-CustomConfigWriteScope

This parameter is available only in on-premises Exchange.

The CustomConfigWriteScope parameter returns only the regular role assignments that include the specified configuration-based regular scope.

This parameter can only be used to retrieve regular configuration-based scopes. To retrieve a list of exclusive configuration-based scopes, use the ExclusiveConfigWriteScope parameter instead.

If the scope name contains spaces, enclose it in quotation marks (").

-CustomRecipientWriteScope

The CustomRecipientWriteScope parameter returns only the regular role assignments that include the specified recipient-based regular scope.

This parameter can only be used to retrieve regular recipient-based scopes. To retrieve a list of exclusive recipient-based scopes, use the ExclusiveRecipientWriteScope parameter instead.

-Delegating

The Delegating parameter specifies whether delegating or regular role assignments should be returned.

By default, both delegating and regular scopes are returned. To return only delegating role assignments, specify a value of $true. To return only regular role assignments, specify a value of $false.

-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 enabled or disabled role assignments should be returned. To return enabled role assignments, specify a value of $true. To return disabled role assignments, specify a value of $false.

The Exclusive parameter specifies whether exclusive or regular role assignments should be returned.

By default, both exclusive and regular scopes are returned. To return only exclusive role assignments, specify a value of $true. To return only regular role assignments, specify a value of $false.

-ExclusiveConfigWriteScope

The ExclusiveConfigWriteScope parameter returns only the exclusive role assignments that include the specified configuration-based exclusive scope.

This parameter can only be used to retrieve exclusive configuration-based scopes. To retrieve a list of regular configuration-based scopes, use the CustomConfigWriteScope parameter instead.

-ExclusiveRecipientWriteScope

The ExclusiveRecipientWriteScope parameter returns only the exclusive role assignments that include the specified recipient-based exclusive scope.

This parameter can only be used to retrieve exclusive recipient-based scopes. To retrieve a list of regular recipient-based scopes, use the CustomRecipientWriteScope parameter instead.

-GetEffectiveUsers

The GetEffectiveUsers switch specifies that the command should show the list of users in the role groups, role assignment policies, or USGs that are associated with the role assignment. You don't need to specify a value with this switch.

Effectively, users are associated with the role assignment through their role group, role assignment policy, or USG memberships.

The Identity parameter specifies the name of the role assignment to retrieve. If the name of the role assignment contains spaces, enclose it in quotation marks ("). If the RoleAssignee parameter is used, you can't use the Identity parameter.

-RecipientAdministrativeUnitScope

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

The RecipientAdministrativeUnitScope parameter returns only the role assignments that include the specified administrative unit.

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

-RecipientGroupScope

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

The RecipientGroupScope parameter returns only the role assignments that are scoped to groups. You can use any value that uniquely identifies the group: Name, DistinguishedName, GUID, DisplayName.

-RecipientOrganizationalUnitScope

The RecipientOrganizationalUnitScope parameter returns only the role assignments that include the specified organizational unit (OU). If the OU tree contains spaces, enclose it in quotation marks (").

-RecipientWriteScope

The RecipientWriteScope parameter returns only the role assignments associated with the recipient scope restriction type specified. The valid values are None, MyGAL, Self, OU, CustomRecipientScope, MyDistributionGroups and ExclusiveRecipientScope.

The Role parameter returns only the role assignments associated with the specified management role. If the name of the role contains spaces, enclose it in quotation marks (").

-RoleAssignee

The RoleAssignee parameter specifies the role group, assignment policy, user, or universal security group (USG) for which you want to view role assignments. If the RoleAssignee parameter is used, you can't use the Identity parameter.

By default, the command returns both direct role assignments to the role assignee and indirect role assignments granted to a role assignee through role groups or assignment policies.

If the name of the user or USG contains spaces, enclose it in quotation marks (").

-RoleAssigneeType

The RoleAssigneeType parameter specifies the type of role assignee to return. The valid values are User, SecurityGroup, RoleAssignmentPolicy, ForeignSecurityPrincipal, RoleGroup, LinkedRoleGroup and Computer.

-WritableDatabase

The WritableDatabase parameter specifies the database object you want to test to determine which role assignments allow it to be modified. The command takes into account the roles and scopes associated with each role assignment. You can use any value that uniquely identifies the database. For example:

• Distinguished name (DN)

If you use this parameter with the GetEffectiveUsers switch, all the users who can modify the database object indirectly through role groups and USGs are also returned. Without the GetEffectiveUsers switch, only the role groups, users and USGs directly assigned the role assignment are returned.

-WritableRecipient

The WritableRecipient parameter specifies the recipient object you want to test to determine which role assignments allow it to be modified. The command takes into account the roles and scopes associated with each role assignment. If the recipient name contains spaces, enclose it in quotation marks (").

If this parameter is used with the GetEffectiveUsers switch, all of the users who can modify the recipient object indirectly through role groups and USGs are also returned. Without the GetEffectiveUsers switch, only the role groups, users and USGs directly assigned the role assignment are returned.

-WritableServer

The WritableServer parameter specifies the server object you want to test to determine which role assignments allow it to be modified. The command takes into account the roles and scopes associated with each role assignment.

You can use any value that uniquely identifies the server. For example:

• Exchange Legacy DN

If this parameter is used with the GetEffectiveUsers switch, all of the users who can modify the server object indirectly through role groups and USGs are also returned. Without the GetEffectiveUsers switch, only the role groups, users and USGs directly assigned the role assignment are returned.

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

Get-ManagementRole.md

Latest commit, file metadata and controls, get-managementrole.

This cmdlet is available in on-premises Exchange and in the cloud-based service. Some parameters and settings may be exclusive to one environment or the other.

Use the Get-ManagementRole cmdlet to view management roles that have been created in your organization.

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

GetChildren

Description.

You can view management roles in several ways, from listing all the roles in your organization to listing only the child roles of a specified parent role. You can also view the details of a specific role by piping the output of the Get-ManagementRole cmdlet to the Format-List cmdlet.

For more information about management roles, see Understanding management roles .

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 lists all the roles that have been created in your organization.

This example lists all the roles that are children of the Mail Recipients management role. The command performs a recursive query of all the child roles of the specified parent role. This recursive query finds every child role from the immediate children of the parent to the last child role in the hierarchy. In a recursive list, the parent role is also returned in the list.

This example lists all the roles that contain both the Identity and Database parameters. Roles that contain only one parameter or the other aren't returned.

This example lists all the roles that have a type of UnScopedTopLevel. These roles contain custom scripts or non-Exchange cmdlets.

This example retrieves only the Transport Rules role and passes the output of the Get-ManagementRole cmdlet to the Format-List cmdlet. The Format-List cmdlet then shows only the Name and RoleType properties of the Transport Rules role. For more information about pipelining and the Format-List cmdlet, see About Pipelines and Working with command output .

This example lists the immediate children of the Mail Recipients role. Only the child roles that hold the Mail Recipients role as their parent role are returned. The Mail Recipients role isn't returned in the list.

The Identity parameter specifies the role you want to view. If the role you want to view contains spaces, enclose the name in quotation marks ("). You can use the wildcard character (*) and a partial role name to match multiple roles.

-GetChildren

The GetChildren parameter retrieves a list of all the roles that were created based on the parent role specified in the Identity parameter. You don't need to specify a value with this switch.

Only the immediate child roles of the parent role are included in the results.

You can use this switch only with the Identity and RoleType parameters.

The Recurse parameter retrieves a list of all the roles that were created based on the parent role specified in the Identity parameter. You don't need to specify a value with this switch.

The role specified in the Identity parameter, its child roles, and their children are returned.

The Cmdlet parameter returns a list of all roles that include the specified cmdlet.

-CmdletParameters

The CmdletParameters parameter returns a list of all roles that include the specified parameter or parameters. You can specify more than one parameter by separating each parameter with a comma. If you specify multiple parameters, only the roles that include all of the specified parameters are returned.

-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 RoleType parameter returns a list of roles that match the specified role type. For a list of valid role types, see Understanding management roles .

The Script parameter returns a list of all roles that include the specified script.

-ScriptParameters

The ScriptParameters parameter returns a list of all roles that include the specified parameter or parameters. You can specify more than one parameter by separating each parameter with a comma. If you specify multiple parameters, only the roles that include all of the specified parameters are returned.

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

PowerShell is fun :)

Blogs about things i encounter in my daily work as an it consultant, using get-managementrole to get the permissions required for exchange-specific cmdlets.

I ran into an issue where one of my Exchange scripts didn’t work, “a parameter could not be found that matches the parameter…” Strange error because the parameter is there… Or is it? In this blog post, I will show you how Get-ManagementRole works in Exchange and how it can help you with issues like this.

What does Get-ManagementRole do?

When do you use it, how do you use it for a specific cmdlet, retrieving all cmdlets and the required permissions, more information.

The Get-ManagementRole cmdlet shows you the role-based access control (RBAC) management roles and role groups that give you access to a specified cmdlet—even if your organization has custom roles, custom role groups, or custom role assignments.

Source: https://learn.microsoft.com/en-us/powershell/exchange/find-exchange-cmdlet-permissions?view=exchange-ps

When in doubt, use Get-ManagementRole ! As a Consultant, I don’t get all permissions in some of my customer tenants. And when you run inventory scripts against Exchange, and they fail, then you start searching for reasons 🙂

Before using it, you must either start the Exchange Management Shell on your Exchange Server (Alternatively, if you start a PowerShell session on a machine with the Exchange Management Shell snap-in installed and loaded) or use Connect-ExchangeOnline after installing the ExchangeOnlineManagement PowerShell module.

You can now use the Get-ManagementRole cmdlet to display the required roles for a specific cmdlet. For example:

This will display the roles required for showing the Migration batches in your environment. Sometimes, the cmdlet requires specific permissions, but the Parameters could require additional permissions. You can also specify a Parameter to query the required permissions, for example:

This displays the cmdlet Set-ExternalInOutlook (Information about this cmdlet here ) required permission. Still, the Parameter Enabled requires Organization Configuration , and that means that someone with View-Only Configuration permissions can see the Set-ExternalInOutlook cmdlet but not use the Enabled Parameter. This makes sense, of course; it’s a View-Only role, but this is just an example.

You can also specify multiple Parameters if needed:

Note: You must have the View-Only Organization Management or Organization Management role to retrieve this information.

You can also display all the Exchange cmdlets and the required roles by running the following:

This will output the information in an Out-GridView pane like this:

You could also export it to a .csv file like this:

When you open the .csv file, it will look like this:

Note: This outputs the cmdlets and the required roles. If you need the required roles for a specific parameter, use “Get-ManagemenRole -cmdlet XYZ -CmdletParameters XYZ.”

You can find more information about Get-ManagementRole here , but also more information about retrieving required permissions here .

Related blog post

Leave a reply cancel reply.

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

Discover more from PowerShell is fun :)

Subscribe now to keep reading and get access to the full archive.

Type your email…

Continue reading

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.

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

Leveling Up Privileged Identity Management with Approvals

In this blog, Brandon Colley reviews how to use PIM approvals to create a workflow that could stop attackers in their tracks, even if they have already compromised credentials.

Exchange Server Roadmap, New MS AI model on the way & Entra ID MFA: The Practical 365 Podcast S4 E19

On this week's episode, Paul and Steve cover several major Microsoft announcements impacting the future of AI, Exchange Server, and identity solutions.

• Infra as Code
• Microsoft 365

Its always a problem on finding, What Roles the Current user is Assigned to, Not sure on what all he has having access to.

You can use the Below PowerShell Command to Find in which role assigments the user is part of in Exchange Role based acess groups.

Replace with “Username” with the Alias of the mailbox

Related Articles

Mem – configure onedrive kfm via intune, configuration policy – how to hide the gaming section on windows devices using intune, step-by-step azure sql backup & restore guide, 15 comments.

That’s a nice post.

I try, it’ works, and it’s helpful. Keep posting helpful article.

Your most welcome Sendi

Hi Satheshwaran,

Can we know which commands a perticular user(admin) can execute depend on the permissions given to him?

Regards, Hemant

Check what all roles assigned to the user. = Check what all the commands the role contains. or login as him — run — Get-command

It didn’t appear to make a difference.

What does it mean if nothing is returned?

Not a member of anything

Your articles are really informative and good , Thanks for sharing the commands , Keep up your good work .

Hi I am trying to get a user name with a specific role assigned for e.g. Get-User | Get-ManagementRoleAssignment -Role ‘audit logs’

Ho can I get this working. Please help

soulful resource http://xnxx-love.com

corporate web site http://iqxnxx.com

Six years later and this is the most helpful article I’ve found. Nothing helpful (cmdlet or article wise) from Microsoft

Many thanks for this simple yet evidently necessary post!

Thank you Nick

The command only works for first 1000 entries. We have over 10 K entries where it is not pulling all the roles assigned to an admin. I tried to explore but it appears there is no parameter called resultsize or -All .

LEAVE A REPLY Cancel reply

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

EDITOR PICKS

Exploring azure sql database auto-failover group for seamless disaster recovery, deploying docker image to azure container registry and hosting it with azure web app service., popular posts, popular category.

• x-All Posts-x 658
• Exchange 2013 183
• Microsoft 365 134
• Exchange 2010 122
• Exchange 2016 105
• Azure Active Directory 102
• Windows Server 55

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

All about Microsoft 365

Generate a report of Azure AD role assignments via the Graph API or PowerShell

A while back, I published a short article and script to illustrate the process of obtaining a list of all Azure AD role assignments. The examples therein use the old MSOnline and Azure AD PowerShell modules, which are now on a deprecation path. Thus, it’s time to update the code to leverage the “latest and greatest”. Quotes are there for a reason…

The updated script comes in two flavors. The first one is based on direct web requests against the Graph API endpoints and uses application permissions, thus is suitable for automation scenarios. Do make sure to replace the authentication variables, which you can find on lines 11-13. Better yet, replace the whole authentication block (lines 7-36) with your preferred “connect to Graph” function. Also make sure that sufficient permissions are granted to the service principal under which you will be running the script. Those include the Directory.Read.All scope for fetching regular role assignments and performing directory-wide queries, and the RoleManagement.Read.Directory for PIM roles.

The second flavor is based on the cmdlets included as part of the Microsoft Graph SDK for PowerShell. As authentication is handled via the Connect-MGGraph cmdlet, the script is half the size of the first one. And it would’ve been even smaller were it not for few annoying bugs Microsoft is yet to address.

In all fairness, switching to the Graph does offer some improvements, such as being able to use a single call to list all role assignments. This is made possible thanks to the  /roleManagement/directory/roleAssignments endpoint (or calling the Get-MgRoleManagementDirectoryRoleAssignment cmdlet). Previously, we had to iterate over each admin role and list its members, which is not exactly optimal, and given the fact that the list of built-in roles has now grown to over 90, it does add up. On the negative side, we have a bunch of GUIDs in the output, most of which we will want to translate to human-readable values, as they designate the user, group or service principal to which a given role has been assigned, as well as the actual role. One way to go about this is to use the $expand operator (or the – ExpandProperty parameter if using the SDK) to request the full object.

While this is the quickest method, the lack of support for the $select operator inside an $expand query means we will be fetching a lot more data than what we need for the report. In addition, there seems to be an issue with the definition of the expandable properties for this specific endpoint, as trying to use the handy $expand=* value will result in an error ( “Could not find a property named ‘appScope’ on type ‘Microsoft.DirectoryServices.RoleAssignment'” ). In effect, to fetch both the expanded principal object and the expanded roleDefinition object, we need to run two separate queries and merge the results. Hopefully Microsoft will address this issue in the future (the /roleManagement/directory/roleEligibilitySchedules we will use to fetch PIM eligible role assignments does support $expand=* query).

Another option is to collect all the principalIDs and issue a POST request against the /directoryObjects/getByIds endpoint (or the corresponding Get-MgDirectoryObjectById cmdlet), which does have a proper support for $select . A single query can be used to “translate” up to 1000 principal values, which should be sufficient for most scenarios. With the information gathered from the query, we can construct a hash-table and use it to lookup the property values we want to expose in our report. Lastly, you can also query each principalID individually, but that’s the messiest option available.

Apart from role assignments obtained via the /roleManagement/directory/roleAssignments call, the script can also include any PIM eligible role assignments. To fetch those, invoke the script with the – IncludePIMEligibleAssignments switch. It will then call the /v1.0/roleManagement/directory/roleEligibilitySchedules endpoint, or similarly, use the Get-MgRoleManagementDirectoryRoleEligibilitySchedule cmdlet. Some minor adjustments are needed to ensure the output between the two is uniform, which includes the aforementioned issue with expanding the navigation properties. But hey, it wouldn’t be a Microsoft product if everything worked out of the box 🙂

Here are some examples on how to run the scripts. The first example uses the Graph API version and no parameters. For the second one, we invoke the – IncludePIMEligibleAssignments parameter in order to include PIM eligible role assignments as well. The last example does the same thing, but for the Graph SDK version of the script.

And with that, we’re ready to build the output. Thanks to the $expand operator and the workarounds used above, we should be able to present sufficient information about each role assignment, while minimizing the number of calls made. The output is automatically exported to a CSV in the script folder, and includes the following fields:

• Principal – an identifier for the user, group or service principal to which the role has been assigned. Depending on the object type, an UPN, appID or GUID value will be presented.
• PrincipalDisplayName – the display name for the principal.
• PrincipalType – the object type of the principal.
• AssignedRole – the display name of the role assigned.
• AssignedRoleScope – the assignment scope, either the whole directory (“/”) or a specific administrative unit.
• AssignmentType – the type of assignment (“Permanent” or “Eligible”).
• IsBuiltIn – indicates whether the role is a default one, or custom-created one.
• RoleTemplate – the GUID for the role template.

Now, it’s very important to understand that this script only covers Azure AD admin roles, either default or custom ones, and optionally eligible PIM-assignable roles (do note that the PIM cmdlets/endpoints do not cover all custom role scenarios). Apart from these, there are numerous workload-specific roles that can be granted across Office 365, such as the Exchange Online Roles and assignments, Roles in the Security and Compliance Center, site collection permissions in SharePoint Online, and so on. Just because a given user doesn’t appear in the admin role report, it doesn’t mean that he cannot have other permissions granted!

In addition, one should make sure to cover any applications (service principals) that have been granted permissions to execute operations against your tenant. Such permissions can range from being able to read directory data to full access to user’s messages and files, so it’s very important to keep track on them. We published an article  that can get you started with a sample script a while back.

9 thoughts on “ Generate a report of Azure AD role assignments via the Graph API or PowerShell ”

• Pingback: Reporting on Entra ID directory role assignments (including PIM) - Blog

This script is very nicely written, however the output of the Powershell Graph SDK version is incorrect (I didn’t check the other).

If I am eligible to activate a role I’ll be in the eligible list. However once I activate the role, my activated role assignment will show up in the list of role assignments from “Get-MgRoleManagementDirectoryRoleAssignment”. The output of that command doesn’t include a ‘status’ property. Your script assumes that if there’s no ‘status’ then the assignment is permanent, however that’s not accurate. So every eligible user who has activated a role shows up twice in the output of your script – once as as eligible for the role and once as a permanent assignment.

I came across your script because I’m trying to accomplish a similar task. My goal is to enumerate all the users who have eligible or permanent role assignments. I think the answer may be that if a user is in the eligible list, and also in the role assignment list, for the same role, then you can assume that the role assignment came from activation, but that doesn’t really seem very satisfactory.

Thanks Matt. The script is a bit outdated by now, I don’t even know if it runs with the “V2” Graph SDK. I’ll update it at some point 🙂

To further address your comment – neither the Get-MgRoleManagementDirectoryRoleAssignment nor the Get-MgRoleManagementDirectoryRoleEligibilitySchedule cmdlet returns sufficient information in order to determine whether a given (eligible) role assignment is currently activated. You can get this information via Get-MgRoleManagementDirectoryRoleAssignmentScheduleInstance, should be easy enough to add to the next iteration of the script.

Hi, thks for your great work. do you know why i dont see the eligible assignements ?

Seems they made some changes and you can no longer use $expand=* on the /v1.0 endpoint. Try using /beta, should work there. I’ll update the script when I get some time.

I’ve updated the script, let me know if you are still having issues.

Awesome, thank you very much.

Merci merci merci !!! Thanks thanks thanks !!

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 .