New-EntraDirectoryRoleDefinition

Module:

Microsoft.Entra.Governance Module v1.3

Create a new Microsoft Entra ID roleDefinition.

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>]

Create a new Microsoft Entra ID roleDefinition object.

In delegated scenarios, the signed-in user must have either a supported Microsoft Entra role or a custom role with the necessary permissions. The minimum roles required for this operation are:

• Privileged Role Administrator

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

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.

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

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.

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

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.

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

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.

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

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.

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

New-EntraRoleDefinition is an alias for New-EntraDirectoryRoleDefintion.