Edit

Share via

Set-EntraDirectoryRoleDefinition

  • Reference
Module:
Microsoft.Graph.Entra

Update an existing Microsoft Entra ID roleDefinition.

Syntax

Set-EntraDirectoryRoleDefinition
   [-TemplateId <String>]
   [-DisplayName <String>]
   [-RolePermissions <System.Collections.Generic.List`1[Microsoft.Open.MSGraph.Model.RolePermission]>]
   -UnifiedRoleDefinitionId <String>
   [-Description <String>]
   [-Version <String>]
   [-IsEnabled <Boolean>]
   [-ResourceScopes <System.Collections.Generic.List`1[System.String]>]
   [<CommonParameters>]

Description

Updates a Microsoft Entra roleDefinition object identified by ID. You can't update built-in roles. This feature requires a Microsoft Entra ID P1 or P2 license.

Examples

Example 1: Update an roleDefinition

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$roleDefinition = Get-EntraDirectoryRoleDefinition -Filter "DisplayName eq '<Role-Definition-Name>'"
Set-EntraDirectoryRoleDefinition -UnifiedRoleDefinitionId $roleDefinition.Id -DisplayName 'UpdatedDisplayName'

This example updates the specified role definition in Microsoft Entra ID.

  • -UnifiedRoleDefinitionId parameter specifies the roleDefinition object ID.
  • -DisplayName parameter specifies the display name for the role definition.

Example 2: Update an roleDefinition with Description

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$roleDefinition = Get-EntraDirectoryRoleDefinition -Filter "DisplayName eq '<Role-Definition-Name>'"
Set-EntraDirectoryRoleDefinition -UnifiedRoleDefinitionId $roleDefinition.Id -Description 'MYROLEUPDATE1S'

This example updates the Description of specified role definition in Microsoft Entra ID.

  • -UnifiedRoleDefinitionId parameter specifies the roleDefinition object ID.
  • -Description parameter specifies the description for the role definition.

Example 3: Update an roleDefinition with IsEnabled

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$roleDefinition = Get-EntraDirectoryRoleDefinition -Filter "DisplayName eq '<Role-Definition-Name>'"
Set-EntraDirectoryRoleDefinition -UnifiedRoleDefinitionId $roleDefinition.Id -IsEnabled $true

This example updates the IsEnabled of specified role definition in Microsoft Entra ID.

  • -UnifiedRoleDefinitionId parameter specifies the roleDefinition object ID.
  • -IsEnabled parameter specifies whether the role definition is enabled.

Example 4: Update an roleDefinition

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$roleDefinition = Get-EntraDirectoryRoleDefinition -Filter "DisplayName eq '<Role-Definition-Name>'"
$RolePermissions = New-object Microsoft.Open.MSGraph.Model.RolePermission
$RolePermissions.AllowedResourceActions = @("microsoft.directory/applications/standard/read")
$params = @{
   UnifiedRoleDefinitionId = $roleDefinition.Id
   Description = 'Update'
   DisplayName = 'Update'
   ResourceScopes = '/'
   IsEnabled = $false
   RolePermissions = $RolePermissions
   TemplateId = 'f2ef992c-3afb-46b9-b7cf-a126ee74c451'
   Version = 2
}

Set-EntraDirectoryRoleDefinition @params

This example updates the RolePermissions, TemplateId, TemplateId, ResourceScopes of specified role definition in Microsoft Entra ID.

  • -UnifiedRoleDefinitionId parameter specifies the roleDefinition object ID.
  • -RolePermissions parameter specifies the permissions for the role definition.
  • -IsEnabled parameter specifies whether the role definition is enabled.
  • -DisplayName parameter specifies the display name for the role definition.
  • -Description parameter specifies the description for the role definition.
  • -ResourceScopes parameter specifies the resource scopes for the role definition.
  • -TemplateId parameter specifies the template ID for the role definition.
  • -Version parameter specifies the version for the role definition.

Parameters

-Description

Specifies a description for the role definition.

Type:System.String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-DisplayName

Specifies a display name for the role definition.

Type:System.String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-IsEnabled

Specifies whether the role definition is enabled. Flag indicating if the role is enabled for assignment. If false, the role is not available for assignment. Read-only when isBuiltIn is true.

Type:System.Boolean
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ResourceScopes

Specifies the resource scopes for the role definition.

Type:System.Collections.Generic.List`1[System.String]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-RolePermissions

Specifies permissions for the role definition. List of permissions included in the role. Read-only when isBuiltIn is true.

Type:System.Collections.Generic.List`1[Microsoft.Open.MSGraph.Model.RolePermission]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-TemplateId

Specifies the template ID for the role definition. A custom template ID can be set when isBuiltIn is false. This ID is typically used to keep the same identifier across different directories. It is read-only when isBuiltIn is true.

Type:System.String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-UnifiedRoleDefinitionId

Specifies the roleDefinition object ID.

Type:System.String
Aliases:Id
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:False

-Version

Specifies version for the role definition. Indicates version of the role definition. Read-only when isBuiltIn is true.

Type:System.String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

System.String

Outputs

System.Object

Notes

Set-EntraRoleDefinition is an alias for Set-EntraDirectoryRoleDefintion.