Create unifiedRoleDefinition

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:

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

Note

The cloud PC RBAC provider currently supports only the list and get operations.

Permissions

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

For 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 Directory (Azure AD) provider

Permission type Permissions (from least to most privileged)
Delegated (work or school account) RoleManagement.ReadWrite.Directory, Directory.ReadWrite.All, Directory.AccessAsUser.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

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

Request

The following is an example of creating a custom role for a directory provider.

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": "c2cb59a3-2d01-4176-a458-95b0e674966f",
    "version": null,
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.directory/applications/standard/read",
				"microsoft.directory/applications/basic/update"
            ],
            "condition": null
        }
    ],
    "inheritsPermissionsFrom@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleDefinitions('c2cb59a3-2d01-4176-a458-95b0e674966f')/inheritsPermissionsFrom",
    "inheritsPermissionsFrom": []
}