Get-EntraDirectoryRoleDefinition
Gets information about role definitions in Microsoft Entra ID.
Syntax
Get-EntraDirectoryRoleDefinition
[-All]
[-Top <Int32>]
[-Filter <String>]
[-Property <String[]>]
[<CommonParameters>] Get-EntraDirectoryRoleDefinition
[-SearchString <String>]
[-All]
[-Property <String[]>]
[<CommonParameters>] Get-EntraDirectoryRoleDefinition
-UnifiedRoleDefinitionId <String>
[-All]
[-Property <String[]>]
[<CommonParameters>] Description
The Get-EntraDirectoryRoleDefinition cmdlet gets information about role definitions in Microsoft Entra ID. To get a role definition, specify the UnifiedRoleDefinitionId parameter. Specify the SearchString or Filter parameter to find particular role definition.
In delegated scenarios with work or school accounts, the signed-in user must have a supported Microsoft Entra role or a custom role with one of the following permissions:
- microsoft.directory/roleAssignments/standard/read (least privileged)
- microsoft.directory/roleAssignments/allProperties/read
- microsoft.directory/roleAssignments/allProperties/allTasks
The least privileged roles for this operation, from least to most privileged, are:
- Directory Readers
- Global Reader
- Privileged Role Administrator
Examples
Example 1: Get all role definitions
Connect-Entra -Scopes 'RoleManagement.Read.Directory','EntitlementManagement.Read.All'
Get-EntraDirectoryRoleDefinition
DisplayName Id TemplateId Description
----------- -- ---------- -----------
Guest User 10dae51f-b6af-4016-8d66-8c2a99b929b3 10dae51f-b6af-4016-8d66-8c2a99b929b3 Default role for guest users. Can read a limited set of directory information.
Restricted Guest User 2af84b1e-32c8-42b7-82bc-daa82404023b 2af84b1e-32c8-42b7-82bc-daa82404023b Restricted role for guest users. Can read a limited set of directory information.This command returns all the role definitions present.
Example 2: Get a role definition by UnifiedRoleDefinitionId
Connect-Entra -Scopes 'RoleManagement.Read.Directory','EntitlementManagement.Read.All'
Get-EntraDirectoryRoleDefinition -UnifiedRoleDefinitionId '2af84b1e-32c8-42b7-82bc-daa82404023b'
DisplayName Id TemplateId Description
----------- -- ---------- -----------
Restricted Guest User 2af84b1e-32c8-42b7-82bc-daa82404023b 2af84b1e-32c8-42b7-82bc-daa82404023b Restricted role for guest users. Can read a limited set of directory information.This command returns a specified role definition.
-UnifiedRoleDefinitionIdparameter specifies the roleDefinition object ID.
Example 3: Filter role definitions by display name
Connect-Entra -Scopes 'RoleManagement.Read.Directory','EntitlementManagement.Read.All'
Get-EntraDirectoryRoleDefinition -Filter "startsWith(displayName, 'Restricted')"
DisplayName Id TemplateId Description
----------- -- ---------- -----------
Restricted Guest User 2af84b1e-32c8-42b7-82bc-daa82404023b 2af84b1e-32c8-42b7-82bc-daa82404023b Restricted role for guest users. Can read a limited set of directory information.This command return all the role definitions containing the specified display name.
Example 4: Get top two role definition
Connect-Entra -Scopes 'RoleManagement.Read.Directory','EntitlementManagement.Read.All'
Get-EntraDirectoryRoleDefinition -Top 2
DisplayName Id TemplateId Description IsBuiltIn IsEnabled
----------- -- ---------- ----------- --------- ---------
Restricted Guest User 00aa00aa-bb11-cc22-dd33-44ee44ee44ee 2af84b1e-32c8-42b7-82bc-daa82404023b Restricted role for guest users. Can read a limited set of directory information. True TrueThis command return top two the role definitions in Microsoft Entra DirectoryRoleId.
Example 5: Filter role definitions by display name
Connect-Entra -Scopes 'RoleManagement.Read.Directory','EntitlementManagement.Read.All'
Get-EntraDirectoryRoleDefinition -SearchString 'Global'
DisplayName Id TemplateId Description IsBu
iltI
n
----------- -- ---------- ----------- ----
Global Administrator 62e90394-69f5-4237-9190-012177145e10 62e90394-69f5-4237-9190-012177145e10 Can manage all aspects of Microsoft Entra ID and Microsoft services that use Microsoft Entra identities. True
Global Reader f2ef992c-3afb-46b9-b7cf-a126ee74c451 f2ef992c-3afb-46b9-b7cf-a126ee74c451 Can read everything that a Global Administrator can, but not update anything. TrueThis command return all the role definitions containing the specified display name.
Parameters
-All
List all pages.
| Type: | System.Management.Automation.SwitchParameter |
| Position: | Named |
| Default value: | False |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Filter
Specifies an OData v4.0 filter string to match a set of role definitions.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Property
Specifies properties to be returned
| Type: | System.String[] |
| Aliases: | Select |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SearchString
Specifies a search string.
| Type: | System.String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-Top
Specifies the maximum number of records that this cmdlet gets. The default value is 100.
| Type: | System.Int32 |
| Aliases: | Limit |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-UnifiedRoleDefinitionId
Specifies the UnifiedRoleDefinitionId of the role definition.
| Type: | System.String |
| Aliases: | Id |
| Position: | Named |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
Inputs
String
Notes
Get-EntraRoleDefinition is an alias for Get-EntraDirectoryRoleDefintion.