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

Get the properties and relationships of a unifiedRoleDefinition object of an RBAC provider.

The following RBAC providers are currently supported:

  • Cloud PC
  • device management (Intune)
  • directory (Microsoft Entra directory roles)
  • entitlement management (Microsoft Entra entitlement management)
  • Exchange Online

This API is available in the following national cloud deployments.

Global service US Government L4 US Government L5 (DOD) China operated by 21Vianet

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.Read.CloudPC, CloudPC.Read.All, RoleManagement.ReadWrite.CloudPC, CloudPC.ReadWrite.All, RoleManagement.Read.All
Delegated (personal Microsoft account) Not supported.
Application RoleManagement.Read.CloudPC, CloudPC.Read.All, RoleManagement.ReadWrite.CloudPC, CloudPC.ReadWrite.All, RoleManagement.Read.All

For a device management (Intune) provider

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

For a directory (Microsoft Entra ID) provider

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

In delegated scenarios with work or school accounts, the signed-in user must be assigned a supported Microsoft Entra role or a custom role with one of the following role permissions:

  • microsoft.directory/roleDefinitions/standard/read (least privileged)
  • microsoft.directory/roleDefinitions/allProperties/read
  • microsoft.directory/roleDefinitions/allProperties/allTasks

The least privileged roles supported for this operation are as follows, in the order of least to most privileged:

  • Directory Readers
  • Global Reader
  • Privileged Role Administrator

For an entitlement management provider

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

For an Exchange Online provider

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

HTTP request

Get a role definition for a Cloud PC provider:

GET /roleManagement/cloudPC/roleDefinitions/{id}

Get a role definition for a device management provider:

GET /roleManagement/deviceManagement/roleDefinitions/{id}

Get a role definition for a directory provider:

GET /roleManagement/directory/roleDefinitions/{id}

Get a role definition for the entitlement management provider:

GET /roleManagement/entitlementManagement/roleDefinitions/{id}

Get a role definition for the Exchange Online provider:

GET /roleManagement/exchange/roleDefinitions/{id}

Optional query parameters

This method supports OData query parameters to help customize the response. For general information, see OData query parameters.

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.

Request body

Don't supply a request body for this method.

Response

If successful, this method returns a 200 OK response code and the requested unifiedRoleDefinition object in the response body.

Examples

Example 1: Get the definition of a custom role for a directory provider

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/f189965f-f560-4c59-9101-933d4c87a91a

Response

The following example shows the response.

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

HTTP/1.1 200 OK
Content-type: application/json


{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleDefinitions/$entity",
    "id": "f189965f-f560-4c59-9101-933d4c87a91a",
    "description": "Allows reading Application Registrations",
    "displayName": "Application Registration Reader",
    "isBuiltIn": false,
    "isEnabled": true,
    "isPrivileged": false,
    "templateId": "f189965f-f560-4c59-9101-933d4c87a91a",
    "version": null,
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.directory/applications/allProperties/read"
            ],
            "condition": null
        }
    ],
    "inheritsPermissionsFrom": []
}

Example 2: Get the definition of a built-in role for a directory provider

Request

The following example shows a request.

GET https://graph.microsoft.com/beta/roleManagement/directory/roleDefinitions/fdd7a751-b60b-444a-984c-02652fe8fa1c

Response

