Create roleDefinitions

Namespace: microsoft.graph

Important

APIs under the /beta version in Microsoft Graph are subject to change. Use of these APIs in production applications is not supported. To determine whether an API is available in v1.0, use the Version selector.

Create a new unifiedRoleDefinition object for an RBAC provider.

The following RBAC providers are currently supported:

  • Cloud PC
  • device management (Intune)
  • directory (Azure AD)

Permissions

Depending on the RBAC provider and the permission type (delegated or application) that is needed, choose from the following tables the least privileged permission required to call this API. To learn more, including taking caution before choosing more privileged permissions, see Permissions.

For a Cloud PC provider

Permission type Permissions (from least to most privileged)
Delegated (work or school account) RoleManagement.ReadWrite.CloudPC, CloudPC.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application RoleManagement.ReadWrite.CloudPC, CloudPC.ReadWrite.All

For a device management (Intune) provider

Permission type Permissions (from least to most privileged)
Delegated (work or school account) DeviceManagementRBAC.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application DeviceManagementRBAC.ReadWrite.All

For a directory (Azure AD) provider

Permission type Permissions (from least to most privileged)
Delegated (work or school account) RoleManagement.ReadWrite.Directory, Directory.ReadWrite.All
Delegated (personal Microsoft account) Not supported.
Application RoleManagement.ReadWrite.Directory, Directory.ReadWrite.All

HTTP request

To create a role definition for a device management provider:

POST /roleManagement/deviceManagement/roleDefinitions

To create a role definition for a directory provider:

POST /roleManagement/directory/roleDefinitions

To create a role definition for a Cloud PC provider:

POST /roleManagement/cloudPc/roleDefinitions

Request headers

Name Description
Authorization Bearer {token}

Request body

In the request body, supply a JSON representation of unifiedRoleDefinition object.

The following table shows the properties that are required when you create a roleDefinition.

Parameter Type Description
displayName string The display name for the role definition.
isEnabled Boolean Flag indicating if the role is enabled for assignment. If false the role is not available for assignment.
rolePermissions unifiedRolePermission collection List of permissions included in the role.

Response

If successful, this method returns 201 Created response code and a new unifiedRoleDefinition object in the response body.

Example 1:Create a custom role for a directory provider

Request

POST https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions
Content-type: application/json

{
  "description": "Update basic properties of application registrations",
  "displayName": "Application Registration Support Administrator",
  "rolePermissions":
    [
        {
            "allowedResourceActions": 
            [
                "microsoft.directory/applications/basic/read"
            ]
        }
    ],
    "isEnabled" : "true"
}

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleDefinitions/$entity",
    "id": "d5eec5e0-6992-4c6b-b430-0f833f1a815a",
    "description": "Update basic properties of application registrations",
    "displayName": "Application Registration Support Administrator",
    "isBuiltIn": false,
    "isEnabled": true,
    "templateId": "d5eec5e0-6992-4c6b-b430-0f833f1a815a",
    "version": null,
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.directory/applications/standard/read",
                "microsoft.directory/applications/basic/update"
            ],
            "condition": null
        }
    ],
    "inheritsPermissionsFrom": []
}

Example 2: Create a custom role for a Cloud PC provider

Request

POST https://graph.microsoft.com/beta/roleManagement/cloudPc/roleDefinitions
Content-type: application/json

{
  "description": "An example custom role",
  "displayName": "ExampleCustomRole",
  "rolePermissions":
    [
        {
            "allowedResourceActions": 
            [
                "Microsoft.CloudPC/CloudPCs/Read"
            ]
        }
    ],
    "condition" : "null"
}

Response

The following is an example of the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/cloudPc/roleDefinitions/$entity",
    "id": "b7f5ddc1-b7dc-4d37-abce-b9d6fc15ffff",
    "description": "An example custom role",
    "displayName": "ExampleCustomRole",
    "isBuiltIn": false,
    "isEnabled": true,
    "templateId": "b7f5ddc1-b7dc-4d37-abce-b9d6fc15ffff",
    "version": null,
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "Microsoft.CloudPC/CloudPCs/Read"
            ],
            "condition": null
        }
    ],
    "resourceScopes":["/"]
}