[FC-0099] feat: add rest api for roles and permissions (openedx#84)

Author: BryanttV

CHANGELOG.rst

@@ -33,3 +33,11 @@ Added
 * ADRs for key design decisions.
 * Casbin model (CONF) and engine layer for authorization.
 * Implementation of public API for roles and permissions management.
+
+0.3.0 - 2025-10-10
+******************
+
+Added
+=====
+
+* Implementation of REST API for roles and permissions management.

openedx_authz/__init__.py

@@ -4,6 +4,6 @@
 
 import os
 
-__version__ = "0.1.0"
+__version__ = "0.3.0"
 
 ROOT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))

openedx_authz/api/data.py

@@ -1,13 +1,19 @@
 """Data classes and enums for representing roles, permissions, and policies."""
 
 import re
+from abc import abstractmethod
 from enum import Enum
 from typing import ClassVar, Literal, Type
 
 from attrs import define
 from opaque_keys import InvalidKeyError
 from opaque_keys.edx.locator import LibraryLocatorV2
 
+try:
+    from openedx.core.djangoapps.content_libraries.models import ContentLibrary
+except ImportError:
+    ContentLibrary = None
+
 __all__ = [
     "UserData",
     "PermissionData",
@@ -18,10 +24,12 @@
     "RoleData",
     "ScopeData",
     "SubjectData",
+    "ContentLibraryData",
 ]
 
 AUTHZ_POLICY_ATTRIBUTES_SEPARATOR = "^"
 EXTERNAL_KEY_SEPARATOR = ":"
+GENERIC_SCOPE_WILDCARD = "*"
 NAMESPACED_KEY_PATTERN = rf"^.+{re.escape(AUTHZ_POLICY_ATTRIBUTES_SEPARATOR)}.+$"
 
 
@@ -249,6 +257,20 @@ def get_subclass_by_external_key(mcs, external_key: str) -> Type["ScopeData"]:
 
         return scope_subclass
 
+    @classmethod
+    def get_all_namespaces(mcs) -> dict[str, Type["ScopeData"]]:
+        """Get all registered scope namespaces.
+
+        Returns:
+            dict[str, Type["ScopeData"]]: A dictionary of all namespace prefixes registered in the scope registry.
+                Each namespace corresponds to a ScopeData subclass (e.g., 'lib', 'sc').
+
+        Examples:
+            >>> ScopeMeta.get_all_namespaces()
+            {'sc': ScopeData, 'lib': ContentLibraryData, 'org': OrganizationData}
+        """
+        return mcs.scope_registry
+
     @classmethod
     def validate_external_key(mcs, external_key: str) -> bool:
         """Validate the external_key format for the subclass.
@@ -301,6 +323,15 @@ def validate_external_key(cls, _: str) -> bool:
         """
         return True
 
+    @abstractmethod
+    def exists(self) -> bool:
+        """Check if the scope exists.
+
+        Returns:
+            bool: True if the scope exists, False otherwise.
+        """
+        raise NotImplementedError("Subclasses must implement exists method.")
+
 
 @define
 class ContentLibraryData(ScopeData):
@@ -355,6 +386,19 @@ def validate_external_key(cls, external_key: str) -> bool:
         except InvalidKeyError:
             return False
 
+    def exists(self) -> bool:
+        """Check if the content library exists.
+
+        Returns:
+            bool: True if the content library exists, False otherwise.
+        """
+        try:
+            library_key = LibraryLocatorV2.from_string(self.library_id)
+            ContentLibrary.objects.get_by_key(library_key=library_key)
+            return True
+        except ContentLibrary.DoesNotExist:
+            return False
+
     def __str__(self):
         """Human readable string representation of the content library."""
         return self.library_id
@@ -562,6 +606,15 @@ class PermissionData:
     action: ActionData = None
     effect: Literal["allow", "deny"] = "allow"
 
+    @property
+    def identifier(self) -> str:
+        """Get the permission identifier.
+
+        Returns:
+            str: The permission identifier (e.g., 'delete_library').
+        """
+        return self.action.external_key
+
     def __str__(self):
         """Human readable string representation of the permission and its effect."""
         return f"{self.action} - {self.effect}"
@@ -571,7 +624,7 @@ def __repr__(self):
         return f"{self.action.namespaced_key} => {self.effect}"
 
 
-@define
+@define(eq=False)
 class RoleData(AuthZData):
     """A role is a named collection of permissions that can be assigned to subjects.
 
@@ -600,6 +653,12 @@ class RoleData(AuthZData):
     NAMESPACE: ClassVar[str] = "role"
     permissions: list[PermissionData] = []
 
+    def __eq__(self, other):
+        """Compare roles based on their namespaced_key."""
+        if not isinstance(other, RoleData):
+            return False
+        return self.namespaced_key == other.namespaced_key
+
     @property
     def name(self) -> str:
         """The human-readable name of the role (e.g., 'Library Admin', 'Course Instructor').
