Edit

Share via

New-EntraRoleDefinition

  • Reference
Module:
Microsoft.Graph.Entra

Create a new Microsoft Entra ID roleDefinition.

Syntax

New-EntraRoleDefinition
    [-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-EntraMSRoleDefinition @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.

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-EntraMSRoleDefinition @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.

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-EntraMSRoleDefinition @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.

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 = '4dd5aa9c-cf4d-4895-a993-740d342802b9'
 }

 New-EntraMSRoleDefinition @params

DisplayName      Id                                   TemplateId                           Description IsBuiltIn IsEnabled
-----------      --                                   ----------                           ----------- --------- ---------
MyRoleDefinition a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 4dd5aa9c-cf4d-4895-a993-740d342802b9             False     False

This command creates a new role definition with TemplateId parameter.

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-EntraMSRoleDefinition @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.

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.

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