🔍 Code Extractor

Represents an Azure Active Directory (Azure AD) role definition, which is a collection of permissions listing operations that can be performed and resources against which they can be performed.

Purpose

This class models Azure AD role definitions in the Microsoft Graph API. It provides access to role metadata including display name, built-in status, permissions, and inheritance relationships. It extends the Entity base class to provide OData entity functionality for querying and managing role definitions in Azure AD. The class is primarily used for reading role definition data from Azure AD, with special support for built-in roles and custom role definitions.

Source Code

class UnifiedRoleDefinition(Entity):
    """A role definition is a collection of permissions in Azure Active Directory (Azure AD) listing the operations
    that can be performed and the resources against which they can performed."""

    @property
    def display_name(self):
        # type: () -> Optional[str]
        """The display name for the unifiedRoleDefinition."""
        return self.properties.get("displayName", None)

    @property
    def is_built_in(self):
        # type: () -> Optional[bool]
        """Flag indicating whether the role definition is part of the default set included in
        Azure Active Directory (Azure AD) or a custom definition.
        """
        return self.properties.get("isBuiltIn", None)

    @property
    def role_permissions(self):
        """
        List of permissions included in the role. Read-only when isBuiltIn is true. Required.
        """
        return self.properties.get(
            "rolePermissions", ClientValueCollection(UnifiedRolePermission)
        )

    @property
    def inherits_permissions_from(self):
        # type: () -> EntityCollection[UnifiedRoleDefinition]
        """
        Read-only collection of role definitions that the given role definition inherits from. Only Azure AD built-in
        roles (isBuiltIn is true) support this attribute. Supports $expand.
        """
        return self.properties.get(
            "inheritsPermissionsFrom",
            EntityCollection(
                self.context,
                UnifiedRoleDefinition,
                ResourcePath("inheritsPermissionsFrom", self.resource_path),
            ),
        )

    def get_property(self, name, default_value=None):
        if default_value is None:
            property_mapping = {
                "inheritsPermissionsFrom": self.inherits_permissions_from,
            }
            default_value = property_mapping.get(name, None)
        return super(UnifiedRoleDefinition, self).get_property(name, default_value)

Parameters

Parameter Details

context: The client context object used for making API requests to Microsoft Graph. Inherited from Entity base class.

resource_path: The OData resource path identifying this specific role definition entity. Inherited from Entity base class.

properties: Dictionary containing the role definition properties retrieved from the API. Inherited from Entity base class.

Return Value

Instantiation returns a UnifiedRoleDefinition object representing an Azure AD role definition. The object provides property accessors that return: display_name (Optional[str]), is_built_in (Optional[bool]), role_permissions (ClientValueCollection[UnifiedRolePermission]), and inherits_permissions_from (EntityCollection[UnifiedRoleDefinition]). The get_property method returns the requested property value or a default value if not found.

Class Interface

Methods

Attributes

Dependencies

• typing
• office365.directory.rolemanagement.unified_role_permission
• office365.entity
• office365.entity_collection
• office365.runtime.client_value_collection
• office365.runtime.paths.resource_path

Required Imports

from typing import Optional
from office365.directory.rolemanagement.unified_role_permission import UnifiedRolePermission
from office365.entity import Entity
from office365.entity_collection import EntityCollection
from office365.runtime.client_value_collection import ClientValueCollection
from office365.runtime.paths.resource_path import ResourcePath

Usage Example

from office365.graph_client import GraphClient
from office365.directory.rolemanagement.unified_role_definition import UnifiedRoleDefinition

# Initialize Graph client with credentials
client = GraphClient.with_token(lambda: 'your_access_token')

# Get a specific role definition
role_def = client.directory.role_definitions.get_by_id('role-id').get().execute_query()

# Access role properties
print(f"Display Name: {role_def.display_name}")
print(f"Is Built-in: {role_def.is_built_in}")

# Access role permissions
for permission in role_def.role_permissions:
    print(f"Permission: {permission}")

# Get inherited role definitions (for built-in roles)
inherited_roles = role_def.inherits_permissions_from
for inherited_role in inherited_roles:
    print(f"Inherits from: {inherited_role.display_name}")

# Use get_property for dynamic property access
display_name = role_def.get_property('displayName')
inherited = role_def.get_property('inheritsPermissionsFrom')

Best Practices

• Always ensure the client context is properly authenticated before accessing role definition properties
• Use execute_query() to fetch data from the API before accessing properties
• The is_built_in property determines whether the role is a default Azure AD role or custom; built-in roles support inheritance
• The inherits_permissions_from collection is only populated for built-in roles (when is_built_in is true)
• Role permissions are read-only when is_built_in is true
• Use get_property() method for dynamic property access with fallback defaults
• The class follows lazy loading patterns - collections are only loaded when accessed
• Properties return None if not set or not yet loaded from the API
• This is a read-focused class; modifications to role definitions typically require separate API calls

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class UnifiedRoleAssignment 77.6% similar

  Represents a role assignment in Microsoft Graph API that grants access to resources by associating a role definition with a principal (user or group) at a specific scope.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/rolemanagement/unified_role_assignment.py

• class DirectoryRole 74.0% similar

  Represents an Azure AD directory role (also known as administrator roles) with properties like description, display name, and members.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/rolemanagement/role.py

• class AppRole 68.7% similar

  Represents an application role in Microsoft Graph API that can be assigned to users, groups, or other applications to define permissions and access control.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/applications/roles/role.py

• class RoleManagement 67.7% similar

  A class representing Microsoft 365 role-based access control (RBAC) role management entity that provides access to role definitions and assignments from various RBAC providers.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/rolemanagement/management.py

• class RoleDefinition 66.1% similar

  Defines a single role definition, including a name, description, and set of rights.

  From: /tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/sharepoint/permissions/roles/definitions/definition.py