@@ -612,6 +671,14 @@ def name(self) -> str:
         """
         return self.external_key.replace("_", " ").title()
 
+    def get_permission_identifiers(self) -> list[str]:
+        """Get the technical identifiers for all permissions in this role.
+
+        Returns:
+            list[str]: Permission identifiers (e.g., ['delete_library', 'edit_content']).
+        """
+        return [permission.identifier for permission in self.permissions]
+
     def __str__(self):
         """Human readable string representation of the role and its permissions."""
         return f"{self.name}: {', '.join(str(p) for p in self.permissions)}"

openedx_authz/api/permissions.py

@@ -42,9 +42,7 @@ def get_all_permissions_in_scope(scope: ScopeData) -> list[PermissionData]:
     Returns:
         list of PermissionData: A list of PermissionData objects associated with the given scope.
     """
-    actions = enforcer.get_filtered_policy(
-        PolicyIndex.SCOPE.value, scope.namespaced_key
-    )
+    actions = enforcer.get_filtered_policy(PolicyIndex.SCOPE.value, scope.namespaced_key)
     return [get_permission_from_policy(action) for action in actions]
 
 
@@ -63,6 +61,5 @@ def is_subject_allowed(
     Returns:
         bool: True if the subject has the specified permission in the scope, False otherwise.
     """
-    return enforcer.enforce(
-        subject.namespaced_key, action.namespaced_key, scope.namespaced_key
-    )
+    enforcer.load_policy()
+    return enforcer.enforce(subject.namespaced_key, action.namespaced_key, scope.namespaced_key)

openedx_authz/api/roles.py

@@ -114,6 +114,7 @@ def get_permissions_for_active_roles_in_scope(
         dict[str, list[PermissionData]]: A dictionary mapping the role external_key to its
         permissions and scopes.
     """
+    enforcer.load_policy()
     filtered_policy = enforcer.get_filtered_grouping_policy(
         GroupingPolicyIndex.SCOPE.value, scope.namespaced_key
     )
@@ -145,6 +146,7 @@ def get_role_definitions_in_scope(scope: ScopeData) -> list[RoleData]:
     Returns:
         list[Role]: A list of roles.
     """
+    enforcer.load_policy()
     policy_filtered = enforcer.get_filtered_policy(
         PolicyIndex.SCOPE.value, scope.namespaced_key
     )
@@ -190,21 +192,27 @@ def get_all_roles_in_scope(scope: ScopeData) -> list[list[str]]:
     Returns:
         list[list[str]]: A list of policies in the specified scope.
     """
+    enforcer.load_policy()
     return enforcer.get_filtered_grouping_policy(
         GroupingPolicyIndex.SCOPE.value, scope.namespaced_key
     )
 
 
 def assign_role_to_subject_in_scope(
     subject: SubjectData, role: RoleData, scope: ScopeData
-) -> None:
+) -> bool:
     """Assign a role to a subject.
 
     Args:
         subject: The ID of the subject.
         role: The role to assign.
+        scope: The scope to assign the role to.
+
+    Returns:
+        bool: True if the role was assigned successfully, False otherwise.
     """
