🔍 Code Extractor

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

Purpose

The AppRole class models application roles used in Azure AD/Microsoft 365 applications for role-based access control (RBAC). It encapsulates role metadata including who can be assigned the role (users, groups, or applications), role description, display name, and enabled status. This class is used when defining or querying application permissions and role assignments in Microsoft Graph API integrations.

Source Code

class AppRole(ClientValue):
    """
    Represents an application role that can be requested by (and granted to) a client application,
    or that can be used to assign an application to users or groups in a specified role.
    """

    def __init__(
        self,
        id_=None,
        allowed_member_types=None,
        description=None,
        display_name=None,
        is_enabled=None,
        origin=None,
        value=None,
    ):
        """
        :param list[str] allowed_member_types: Specifies whether this app role can be assigned to users and groups
            (by setting to ["User"]), to other application's (by setting to ["Application"], or both (by setting to
            ["User", "Application"]). App roles supporting assignment to other applications' service principals are
            also known as application permissions. The "Application" value is only supported for app roles defined
            on application entities.
        :param str value:
        """
        self.id = id_
        self.allowedMemberTypes = StringCollection(allowed_member_types)
        self.description = description
        self.displayName = display_name
        self.isEnabled = is_enabled
        self.origin = origin
        self.value = value

    def __str__(self):
        return "{0}  {1}".format(self.allowedMemberTypes, self.value)

    def __repr__(self):
        return "{0}".format(self.id)

Parameters

Parameter Details

id_: Unique identifier for the app role, typically a GUID string. Used to reference this specific role in the system.

allowed_member_types: List of strings specifying who can be assigned this role. Valid values are ['User'], ['Application'], or ['User', 'Application']. Determines if the role can be assigned to users/groups, other applications (application permissions), or both.

description: Human-readable text describing what this app role represents and what permissions or access it grants.

display_name: User-friendly name for the role that will be displayed in UI elements and consent screens.

is_enabled: Boolean flag indicating whether this app role is currently active and can be assigned. Disabled roles cannot be granted to new members.

origin: String indicating the source or origin of this app role definition (e.g., whether it was user-defined or system-generated).

value: The string value/claim that will be included in tokens when this role is assigned. This is the programmatic identifier used in authorization logic.

Return Value

Instantiation returns an AppRole object that inherits from ClientValue. The object contains all role metadata as instance attributes. The __str__ method returns a formatted string showing allowed member types and value. The __repr__ method returns the role's ID.

Class Interface

Methods

Attributes

Dependencies

• office365

Required Imports

from office365.runtime.client_value import ClientValue
from office365.runtime.types.collections import StringCollection

Usage Example

# Create an app role for users
from office365.runtime.client_value import ClientValue
from office365.runtime.types.collections import StringCollection

# Define a role that can be assigned to users
user_role = AppRole(
    id_='12345678-1234-1234-1234-123456789abc',
    allowed_member_types=['User'],
    description='Can read and write documents',
    display_name='Document Editor',
    is_enabled=True,
    origin='Application',
    value='Document.ReadWrite'
)

# Define an application permission role
app_permission = AppRole(
    id_='87654321-4321-4321-4321-cba987654321',
    allowed_member_types=['Application'],
    description='Allows the app to read all user profiles',
    display_name='Read All User Profiles',
    is_enabled=True,
    value='User.Read.All'
)

# Access role properties
print(user_role)  # Outputs: ['User']  Document.ReadWrite
print(repr(user_role))  # Outputs: 12345678-1234-1234-1234-123456789abc
print(user_role.displayName)  # Outputs: Document Editor

Best Practices

• Always provide a unique GUID for the id_ parameter when creating new app roles to avoid conflicts.
• Set allowed_member_types appropriately: use ['User'] for user-assignable roles, ['Application'] for application permissions, or both for hybrid scenarios.
• Ensure the value parameter uses a clear, namespaced format (e.g., 'Resource.Action.Scope') for consistency with Microsoft Graph conventions.
• Set is_enabled to False instead of deleting roles to maintain referential integrity with existing assignments.
• The display_name and description should be clear and user-friendly as they appear in consent dialogs and admin portals.
• This class is typically used as part of larger Microsoft Graph API operations, not instantiated in isolation.
• The allowedMemberTypes attribute is automatically wrapped in a StringCollection for proper serialization.
• This is an immutable data transfer object (DTO) - create new instances rather than modifying existing ones.

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• class AppRoleAssignment 83.4% similar

  Represents an app role assignment in Microsoft Graph API, recording when a user, group, or service principal is assigned an app role for an application.

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

• class DirectoryRole 70.8% 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 RoleManagement 70.3% 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 UnifiedRoleDefinition 68.7% similar

  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.

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

• class UnifiedRoleAssignment 67.8% 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