unifiedRoleDefinition resource type

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.

Represents a collection of permissions listing the operations, such as read, write, and delete, that can be performed by an RBAC provider, as part of Microsoft 365 RBAC role management.

The following RBAC providers are currently supported:

• Cloud PC
• device management (Intune)
• directory (Microsoft Entra ID)
• entitlement management (Microsoft Entra Entitlement Management)
• Exchange Online

Methods

Method	Return Type	Description
List roleDefinitions	unifiedRoleDefinition collection	Read a list of unifiedRoleDefinition objects, and their properties.
Get unifiedRoleDefinition	unifiedRoleDefinition	Read the properties of a unifiedRoleDefinition object.
Create roleDefinitions	unifiedRoleDefinition	Create a unifiedRoleDefinition object.
Update unifiedRoleDefinition	unifiedRoleDefinition	Update a unifiedRoleDefinition object.
Delete unifiedRoleDefinition	None	Delete a unifiedRoleDefinition object.
List assignedPrincipals	directoryObject collection	Get the users and groups assigned to a role across all scopes.

Properties

Property	Type	Description
allowedPrincipalTypes	allowedRolePrincipalTypes	Types of principals that can be assigned the role. Read-only. The possible values are: user, servicePrincipal, group, unknownFutureValue. This is a multi-valued enumeration that can contain up to three values as a comma-separated string. For example, user, group. Supports $filter (eq).
description	String	The description for the unifiedRoleDefinition. Read-only when isBuiltIn is true.
displayName	String	The display name for the unifiedRoleDefinition. Read-only when isBuiltIn is true. Required. Supports $filter (eq and startsWith).
id	String	The unique identifier for the unifiedRoleDefinition. Key, not nullable, Read-only. Supports $filter (eq operator only).
isBuiltIn	Boolean	Flag indicating if the unifiedRoleDefinition is part of the default set included with the product or custom. Read-only. Supports $filter (eq).
isEnabled	Boolean	Flag indicating if the role is enabled for assignment. If false the role is not available for assignment. Read-only when isBuiltIn is true.
isPrivileged	Boolean	Flag indicating if the role is privileged. Microsoft Entra ID defines a role as privileged if it contains at least one sensitive resource action in the rolePermissions and allowedResourceActions objects. Applies only for actions in the microsoft.directory resource namespace. Read-only. Supports $filter (eq).
resourceScopes	String collection	List of scopes permissions granted by the role definition apply to. Currently only / is supported. Read-only when isBuiltIn is true. DO NOT USE. This will be deprecated soon. Attach scope to role assignment.
rolePermissions	unifiedRolePermission collection	List of permissions included in the role. Read-only when isBuiltIn is true. Required.
templateId	String	Custom template identifier that can be set when isBuiltIn is false. This identifier is typically used if one needs an identifier to be the same across different directories. Read-only when isBuiltIn is true.
version	String	Indicates the version of the unifiedRoleDefinition object. Read-only when isBuiltIn is true.

Relationships

Relationship	Type	Description
inheritsPermissionsFrom	unifiedRoleDefinition collection	Read-only collection of role definitions that the given role definition inherits from. Only Microsoft Entra built-in roles support this attribute.

JSON representation

The following is a JSON representation of the resource.

{
  "allowedPrincipalTypes": "String",
  "description": "String",
  "displayName": "String",
  "id": "String (identifier)",
  "isBuiltIn": true,
  "isEnabled": true,
  "isPrivileged": true,
  "resourceScopes": ["String"],
  "rolePermissions": [{"@odata.type": "microsoft.graph.unifiedRolePermission"}],
  "templateId": "String",
  "inheritsPermissionsFrom": [{"@odata.type": "microsoft.graph.unifiedRoleDefinition"}],
  "version": "String"
}