title	Get unifiedRoleDefinition
description	Retrieve the properties and relationships of a unifiedRoleDefinition object.
ms.localizationpriority	medium
author	DougKirschner
ms.reviewer	msodsrbac
ms.subservice	entra-directory-management
doc_type	apiPageType
ms.date	07/26/2024

Get unifiedRoleDefinition

Namespace: microsoft.graph

[!INCLUDE beta-disclaimer]

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)
Defender (Microsoft Defender XDR Unified RBAC)
directory (Microsoft Entra directory roles)
entitlement management (Microsoft Entra entitlement management)
Exchange Online (Except China operated by 21Vianet)

[!INCLUDE national-cloud-support]

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 Defender provider

Permission type	Permissions (from least to most privileged)
Delegated (work or school account)	RoleManagement.Read.Defender, RoleManagement.ReadWrite.Defender, RoleManagement.Read.All
Delegated (personal Microsoft account)	Not supported.
Application	RoleManagement.Read.Defender, RoleManagement.ReadWrite.Defender, RoleManagement.Read.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

[!INCLUDE rbac-role-definition-apis-read]

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 Defender provider:

GET /roleManagement/defender/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.

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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.

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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

Example 6: Get the definition of a custom role for a defender provider

Request

The following example shows a request.

HTTP

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

C#

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Go

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

Java

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

JavaScript

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PHP

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

PowerShell

[!INCLUDE snippet-not-available] [!INCLUDE sdk-documentation]

Python

[!INCLUDE sample-code] [!INCLUDE sdk-documentation]

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/defender/roleDefinitions/$entity",
    "id": "f189965f-f560-4c59-9101-933d4c87a91b",
    "description": "Role definition 2 description.",
    "displayName": "Role Definition 2",
    "rolePermissions": [
        {
            "allowedResourceActions": [
                "microsoft.xdr/securityposture/read"
            ],
        }
    ]
}

FilesExpand file tree

unifiedroledefinition-get.md

Latest commit

History

unifiedroledefinition-get.md

File metadata and controls

Get unifiedRoleDefinition

Permissions

For a Cloud PC provider

For a device management (Intune) provider

For a Defender provider

For a directory (Microsoft Entra ID) provider

For an entitlement management provider

For an Exchange Online provider

HTTP request

Optional query parameters

Request headers

Request body

Response

Examples

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

Request

Response

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

Request

Response

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

Request

Response

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

Request

Response

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

Request

Response

Example 6: Get the definition of a custom role for a defender provider

Request

Response