openedx_authz.api package#
Submodules#
openedx_authz.api.data module#
Data classes and enums for representing roles, permissions, and policies.
- class openedx_authz.api.data.ActionData(external_key: str = '', namespaced_key: str = '')
Bases:
AuthZDataAn action represents an operation that can be performed in the authorization system.
Actions are the operations that can be allowed or denied in authorization policies.
- NAMESPACE
‘act’ for actions.
- Type:
ClassVar[str]
- external_key
The action identifier (e.g., ‘content_libraries.view_library’).
- Type:
- namespaced_key
The action identifier with namespace (e.g., ‘act^content_libraries.view_library’).
- Type:
- name
Property that returns a human-readable action name (e.g., ‘Content Libraries > View Library’).
Examples
>>> action = ActionData(external_key='content_libraries.delete_library') >>> action.namespaced_key 'act^content_libraries.delete_library' >>> action.name 'Content Libraries > Delete Library'
- property name: str
The human-readable name of the action (e.g., ‘Content Libraries > Delete Library’).
This property transforms the external_key into a human-readable display name by replacing dots with ‘ > ‘ and capitalizing each word.
- Returns:
The human-readable action name (e.g., ‘Content Libraries > Delete Library’).
- Return type:
- class openedx_authz.api.data.ContentLibraryData(*args, **kwargs)
Bases:
ScopeDataA content library scope for authorization in the Open edX platform.
Content libraries use the LibraryLocatorV2 format for identification.
- NAMESPACE
‘lib’ for content library scopes.
- Type:
ClassVar[str]
- external_key
The content library identifier (e.g., ‘lib:DemoX:CSPROB’). Must be a valid LibraryLocatorV2 format.
- Type:
- namespaced_key
The library identifier with namespace (e.g., ‘lib^lib:DemoX:CSPROB’).
- Type:
- library_id
Property alias for external_key.
Examples
>>> library = ContentLibraryData(external_key='lib:DemoX:CSPROB') >>> library.namespaced_key 'lib^lib:DemoX:CSPROB' >>> library.library_id 'lib:DemoX:CSPROB'
Note
TODO: this class should live alongside library definitions and not here.
- exists() bool
Check if the content library exists.
- Returns:
True if the content library exists, False otherwise.
- Return type:
- get_object() ContentLibrary | None
Retrieve the ContentLibrary instance associated with this scope.
This method converts the library_id to a LibraryLocatorV2 key and queries the database to fetch the corresponding ContentLibrary object.
- Returns:
- The ContentLibrary instance if found in the database,
or None if the library does not exist or has an invalid key format.
- Return type:
ContentLibrary | None
Examples
>>> library_scope = ContentLibraryData(external_key='lib:DemoX:CSPROB') >>> library_obj = library_scope.get_object() # ContentLibrary object
- property library_id: str
CSPROB’).
This is an alias for external_key that represents the library ID without the namespace prefix.
- Returns:
The library identifier without namespace.
- Return type:
- Type:
The library identifier as used in Open edX (e.g., ‘lib
- Type:
DemoX
- property library_key: LibraryLocatorV2
The LibraryLocatorV2 object for the content library.
- Returns:
The library locator object.
- Return type:
LibraryLocatorV2
- class openedx_authz.api.data.GroupingPolicyIndex(*values)
Bases:
EnumIndex positions for fields in a Casbin grouping policy (g or g2).
Grouping policies represent role assignments that link subjects to roles within scopes. Format: [subject, role, scope, …]
- SUBJECT
Position 0 - The subject identifier (e.g., ‘user^john_doe’).
- ROLE
Position 1 - The role identifier (e.g., ‘role^instructor’).
- SCOPE
Position 2 - The scope identifier (e.g., ‘lib^lib:DemoX:CSPROB’).
Note
Additional fields beyond position 2 are optional and currently ignored.
- ROLE = 1
- SCOPE = 2
- SUBJECT = 0
- class openedx_authz.api.data.PermissionData(action: ActionData = None, effect: Literal['allow', 'deny'] = 'allow')
Bases:
objectA permission combines an action with an effect (allow or deny).
Permissions define whether a specific action should be allowed or denied. They are typically associated with roles in the authorization system.
- action
The action being permitted or denied (ActionData instance).
- Type:
openedx_authz.api.data.ActionData
- effect
The effect of the permission, either ‘allow’ or ‘deny’ (default: ‘allow’).
- Type:
Literal[‘allow’, ‘deny’]
Examples
>>> read_action = ActionData(external_key='read') >>> permission = PermissionData(action=read_action, effect='allow') >>> str(permission) 'Read - allow' >>> write_action = ActionData(external_key='write') >>> deny_perm = PermissionData(action=write_action, effect='deny') >>> str(deny_perm) 'Write - deny'
- action: ActionData
- effect: Literal['allow', 'deny']
- class openedx_authz.api.data.PolicyIndex(*values)
Bases:
EnumIndex positions for fields in a Casbin policy (p).
Policies define permissions by linking roles to actions within scopes with an effect. Format: [role, action, scope, effect, …]
- ROLE
Position 0 - The role identifier (e.g., ‘role^instructor’).
- ACT
Position 1 - The action identifier (e.g., ‘act^read’).
- SCOPE
Position 2 - The scope identifier (e.g., ‘lib^lib:DemoX:CSPROB’).
- EFFECT
Position 3 - The effect, either ‘allow’ or ‘deny’.
Note
Additional fields beyond position 3 are optional and currently ignored.
- ACT = 1
- EFFECT = 3
- ROLE = 0
- SCOPE = 2
- class openedx_authz.api.data.RoleAssignmentData(subject: SubjectData = None, roles: list[RoleData] = [], scope: ScopeData = None)
Bases:
objectA role assignment links a subject, roles, and a scope together.
Role assignments represent the authorization grants in the system. They specify that a particular subject (e.g., a user) has certain roles within a specific scope (e.g., a content library).
- subject
The subject (e.g., UserData) to whom roles are assigned.
- Type:
openedx_authz.api.data.SubjectData
- roles
A list of RoleData instances being assigned to the subject.
- Type:
list[openedx_authz.api.data.RoleData]
- scope
The scope (e.g., ContentLibraryData) in which the roles apply.
- Type:
openedx_authz.api.data.ScopeData
Examples
>>> user = UserData(external_key='john_doe') >>> role = RoleData(external_key='instructor') >>> library = ContentLibraryData(external_key='lib:DemoX:CSPROB') >>> assignment = RoleAssignmentData(subject=user, roles=[role], scope=library) >>> str(assignment) 'john_doe => Instructor @ lib:DemoX:CSPROB' >>> repr(assignment) 'user^john_doe => [role^instructor] @ lib^lib:DemoX:CSPROB'
- roles: list[RoleData]
- scope: ScopeData
- subject: SubjectData
- class openedx_authz.api.data.RoleData(external_key: str = '', namespaced_key: str = '', permissions: list[PermissionData] = [])
Bases:
AuthZDataA role is a named collection of permissions that can be assigned to subjects.
Roles group related permissions together for easier authorization management.
- NAMESPACE
‘role’ for roles.
- Type:
ClassVar[str]
- external_key
The role identifier (e.g., ‘instructor’, ‘library_admin’).
- Type:
- namespaced_key
The role identifier with namespace (e.g., ‘role^instructor’).
- Type:
- permissions
A list of PermissionData instances associated with this role.
- Type:
list[openedx_authz.api.data.PermissionData]
- name
Property that returns a human-readable role name (e.g., ‘Instructor’, ‘Library Admin’).
Examples
>>> role = RoleData(external_key='instructor') >>> role.namespaced_key 'role^instructor' >>> role.name 'Instructor' >>> action = ActionData(external_key='read') >>> perm = PermissionData(action=action, effect='allow') >>> role_with_perms = RoleData(external_key='instructor', permissions=[perm]) >>> str(role_with_perms) 'Instructor: Read - allow'
- get_permission_identifiers() list[str]
Get the technical identifiers for all permissions in this role.
- property name: str
The human-readable name of the role (e.g., ‘Library Admin’, ‘Course Instructor’).
This property transforms the external_key into a human-readable display name by replacing underscores with spaces and capitalizing each word.
- Returns:
The human-readable role name (e.g., ‘Library Admin’).
- Return type:
- permissions: list[PermissionData]
- class openedx_authz.api.data.ScopeData(*args, **kwargs)
Bases:
AuthZDataA scope is a context in which roles and permissions are assigned.
This is the base class for scope types. Specific scope types (like ContentLibraryData) are subclasses with their own namespace prefixes. This class is supposed to be generic and not tied to any specific scope type, holding attributes common to all scopes.
- NAMESPACE
‘global’ for generic scopes.
- Type:
ClassVar[str]
- external_key
The scope identifier without namespace (e.g., ‘generic_scope’).
- Type:
- namespaced_key
The scope identifier with namespace (e.g., ‘global^generic_scope’).
- Type:
Examples
>>> scope = ScopeData(external_key='generic_scope') >>> scope.namespaced_key 'global^generic_scope'
- abstractmethod exists() bool
Check if the scope exists.
- Returns:
True if the scope exists, False otherwise.
- Return type:
- abstractmethod get_object() Any | None
Retrieve the underlying domain object that this scope represents.
This method fetches the actual Open edX object (e.g., ContentLibrary, Organization) associated with this scope’s external_key. Subclasses should implement this to return their specific object types.
- Returns:
- The domain object associated with this scope, or None if the object
does not exist or cannot be retrieved.
- Return type:
Any | None
- classmethod validate_external_key(_: str) bool
Validate the external_key format for ScopeData.
For the base ScopeData class, we accept any external_key works. This is only implemented for the sake of completeness. Subclasses should implement their own validation logic.
- Parameters:
external_key – The external key to validate.
- Returns:
True if valid, False otherwise.
- Return type:
- class openedx_authz.api.data.SubjectData(*args, **kwargs)
Bases:
AuthZDataA subject is an entity that can be assigned roles and permissions.
This is the base class for subject types. Specific subject types (like UserData) are subclasses with their own namespace prefixes.
- NAMESPACE
‘sub’ for generic subjects.
- Type:
ClassVar[str]
- external_key
The subject identifier without namespace (e.g., ‘generic’).
- Type:
- namespaced_key
The subject identifier with namespace (e.g., ‘sub^generic’).
- Type:
Examples
>>> subject = SubjectData(external_key='generic') >>> subject.namespaced_key 'sub^generic'
- class openedx_authz.api.data.UserData(*args, **kwargs)
Bases:
SubjectDataA user subject for authorization in the Open edX platform.
This class represents individual users who can be assigned roles and permissions. Can be initialized with either external_key or namespaced_key parameter.
- NAMESPACE
‘user’ for user subjects.
- Type:
ClassVar[str]
- external_key
The username (e.g., ‘john_doe’).
- Type:
- namespaced_key
The username with namespace prefix (e.g., ‘user^john_doe’).
- Type:
- username
Property alias for external_key.
Examples
>>> user = UserData(external_key='john_doe') >>> user.namespaced_key 'user^john_doe' >>> user.username 'john_doe' >>> user2 = UserData(namespaced_key='user^jane_smith') >>> user2.username 'jane_smith'
openedx_authz.api.permissions module#
Public API for permissions management.
A permission is the authorization granted by a policy. It represents the allowed actions(s) a subject can perform on an object. In Casbin, permissions are not explicitly defined, but are inferred from the policy rules.
- openedx_authz.api.permissions.get_all_permissions_in_scope(scope: ScopeData) list[PermissionData]
Retrieve all permissions associated with a specific scope.
- Parameters:
scope – The scope to filter permissions by.
- Returns:
A list of PermissionData objects associated with the given scope.
- Return type:
list of PermissionData
- openedx_authz.api.permissions.get_permission_from_policy(policy: list[str]) PermissionData
Convert a Casbin policy list to a PermissionData object.
- Parameters:
policy – A list representing a Casbin policy.
- Returns:
The corresponding PermissionData object or an empty PermissionData if the policy is invalid.
- Return type:
PermissionData
- openedx_authz.api.permissions.is_subject_allowed(subject: SubjectData, action: ActionData, scope: ScopeData) bool
Check if a subject has a specific permission in a given scope.
- Parameters:
subject – The subject to check (e.g., user or service).
action – The action to check (e.g., ‘view_course’).
scope – The scope in which to check the permission (e.g., ‘course-v1:edX+DemoX+2021_T1’).
- Returns:
True if the subject has the specified permission in the scope, False otherwise.
- Return type:
openedx_authz.api.roles module#
Public API for roles management.
A role is named group of permissions (actions). Instead of assigning permissions to each subject, permissions can be assigned to a role, and subjects inherit the role’s permissions.
We’ll interact with roles through this API, which will use the enforcer internally to manage the underlying policies and role assignments.
- openedx_authz.api.roles.assign_role_to_subject_in_scope(subject: SubjectData, role: RoleData, scope: ScopeData) bool
Assign a role to a subject.
- Parameters:
subject – The ID of the subject.
role – The role to assign.
scope – The scope to assign the role to.
- Returns:
True if the role was assigned successfully, False otherwise.
- Return type:
- openedx_authz.api.roles.batch_assign_role_to_subjects_in_scope(subjects: list[SubjectData], role: RoleData, scope: ScopeData) None
Assign a role to a list of subjects.
- Parameters:
subjects – A list of subject IDs.
role – The role to assign.
- openedx_authz.api.roles.batch_unassign_role_from_subjects_in_scope(subjects: list[SubjectData], role: RoleData, scope: ScopeData) None
Unassign a role from a list of subjects.
- Parameters:
subjects – A list of subject IDs.
role_name – The external_key of the role.
scope – The scope from which to unassign the role.
- openedx_authz.api.roles.get_all_roles_in_scope(scope: ScopeData) list[list[str]]
Get all the available role grouping policies in a specific scope.
- openedx_authz.api.roles.get_all_roles_names() list[str]
Get all the available roles names in the current environment.
- openedx_authz.api.roles.get_all_subject_role_assignments_in_scope(scope: ScopeData) list[RoleAssignmentData]
Get all the subjects assigned to any role in a specific scope.
- Parameters:
scope – The ScopeData object representing the scope (e.g., ScopeData(external_key=’lib:DemoX:CSPROB’)).
- Returns:
A list of role assignments for all subjects in the specified scope.
- Return type:
list[RoleAssignmentData]
- openedx_authz.api.roles.get_permissions_for_active_roles_in_scope(scope: ScopeData, role: RoleData | None = None) dict[str, dict[str, list[PermissionData | str]]]
Retrieve all permissions granted by the specified roles within the given scope.
This function operates on the principle that roles defined in policies are templates that become active only when assigned to subjects with specific scopes.
Role Definition vs Role Assignment:
Policy roles define potential permissions with namespace patterns (e.g., ‘lib^*’)
Actual permissions are granted only when roles are assigned to subjects with concrete scopes (e.g., ‘lib^lib:DemoX:CSPROB’)
The namespace pattern in the policy (‘lib^*’) indicates the role is designed for resources in that namespace, but doesn’t grant blanket access
The specific scope at assignment time (‘lib^lib:DemoX:CSPROB’) determines the exact resource the permissions apply to
Behavior:
Returns permissions only for roles that have been assigned to subjects
Unassigned roles (those defined in policy but not given to any subject) contribute no permissions to the result
Scope filtering ensures permissions are returned only for the specified resource scope, not for the broader namespace pattern
- openedx_authz.api.roles.get_permissions_for_roles(roles: list[RoleData]) dict[str, dict[str, list[PermissionData | str]]]
Get the permissions (actions) for a list of roles.
- openedx_authz.api.roles.get_permissions_for_single_role(role: RoleData) list[PermissionData]
Get the permissions (actions) for a single role.
- Parameters:
role – A RoleData object representing the role.
- Returns:
A list of PermissionData objects associated with the given role.
- Return type:
list[PermissionData]
- openedx_authz.api.roles.get_role_definitions_in_scope(scope: ScopeData) list[RoleData]
Get all role definitions available in a specific scope.
See get_permissions_for_active_roles_in_scope for explanation of role definitions vs assignments.
- Parameters:
scope – The scope to filter roles (e.g., ‘lib^*’ or ‘*’ for global).
- Returns:
A list of roles.
- Return type:
list[Role]
- openedx_authz.api.roles.get_scopes_for_subject_and_permission(subject: SubjectData, permission: PermissionData) list[ScopeData]
Get all scopes where a specific subject has been assigned a specific permission via roles.
- Parameters:
permission (PermissionData) – The permission to filter scopes.
subject (SubjectData) – The subject to filter scopes.
- Returns:
A list of scopes where the subject is assigned the specified permission.
- Return type:
list[ScopeData]
- openedx_authz.api.roles.get_subject_role_assignments(subject: SubjectData) list[RoleAssignmentData]
Get all the roles for a subject across all scopes.
- Parameters:
subject – The SubjectData object representing the subject (e.g., SubjectData(external_key=’john_doe’)).
- Returns:
A list of role assignments for the subject.
- Return type:
list[RoleAssignmentData]
- openedx_authz.api.roles.get_subject_role_assignments_for_role_in_scope(role: RoleData, scope: ScopeData) list[RoleAssignmentData]
Get the subjects assigned to a specific role in a specific scope.
- Parameters:
role – The RoleData object representing the role (e.g., RoleData(external_key=’library_admin’)).
scope – The ScopeData object representing the scope (e.g., ScopeData(external_key=’lib:DemoX:CSPROB’)).
- Returns:
A list of subjects assigned to the specified role in the specified scope.
- Return type:
list[RoleAssignmentData]
- openedx_authz.api.roles.get_subject_role_assignments_in_scope(subject: SubjectData, scope: ScopeData) list[RoleAssignmentData]
Get the roles for a subject in a specific scope.
- Parameters:
subject – The SubjectData object representing the subject (e.g., SubjectData(external_key=’john_doe’)).
scope – The ScopeData object representing the scope (e.g., ScopeData(external_key=’lib:DemoX:CSPROB’)).
- Returns:
A list of role assignments for the subject in the scope.
- Return type:
list[RoleAssignmentData]
- openedx_authz.api.roles.unassign_role_from_subject_in_scope(subject: SubjectData, role: RoleData, scope: ScopeData) bool
Unassign a role from a subject.
- Parameters:
subject – The ID of the subject.
role – The role to unassign.
scope – The scope from which to unassign the role.
- Returns:
True if the role was unassigned successfully, False otherwise.
- Return type:
openedx_authz.api.users module#
User-related API methods for role assignments and retrievals.
This module provides user-related API methods for assigning roles to users, unassigning roles from users, and retrieving roles assigned to users within the Open edX AuthZ framework.
These methods internally namespace user identifiers to ensure consistency with the role management system, which uses namespaced subjects (e.g., ‘user^john_doe’).
- openedx_authz.api.users.assign_role_to_user_in_scope(user_external_key: str, role_external_key: str, scope_external_key: str) bool
Assign a role to a user in a specific scope.
- openedx_authz.api.users.batch_assign_role_to_users_in_scope(users: list[str], role_external_key: str, scope_external_key: str)
Assign a role to multiple users in a specific scope.
- openedx_authz.api.users.batch_unassign_role_from_users(users: list[str], role_external_key: str, scope_external_key: str)
Unassign a role from multiple users in a specific scope.
- openedx_authz.api.users.get_all_user_role_assignments_in_scope(scope_external_key: str) list[RoleAssignmentData]
Get all user role assignments in a specific scope.
- openedx_authz.api.users.get_scopes_for_user_and_permission(user_external_key: str, action_external_key: str) list[ScopeData]
Get all scopes where a specific user is assigned a specific permission.
- openedx_authz.api.users.get_user_role_assignments(user_external_key: str) list[RoleAssignmentData]
Get all roles for a user across all scopes.
- openedx_authz.api.users.get_user_role_assignments_for_role_in_scope(role_external_key: str, scope_external_key: str) list[RoleAssignmentData]
Get all users assigned to a specific role across all scopes.
- openedx_authz.api.users.get_user_role_assignments_in_scope(user_external_key: str, scope_external_key: str) list[RoleAssignmentData]
Get the roles assigned to a user in a specific scope.
- openedx_authz.api.users.get_users_for_role_in_scope(role_external_key: str, scope_external_key: str) list[UserData]
Get all the users assigned to a specific role in a specific scope.
- openedx_authz.api.users.is_user_allowed(user_external_key: str, action_external_key: str, scope_external_key: str) bool
Check if a user has a specific permission in a given scope.
- Parameters:
- Returns:
True if the user has the specified permission in the scope, False otherwise.
- Return type:
- openedx_authz.api.users.unassign_all_roles_from_user(user_external_key: str) bool
Unassign all roles from a user across all scopes.
Module contents#
Public API for the Open edX AuthZ framework.
This module provides a public API as part of the Open edX AuthZ framework. This is part of the Open edX Layer used to abstract the authorization engine and provide a simpler interface for other services in the Open edX ecosystem.