Skip to main content

​
SYNOPSIS

Get-MgRoleReport.ps1 - Reports on Microsoft Entra ID (Azure AD) roles

​
SYNTAX

Get-MgRoleReport [[-Identity] <String>] [[-PrincipalID] <String>] [[-PrincipalDisplayName] <String>]
 [[-Scope] <String>] [[-TierLevel] <String>] [-IncludeEmptyRoles] [-ExcludePIMEligibleAssignments]
 [-ForceNewToken] [-MaesterMode] [-ExportToExcel] [-ProgressAction <ActionPreference>] [<CommonParameters>]

​
DESCRIPTION

By default, the report contains only the roles with members. To get all the role, included empty roles, add -IncludeEmptyRoles $true

​
EXAMPLES

​
EXAMPLE 1

Get-MgRoleReport
Get all the roles with members, including PIM eligible assignments but without empty roles

​
EXAMPLE 2

Get-MgRoleReport -Identity 'Global Administrator'
Returns only the assignments of the Global Administrator role (filter accepts both role name and roleDefinitionId).

​
EXAMPLE 3

Get-MgRoleReport -PrincipalID 'alice@contoso.com'
Returns only the role assignments of alice@contoso.com (direct or via group membership).

​
EXAMPLE 4

Get-MgRoleReport -PrincipalID '11111111-2222-3333-4444-555555555555'
Returns only the role assignments for the principal matching this ObjectId or AppId.

​
EXAMPLE 5

Get-MgRoleReport -PrincipalDisplayName 'Alice Doe'
Returns only the role assignments for the principal whose DisplayName is ‘Alice Doe’.

​
EXAMPLE 6

Get-MgRoleReport -Scope '/'
Returns only the role assignments at tenant scope.

​
EXAMPLE 7

Get-MgRoleReport -TierLevel 0
Returns only the assignments of Tier 0 (control plane) roles. Each row carries a RoleTier property.

​
EXAMPLE 8

Get-MgRoleReport -IncludeEmptyRoles
Get all the roles, including the ones without members

​
EXAMPLE 9

Get-MgRoleReport -ExcludePIMEligibleAssignments
Get all the roles with members (without empty roles), but without PIM eligible assignments

​
EXAMPLE 10

Get-MgRoleReport | Export-CSV -NoTypeInformation "$(Get-Date -Format yyyyMMdd)_adminRoles.csv" -Encoding UTF8

​
PARAMETERS

​
-Identity

Filter the report on a specific role. Accepts the role display name (e.g. ‘Global Administrator’) or the role definition Id (GUID). 
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-PrincipalID

Filter the report on a specific principal. Accepts the UPN (user), AppId (service principal) or ObjectId. 
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-PrincipalDisplayName

Filter the report on a specific principal display name (exact match, case-insensitive). 
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-Scope

Filter the report on the assignment scope (AssignedRoleScope / directoryScopeId). Examples: ’/’ (tenant-wide), ‘/administrativeUnits/<id>’ (AU-scoped), or any resource scope. 
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-TierLevel

Filter the report on a privileged role tier: ‘0’ (control plane), ‘1’ (service/workload admins) or ‘2’ (lower-privilege / read-mostly). Tiering is based on Sean Metcalf’s (PyroTek3) classification. Regardless of this filter, every row is always annotated with a RoleTier property (Tier0/Tier1/Tier2/Untiered). 
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

​
-IncludeEmptyRoles

Switch parameter to include empty roles in the report 
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

​
-ExcludePIMEligibleAssignments

Switch parameter to exclude PIM eligible assignments from the report. Default is $false (includes them) 
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

​
-ForceNewToken

Switch parameter to force getting a new token from Microsoft Graph 
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

​
-MaesterMode

Switch parameter to use with the Maester framework (internal process not presented here) 
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

​
-ExportToExcel

Switch parameter to export the report to an Excel file in the user’s profile directory 
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

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

​
INPUTS

​
OUTPUTS

​
The report is output to an array contained all the audit logs found.

​
To export in a csv, do Get-MgRoleReport | Export-CSV -NoTypeInformation ”$(Get-Date -Format yyyyMMdd)_adminRoles.csv” -Encoding UTF8

​
NOTES

https://itpro-tips.com/get-the-office-365-admin-roles-and-track-the-changes/ Written by Bastien Perez (Clidsys.com - ITPro-Tips.com) For more Office 365/Microsoft 365 tips and news, check out ITPro-Tips.com. https://ps365.clidsys.com/docs/commands/Get-MgRoleReport