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. True
Global Secure Access Administrator ac434307-12b9-4fa1-a708-88bf58caabc1 ac434307-12b9-4fa1-a708-88bf58caabc1 Create and manage all aspects of Global Secure Internet Access and Microsoft Global Secure Private Access, including managing access to public and private endpoints. 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[] |
| 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 |
| 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.