Edit

Share via

New-EntraDirectoryRoleDefinition

  • Reference
Module:
Microsoft.Graph.Entra

Create a new Microsoft Entra ID roleDefinition.

Syntax

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

Description

Create a new Microsoft Entra ID roleDefinition object.

Examples

Example 1: Creates a new role definition

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$RolePermissions = New-object Microsoft.Open.MSGraph.Model.RolePermission
$RolePermissions.AllowedResourceActions =  @("microsoft.directory/applications/basic/read")

$params = @{
   RolePermissions = $RolePermissions
   IsEnabled = $false
   DisplayName = 'MyRoleDefinition'
}

New-EntraDirectoryRoleDefinition @params

DisplayName      Id                                   TemplateId                           Description IsBuiltIn IsEnabled
-----------      --                                   ----------                           ----------- --------- ---------
MyRoleDefinition a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 93ff7659-04bd-4d97-8add-b6c992cce98e             False     False

This command creates a new role definition in Microsoft Entra 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.

Example 2: Creates a new role definition with Description parameter

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$RolePermissions = New-object Microsoft.Open.MSGraph.Model.RolePermission
$RolePermissions.AllowedResourceActions =  @("microsoft.directory/applications/basic/read")
$params = @{
   RolePermissions = $RolePermissions
   IsEnabled = $false
   DisplayName = 'MyRoleDefinition'
   Description = 'Role Definition demo'
}

New-EntraDirectoryRoleDefinition @params

DisplayName      Id                                   TemplateId                           Description          IsBuiltIn IsEnabled
-----------      --                                   ----------                           -----------          --------- ---------
MyRoleDefinition a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 e14cb8e2-d696-4756-bd7f-c7df25271f3d Role Definition demo False     False

This command creates a new role definition with Description parameter.

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

Example 3: Creates a new role definition with ResourceScopes parameter

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$RolePermissions = New-object Microsoft.Open.MSGraph.Model.RolePermission
$RolePermissions.AllowedResourceActions =  @("microsoft.directory/applications/basic/read")
$params = @{
   RolePermissions = $RolePermissions
   IsEnabled = $false
   DisplayName = 'MyRoleDefinition'
   ResourceScopes = '/'
}

New-EntraDirectoryRoleDefinition @params

DisplayName      Id                                   TemplateId                           Description IsBuiltIn IsEnabled
-----------      --                                   ----------                           ----------- --------- ---------
MyRoleDefinition a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 2bc29892-ca2e-457e-b7c0-03257a0bcd0c             False     False

This command creates a new role definition with ResourceScopes parameter.

  • -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.
  • -ResourceScopes parameter specifies the resource scopes for the role definition.

Example 4: Creates a new role definition with TemplateId parameter

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$RolePermissions = New-object Microsoft.Open.MSGraph.Model.RolePermission
$RolePermissions.AllowedResourceActions =  @("microsoft.directory/applications/basic/read")
$params = @{
   RolePermissions = $RolePermissions
   IsEnabled = $false
   DisplayName = 'MyRoleDefinition'
   TemplateId = 'f2ef992c-3afb-46b9-b7cf-a126ee74c451'
}

New-EntraDirectoryRoleDefinition @params

DisplayName      Id                                   TemplateId                           Description IsBuiltIn IsEnabled
-----------      --                                   ----------                           ----------- --------- ---------
MyRoleDefinition a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 f2ef992c-3afb-46b9-b7cf-a126ee74c451             False     False

This command creates a new role definition with TemplateId parameter.

  • -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.
  • -TemplateId parameter specifies the template ID for the role definition.

Example 5: Creates a new role definition with Version parameter

Connect-Entra -Scopes 'RoleManagement.ReadWrite.Directory'
$RolePermissions = New-object Microsoft.Open.MSGraph.Model.RolePermission
$RolePermissions.AllowedResourceActions =  @("microsoft.directory/applications/basic/read")
$params = @{
   RolePermissions = $RolePermissions
   IsEnabled = $false
   DisplayName = 'MyRoleDefinition'
   Version = '2'
}

New-EntraDirectoryRoleDefinition @params

DisplayName      Id                                   TemplateId                           Description IsBuiltIn IsEnabled
-----------      --                                   ----------                           ----------- --------- ---------
MyRoleDefinition a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 b69d16e9-b3f9-4289-a87f-8f796bd9fa28             False     False

This command creates a new role definition with Version parameter.

  • -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.
  • -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:True
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 isn't available for assignment. Read-only when isBuiltIn is true.

Type:System.Boolean
Position:Named
Default value:None
Required:True
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.

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

-TemplateId

Specifies the template ID for the role definition.

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

-Version

Specifies version for the role definition.

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

Outputs

Microsoft.Open.MSGraph.Model.DirectoryRoleDefinition

Notes

New-EntraRoleDefinition is an alias for New-EntraDirectoryRoleDefintion.