The following example shows the response.

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/directory/roleDefinitions/$entity",
    "id": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "description": "Members of this role can create/manage groups, create/manage groups settings like naming and expiration policies, and view groups activity and audit reports.",
    "displayName": "Groups Administrator",
    "isBuiltIn": true,
    "isEnabled": true,
    "isPrivileged": false,
    "resourceScopes": [
        "/"
    ],
    "templateId": "fdd7a751-b60b-444a-984c-02652fe8fa1c",
    "version": "1",
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.directory/groups/assignLicense",
                "microsoft.directory/groups/create",
                "microsoft.directory/groups/delete",
                "microsoft.directory/groups/hiddenMembers/read",
                "microsoft.directory/groups/reprocessLicenseAssignment",
                "microsoft.directory/groups/restore",
                "microsoft.directory/groups/basic/update",
                "microsoft.directory/groups/classification/update",
                "microsoft.directory/groups/dynamicMembershipRule/update",
                "microsoft.directory/groups/groupType/update",
                "microsoft.directory/groups/members/update",
                "microsoft.directory/groups/owners/update",
                "microsoft.directory/groups/settings/update",
                "microsoft.directory/groups/visibility/update",
                "microsoft.azure.serviceHealth/allEntities/allTasks",
                "microsoft.azure.supportTickets/allEntities/allTasks",
                "microsoft.office365.serviceHealth/allEntities/allTasks",
                "microsoft.office365.supportTickets/allEntities/allTasks",
                "microsoft.office365.webPortal/allEntities/standard/read"
            ],
            "condition": null
        }
    ],
    "inheritsPermissionsFrom": [
        {
            "id": "88d8e3e3-8f55-4a1e-953a-9b9898b8876b"
        }
    ]
}

Example 3: Get the definition of a built-in role for a Cloud PC provider

Request

GET https://graph.microsoft.com/beta/roleManagement/cloudPC/roleDefinitions/d40368cb-fbf4-4965-bbc1-f17b3a78e510

Response

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/cloudPC/roleDefinitions/$entity",
    "id": "d40368cb-fbf4-4965-bbc1-f17b3a78e510",
    "description": "Have read-only access all Cloud PC features.",
    "displayName": "Cloud PC Reader",
    "isBuiltIn": true,
    "isEnabled": true,
    "resourceScopes": [
        "/"
    ],
    "templateId": "d40368cb-fbf4-4965-bbc1-f17b3a78e510",
    "version": null,
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "Microsoft.CloudPC/CloudPCs/Read",
                "Microsoft.CloudPC/DeviceImages/Read",
                "Microsoft.CloudPC/OnPremisesConnections/Read",
                "Microsoft.CloudPC/ProvisioningPolicies/Read",
                "Microsoft.CloudPC/Roles/Read",
                "Microsoft.CloudPC/SelfServiceSettings/Read"
            ],
            "condition": null
        }
    ]
}

Example 4: Get the definition of a built-in role for the entitlement management provider

Request

GET https://graph.microsoft.com/beta/roleManagement/entitlementManagement/roleDefinitions/ba92d953-d8e0-4e39-a797-0cbedb0a89e8

Response

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/entitlementManagement/roleDefinitions/$entity",
    "id": "ba92d953-d8e0-4e39-a797-0cbedb0a89e8",
    "displayName": "Catalog creator",
    "description": "Catalog creator",
    "isBuiltIn": true,
    "isEnabled": true,
    "templateId": "ba92d953-d8e0-4e39-a797-0cbedb0a89e8",
    "version": "1.0",
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.entitlementManagement/AccessPackageCatalog/Create"
            ]
        }
    ]
}

Example 5: Get the definition of a built-in role for the Exchange Online provider

Request

GET https://graph.microsoft.com/beta/roleManagement/exchange/roleDefinitions/7224da60-d8e2-4f45-9380-8e4fda64e133

Response

Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#roleManagement/exchange/roleDefinitions/$entity",
    "id": "7224da60-d8e2-4f45-9380-8e4fda64e133",
    "description": "This role enables administrators to manage address lists, global address lists, and offline address lists in an organization.",
    "displayName": "Address Lists",
    "isEnabled": true,
    "version": "0.12 (14.0.451.0)",
    "isBuiltIn": true,
    "templateId": null,
    "allowedPrincipalTypes": "user,group",
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "(Microsoft.Exchange.Management.PowerShell.E2010) Get-AddressBookPolicy -ErrorAction -ErrorVariable -Identity -OutBuffer -OutVariable -WarningAction -WarningVariable"
            ],
            "excludedResourceActions": [],
            "condition": null
        }
    ]
}