class PermissionScope
Represents a delegated permission definition for Microsoft identity platform applications, encapsulating permission metadata such as consent descriptions and enabled status.
/tf/active/vicechatdev/SPFCsync/venv/lib64/python3.11/site-packages/office365/directory/permissions/scope.py
4 - 36
simple
Purpose
This class models a delegated permission scope that can be requested by client applications to access APIs on the Microsoft identity platform. It stores permission metadata including admin consent information, unique identifiers, and enabled state. Delegated permissions can be requested dynamically via the scopes parameter in authorization requests or statically through the requiredResourceAccess collection. This class inherits from ClientValue, making it suitable for serialization and transmission in API requests/responses related to Microsoft Graph or Azure AD application permissions.
Source Code
class PermissionScope(ClientValue):
"""
Represents the definition of a delegated permission.
Delegated permissions can be requested by client applications needing an access token to the API which defined the
permissions. Delegated permissions can be requested dynamically, using the scopes parameter in an authorization
request to the Microsoft identity platform, or statically, through the requiredResourceAccess collection on the
application object.
"""
def __init__(
self,
admin_consent_display_name=None,
admin_consent_description=None,
_id=None,
is_enabled=None,
):
"""
:param str admin_consent_display_name: The permission's title, intended to be read by an administrator granting
the permission on behalf of all users.
:param str admin_consent_description: A description of the delegated permissions, intended to be read
by an administrator granting the permission on behalf of all users. This text appears in tenant-wide
admin consent experiences.
:param str _id: Unique delegated permission identifier inside the collection of delegated permissions defined
for a resource application.
:param str is_enabled: When creating or updating a permission, this property must be set to true
(which is the default). To delete a permission, this property must first be set to false.
At that point, in a subsequent call, the permission may be removed.
"""
self.adminConsentDescription = admin_consent_description
self.adminConsentDisplayName = admin_consent_display_name
self.id = _id
self.isEnabled = is_enabledParameters
| Name | Type | Default | Kind |
|---|---|---|---|
bases |
ClientValue | - |
Parameter Details
admin_consent_display_name: The human-readable title of the permission intended for administrators. This text is displayed when an administrator grants the permission on behalf of all users in the organization. Optional string parameter, defaults to None.
admin_consent_description: A detailed description of what the delegated permission allows, written for administrators who grant consent on behalf of all users. This text appears in tenant-wide admin consent experiences. Optional string parameter, defaults to None.
_id: A unique identifier (GUID format typically) for this delegated permission within the collection of permissions defined for a resource application. This distinguishes the permission from others in the same application. Optional string parameter, defaults to None.
is_enabled: Boolean flag indicating whether the permission is active. Must be set to true when creating or updating a permission (default behavior). To delete a permission, this must first be set to false, then the permission can be removed in a subsequent operation. Optional parameter, defaults to None.
Return Value
Instantiation returns a PermissionScope object with four instance attributes: adminConsentDescription, adminConsentDisplayName, id, and isEnabled. These attributes map to the constructor parameters and are used for serialization when interacting with Microsoft identity platform APIs. The class inherits from ClientValue which likely provides serialization/deserialization capabilities.
Class Interface
Methods
__init__(self, admin_consent_display_name=None, admin_consent_description=None, _id=None, is_enabled=None)
Purpose: Initializes a new PermissionScope instance with delegated permission metadata
Parameters:
admin_consent_display_name: Optional string for the permission's display title shown to administratorsadmin_consent_description: Optional string describing the permission for administrator consent flows_id: Optional string containing the unique identifier for this permissionis_enabled: Optional boolean indicating if the permission is active (default behavior is True when used)
Returns: None (constructor)
Attributes
| Name | Type | Description | Scope |
|---|---|---|---|
adminConsentDescription |
str or None | Stores the detailed description of the delegated permission for administrator consent experiences | instance |
adminConsentDisplayName |
str or None | Stores the human-readable title of the permission displayed to administrators | instance |
id |
str or None | Stores the unique identifier (typically GUID) for this delegated permission | instance |
isEnabled |
bool or None | Stores the enabled state of the permission; must be True for active permissions, False before deletion | instance |
Dependencies
office365
Required Imports
from office365.runtime.client_value import ClientValue
Usage Example
from office365.runtime.client_value import ClientValue
from office365.entity_types.permission_scope import PermissionScope
# Create a new delegated permission scope
permission = PermissionScope(
admin_consent_display_name="Read user files",
admin_consent_description="Allows the app to read files on behalf of the signed-in user",
_id="e1fe6dd8-ba31-4d61-89e7-88639da4683d",
is_enabled=True
)
# Access the attributes
print(permission.adminConsentDisplayName) # Output: Read user files
print(permission.id) # Output: e1fe6dd8-ba31-4d61-89e7-88639da4683d
print(permission.isEnabled) # Output: True
# Disable a permission (first step before deletion)
permission.isEnabled = False
# Create a minimal permission scope
minimal_permission = PermissionScope(_id="abc-123-def")Best Practices
- Always provide meaningful admin_consent_display_name and admin_consent_description values to help administrators understand what permissions they are granting
- Set is_enabled to True when creating new permissions or updating existing ones
- To delete a permission, follow the two-step process: first set is_enabled to False, then remove the permission in a subsequent operation
- Use unique, stable identifiers for the _id parameter, typically GUIDs, to avoid conflicts with other permissions
- This class is a data container (value object) and does not perform validation or API calls itself - it's meant to be used with other components that handle Microsoft Graph API interactions
- The attribute names use camelCase (adminConsentDescription, isEnabled) to match Microsoft Graph API conventions, while constructor parameters use snake_case following Python conventions
- Since this inherits from ClientValue, it likely supports serialization to/from JSON for API communication - ensure all attributes are JSON-serializable types
Tags
Similar Components
AI-powered semantic similarity - components with related functionality:
-
class OAuth2PermissionGrant 76.1% similar
-
class AccessReviewScope 63.0% similar
-
class ResourceSpecificPermissionGrant 61.0% similar
-
class UserConsentRequest 59.5% similar
-
class AppConsentRequest 59.3% similar