-    enforcer.add_role_for_user_in_domain(
+    enforcer.load_policy()
+    return enforcer.add_role_for_user_in_domain(
         subject.namespaced_key,
         role.namespaced_key,
         scope.namespaced_key,
@@ -226,15 +234,19 @@ def batch_assign_role_to_subjects_in_scope(
 
 def unassign_role_from_subject_in_scope(
     subject: SubjectData, role: RoleData, scope: ScopeData
-) -> None:
+) -> bool:
     """Unassign a role from a subject.
 
     Args:
         subject: The ID of the subject.
         role: The role to unassign.
         scope: The scope from which to unassign the role.
+
+    Returns:
+        bool: True if the role was unassigned successfully, False otherwise.
     """
-    enforcer.delete_roles_for_user_in_domain(
+    enforcer.load_policy()
+    return enforcer.delete_roles_for_user_in_domain(
         subject.namespaced_key, role.namespaced_key, scope.namespaced_key
     )
 
@@ -291,6 +303,7 @@ def get_subject_role_assignments_in_scope(
     Returns:
         list[RoleAssignmentData]: A list of role assignments for the subject in the scope.
     """
+    enforcer.load_policy()
     # TODO: we still need to get the remaining data for the role like email, etc
     role_assignments = []
     for namespaced_key in enforcer.get_roles_for_user_in_domain(
@@ -378,3 +391,17 @@ def get_all_subject_role_assignments_in_scope(
         )
 
     return list(role_assignments_per_subject.values())
+
+
+def get_subjects_for_role(role: RoleData) -> list[SubjectData]:
+    """Get all the subjects assigned to a specific role.
+
+    Args:
+        role (RoleData): The role to filter subjects.
+
+    Returns:
+        list[SubjectData]: A list of subjects assigned to the specified role.
+    """
+    enforcer.load_policy()
+    policies = enforcer.get_filtered_grouping_policy(GroupingPolicyIndex.ROLE.value, role.namespaced_key)
+    return [SubjectData(namespaced_key=policy[GroupingPolicyIndex.SUBJECT.value]) for policy in policies]

openedx_authz/api/users.py

@@ -19,6 +19,7 @@
     get_subject_role_assignments,
     get_subject_role_assignments_for_role_in_scope,
     get_subject_role_assignments_in_scope,
+    get_subjects_for_role,
     unassign_role_from_subject_in_scope,
 )
 
@@ -32,29 +33,29 @@
     "get_user_role_assignments_for_role_in_scope",
     "get_all_user_role_assignments_in_scope",
     "is_user_allowed",
+    "get_users_for_role",
 ]
 
 
-def assign_role_to_user_in_scope(
-    user_external_key: str, role_external_key: str, scope_external_key: str
-) -> bool:
+def 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.
 
     Args:
         user (str): ID of the user (e.g., 'john_doe').
         role_external_key (str): Name of the role to assign.
         scope (str): Scope in which to assign the role.
+
+    Returns:
+        bool: True if the role was assigned successfully, False otherwise.
     """
-    assign_role_to_subject_in_scope(
+    return assign_role_to_subject_in_scope(
         UserData(external_key=user_external_key),
         RoleData(external_key=role_external_key),
         ScopeData(external_key=scope_external_key),
     )
 
 
-def batch_assign_role_to_users_in_scope(
-    users: list[str], role_external_key: str, scope_external_key: str
-):
+def 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.
 
     Args:
@@ -70,26 +71,25 @@ def batch_assign_role_to_users_in_scope(
     )
 
 
-def unassign_role_from_user(
-    user_external_key: str, role_external_key: str, scope_external_key: str
-):
+def unassign_role_from_user(user_external_key: str, role_external_key: str, scope_external_key: str):
     """Unassign a role from a user in a specific scope.
 
     Args:
         user_external_key (str): ID of the user (e.g., 'john_doe').
         role_external_key (str): Name of the role to unassign.
         scope_external_key (str): Scope in which to unassign the role.
+
+    Returns:
+        bool: True if the role was unassigned successfully, False otherwise.
     """
-    unassign_role_from_subject_in_scope(
+    return unassign_role_from_subject_in_scope(
         UserData(external_key=user_external_key),
         RoleData(external_key=role_external_key),
         ScopeData(external_key=scope_external_key),
     )
 
 
-def batch_unassign_role_from_users(
-    users: list[str], role_external_key: str, scope_external_key: str
-):
+def 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.
 
     Args:
@@ -117,9 +117,7 @@ def get_user_role_assignments(user_external_key: str) -> list[RoleAssignmentData
     return get_subject_role_assignments(UserData(external_key=user_external_key))
 
 
-def get_user_role_assignments_in_scope(
-    user_external_key: str, scope_external_key: str
-) -> list[RoleAssignmentData]:
+def 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.
 
     Args:
@@ -164,9 +162,7 @@ def get_all_user_role_assignments_in_scope(
     Returns:
         list[RoleAssignmentData]: A list of user role assignments and all their metadata in the specified scope.
     """
-    return get_all_subject_role_assignments_in_scope(
-        ScopeData(external_key=scope_external_key)
-    )
+    return get_all_subject_role_assignments_in_scope(ScopeData(external_key=scope_external_key))
 
 
 def is_user_allowed(
@@ -189,3 +185,16 @@ def is_user_allowed(
         ActionData(external_key=action_external_key),
         ScopeData(external_key=scope_external_key),
     )
+
+
+def get_users_for_role(role_external_key: str) -> list[UserData]:
+    """Get all the users assigned to a specific role.
+
+    Args:
+        role_external_key (str): The role to filter users (e.g., 'library_admin').
+
+    Returns:
+        list[UserData]: A list of users assigned to the specified role.
+    """
+    users = get_subjects_for_role(RoleData(external_key=role_external_key))
+    return [UserData(namespaced_key=user.namespaced_key) for user in users]