feat: add flexible filtering for user role assignments

Author: BryanttV

openedx_authz/api/roles.py

@@ -26,22 +26,22 @@
 from openedx_authz.models import ExtendedCasbinRule
 
 __all__ = [
-    "get_permissions_for_single_role",
-    "get_permissions_for_roles",
-    "get_all_roles_names",
-    "get_all_roles_in_scope",
-    "get_permissions_for_active_roles_in_scope",
-    "get_role_definitions_in_scope",
     "assign_role_to_subject_in_scope",
     "batch_assign_role_to_subjects_in_scope",
-    "unassign_role_from_subject_in_scope",
     "batch_unassign_role_from_subjects_in_scope",
-    "get_subject_role_assignments_in_scope",
-    "get_subject_role_assignments_for_role",
-    "get_subject_role_assignments_for_role_in_scope",
+    "get_all_roles_in_scope",
+    "get_all_roles_names",
     "get_all_subject_role_assignments_in_scope",
-    "get_subject_role_assignments",
+    "get_permissions_for_active_roles_in_scope",
+    "get_permissions_for_roles",
+    "get_permissions_for_single_role",
+    "get_role_assignments",
+    "get_role_definitions_in_scope",
     "get_scopes_for_subject_and_permission",
+    "get_subject_role_assignments",
+    "get_subject_role_assignments_for_role_in_scope",
+    "get_subject_role_assignments_in_scope",
+    "unassign_role_from_subject_in_scope",
     "unassign_subject_from_all_roles",
 ]
 
@@ -294,6 +294,92 @@ def get_subject_role_assignments(subject: SubjectData) -> list[RoleAssignmentDat
     return role_assignments
 
 
+def get_field_index_and_values(
+    subject: SubjectData | None,
+    role: RoleData | None,
+    scope: ScopeData | None,
+) -> tuple[int, list[str]]:
+    """Build field index and values for Casbin's get_filtered_grouping_policy.
+
+    Returns the leftmost non-None field as field_index and a list of consecutive
+    values starting from that index. Empty strings serve as wildcards for positions
+    between specified values.
+
+    Examples:
+        >>> get_field_index_and_values(user, None, None)
+        (0, ['user^steve'])
+        >>> get_field_index_and_values(user, role, None)
+        (0, ['user^steve', 'role^course_admin'])
+        >>> get_field_index_and_values(None, role, scope)
+        (1, ['role^course_admin', 'course-v1^course-v1:OpenedX+Demo+Course'])
+        >>> get_field_index_and_values(user, None, scope)
+        (0, ['user^steve', '', 'course-v1^course-v1:OpenedX+Demo+Course'])
+
+    Args:
+        subject: Optional subject to filter by.
+        role: Optional role to filter by.
+        scope: Optional scope to filter by.
+
+    Returns:
+        tuple: (field_index, field_values) where field_index is the starting position
+            and field_values are the consecutive filter values from that position.
+    """
+    values = [
+        subject.namespaced_key if subject else "",
+        role.namespaced_key if role else "",
+        scope.namespaced_key if scope else "",
+    ]
+
+    # Find first non-empty value (leftmost defined field)
+    try:
+        field_index = next(idx for idx, value in enumerate(values) if value)
+    except StopIteration:
+        return 0, []
+
+    # Take slice from first defined field
+    field_values = values[field_index:]
+
+    # Remove trailing wildcards
+    while field_values and field_values[-1] == "":
+        field_values.pop()
+
+    return field_index, field_values
+
+
+def get_role_assignments(
+    *,
+    subject: SubjectData | None = None,
+    role: RoleData | None = None,
+    scope: ScopeData | None = None,
+) -> list[RoleAssignmentData]:
+    """Get all the roles for a subject across all scopes filtered by the given filters.
+
+    Args:
+        subject: Optional SubjectData object to filter by.
+        role: Optional RoleData object to filter by.
+        scope: Optional ScopeData object to filter by.
+
+    Returns:
+        list[RoleAssignmentData]: A list of RoleAssignmentData objects filtered by the given filters.
+    """
+    enforcer = AuthzEnforcer.get_enforcer()
+    role_assignments = []
+    field_index, field_values = get_field_index_and_values(subject, role, scope)
+    policies = enforcer.get_filtered_grouping_policy(field_index, *field_values)
+
+    for policy in policies:
+        role = RoleData(namespaced_key=policy[GroupingPolicyIndex.ROLE.value])
+        role.permissions = get_permissions_for_single_role(role)
+        role_assignments.append(
+            RoleAssignmentData(
+                subject=SubjectData(namespaced_key=policy[GroupingPolicyIndex.SUBJECT.value]),
+                roles=[role],
+                scope=ScopeData(namespaced_key=policy[GroupingPolicyIndex.SCOPE.value]),
+            )
+        )
+    return role_assignments
+
+
 def get_subject_role_assignments_in_scope(subject: SubjectData, scope: ScopeData) -> list[RoleAssignmentData]:
     """Get the roles for a subject in a specific scope.
 

openedx_authz/api/users.py

@@ -23,6 +23,7 @@
     batch_assign_role_to_subjects_in_scope,
     batch_unassign_role_from_subjects_in_scope,
     get_all_subject_role_assignments_in_scope,
+    get_role_assignments,
     get_scopes_for_subject_and_permission,
     get_subject_role_assignments,
     get_subject_role_assignments_for_role,
@@ -41,6 +42,7 @@
     "get_user_role_assignments",
     "get_user_role_assignments_in_scope",
     "get_user_role_assignments_for_role_in_scope",
+    "get_user_role_assignments_filtered",
     "get_all_user_role_assignments_in_scope",
     "is_user_allowed",
     "get_scopes_for_user_and_permission",
@@ -180,6 +182,33 @@ def get_user_role_assignments_for_role_in_scope(
     )
 
 
+def get_user_role_assignments_filtered(
+    *,
+    user_external_key: str | None = None,
+    role_external_key: str | None = None,
+    scope_external_key: str | None = None,
+) -> list[RoleAssignmentData]:
+    """Get role assignments filtered by user, role, and/or scope.
+
+    This function provides flexible filtering of role assignments by any combination
+    of user, role, and scope. At least one filter parameter should be provided for
+    meaningful results.
+
+    Args:
+        user_external_key: Optional user ID to filter by (e.g., 'john_doe').
+        role_external_key: Optional role name to filter by (e.g., 'library_admin').
+        scope_external_key: Optional scope to filter by (e.g., 'lib:DemoX:CSPROB').
+
+    Returns:
+        list[RoleAssignmentData]: Filtered role assignments.
+    """
+    return get_role_assignments(
+        subject=UserData(external_key=user_external_key) if user_external_key else None,
+        role=RoleData(external_key=role_external_key) if role_external_key else None,
+        scope=ScopeData(external_key=scope_external_key) if scope_external_key else None,
+    )
+
+
 def get_all_user_role_assignments_in_scope(
     scope_external_key: str,
 ) -> list[RoleAssignmentData]: