openedx_authz.rest_api package

openedx_authz.rest_api package#

Subpackages#

Submodules#

openedx_authz.rest_api.data module#

Data classes and enums for the Open edX AuthZ REST API.

class openedx_authz.rest_api.data.AssignmentSortField(*values)

Bases: BaseEnum

Enum for the role assignment fields to sort by.

ORG = 'org'
ROLE = 'role'
SCOPE = 'scope'
class openedx_authz.rest_api.data.BaseEnum(new_class_name, /, names, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: str, Enum

Base enum class.

classmethod values()

List the values of the enum.

class openedx_authz.rest_api.data.RoleOperationError(*values)

Bases: BaseEnum

Enum for errors that can occur during role assignment and removal operations.

ROLE_ASSIGNMENT_ERROR = 'role_assignment_error'
ROLE_REMOVAL_ERROR = 'role_removal_error'
USER_ALREADY_HAS_ROLE = 'user_already_has_role'
USER_DOES_NOT_HAVE_ROLE = 'user_does_not_have_role'
USER_NOT_FOUND = 'user_not_found'
class openedx_authz.rest_api.data.RoleOperationStatus(*values)

Bases: BaseEnum

Enum for the status of role assignment and removal operations.

ROLE_ADDED = 'role_added'
ROLE_REMOVED = 'role_removed'
class openedx_authz.rest_api.data.ScopesQuerySetFields(*values)

Bases: BaseEnum

Enum for the annotated fields used in the Scopes query set for the scopes endpoint

DISPLAY_NAME_COL = 'display_name_col'
ORG_NAME = 'org_name'
SCOPE_ID = 'scope_id'
SCOPE_TYPE = 'scope_type'
class openedx_authz.rest_api.data.ScopesTypeField(*values)

Bases: BaseEnum

Enum for the scope_type query field on the scopes endpoint

COURSE = 'course'
LIBRARY = 'library'
class openedx_authz.rest_api.data.SearchField(*values)

Bases: BaseEnum

Enum for the fields allowed for text search filtering.

EMAIL = 'email'
FULL_NAME = 'full_name'
USERNAME = 'username'
class openedx_authz.rest_api.data.SerializedAssignment

Bases: TypedDict

Shape of an inline assignment as produced by TeamMemberAssignmentInlineSerializer.

org: str
permission_count: int
role: str
scope: str
scope_display_name: str
class openedx_authz.rest_api.data.SortField(*values)

Bases: BaseEnum

Enum for the fields to sort by.

EMAIL = 'email'
FULL_NAME = 'full_name'
USERNAME = 'username'
class openedx_authz.rest_api.data.SortOrder(*values)

Bases: BaseEnum

Enum for the order to sort by.

ASC = 'asc'
DESC = 'desc'
class openedx_authz.rest_api.data.UserAssignmentSortField(*values)

Bases: BaseEnum

Enum for the user role assignment fields to sort by.

EMAIL = 'email'
FULL_NAME = 'full_name'
ORG = 'org'
ROLE = 'role'
SCOPE = 'scope'
USERNAME = 'username'

openedx_authz.rest_api.decorators module#

Decorators for the Open edX AuthZ REST API.

openedx_authz.rest_api.decorators.authz_permissions(permissions: list[str])

Decorator to attach required permissions to view methods.

This decorator stores a list of permission identifiers that will be checked by MethodPermissionMixin during authorization.

Parameters:

permissions – List of permission identifiers e.g., [“content_libraries.view_library_team”, “content_libraries.manage_library_team”])

Examples

>>> class MyView(APIView):
...     @authz_permissions(["content_libraries.view_library_team"])
...     def get(self, request):
...         pass
...
...     @authz_permissions(["content_libraries.manage_library_team"])
...     def post(self, request):
...         pass
openedx_authz.rest_api.decorators.view_auth_classes(is_authenticated=True)

Function and class decorator that abstracts the authentication and permission checks for api views.

Parameters:

is_authenticated – Whether the view requires authentication.

Returns:

The decorated view or class.

Examples

>>> @view_auth_classes(is_authenticated=False)
... class MyView(APIView):
...     def get(self, request):
...         return Response("Hello, world!")

openedx_authz.rest_api.urls module#

Open edX AuthZ API URLs.

openedx_authz.rest_api.utils module#

Utility functions for the Open edX AuthZ REST API.

openedx_authz.rest_api.utils.filter_users(users: list[dict], search: str | None, roles: list[str] | None) → list[dict]

Filter users by a case-insensitive search string and/or by roles.

Parameters:

  • users (list[dict]) – The users to filter.

  • search (str | None) – Optional search term matched against fields in SearchField.

  • roles (list[str] | None) – Optional list of roles; include users that have any of these roles.

Returns:

The filtered users, preserving the original order.

Return type:

list[dict]

openedx_authz.rest_api.utils.get_generic_scope(scope: ScopeData) → ScopeData

Create a generic scope from a given scope by replacing its key with a wildcard.

This function preserves the namespace of the original scope but replaces the specific key with a wildcard, allowing for broader permission checks across all scopes within the same namespace.

Parameters:

scope (ScopeData) – The specific scope to generalize.

Returns:

A new scope with the same namespace but a wildcard key.

Return type:

ScopeData

Examples

>>> scope = ScopeData(namespaced_key="lib^lib:DemoX:CSPROB")
>>> get_generic_scope(scope)
ScopeData(namespaced_key="lib^*")
openedx_authz.rest_api.utils.inject_scope_display_names(assignments: list[SerializedAssignment]) → None

Set scope_display_name in-place on serialized assignments using one bulk lookup.

Callers must pass only the assignments of the current page, after filtering, sorting and pagination. This avoids DB lookups for assignments that are not in the response and keeps the cost at one batched query per scope type (libraries and courses) instead of one per assignment. Unresolvable scopes (globs, superadmin entries, missing resources) get an empty string.

Parameters:

assignments – Serialized assignments for the current page. Each one must have a scope key. They are modified in-place, and scope_display_name is set on every entry.

openedx_authz.rest_api.utils.sort_assignments(assignments: list[dict], sort_by: AssignmentSortField = AssignmentSortField.ROLE, order: SortOrder = SortOrder.ASC) → list[dict]

Sort role assignments by a given field and order.

Parameters:

  • assignments (list[dict]) – The assignments to sort.

  • sort_by (AssignmentSortField, optional) – The field to sort by. Defaults to AssignmentSortField.ROLE.

  • order (SortOrder, optional) – The order to sort by. Defaults to SortOrder.ASC.

Raises:
Returns:

The sorted assignments.

Return type:

list[dict]

openedx_authz.rest_api.utils.sort_user_assignments(assignments: list[dict], sort_by: UserAssignmentSortField = UserAssignmentSortField.ROLE, order: SortOrder = SortOrder.ASC) → list[dict]

Sort role assignments by a given field and order.

Parameters:

  • assignments (list[dict]) – The assignments to sort.

  • sort_by (UserAssignmentSortField, optional) – The field to sort by. Defaults to UserAssignmentSortField.ROLE.

  • order (SortOrder, optional) – The order to sort by. Defaults to SortOrder.ASC.

Raises:
Returns:

The sorted assignments.

Return type:

list[dict]

openedx_authz.rest_api.utils.sort_users(users: list[dict], sort_by: SortField = SortField.USERNAME, order: SortOrder = SortOrder.ASC) → list[dict]

Sort users by a given field and order.

Parameters:

  • users (list[dict]) – The users to sort.

  • sort_by (SortField, optional) – The field to sort by. Defaults to SortField.USERNAME.

  • order (SortOrder, optional) – The order to sort by. Defaults to SortOrder.ASC.

Raises:
Returns:

The sorted users.

Return type:

list[dict]

Module contents#