squash!: Implement superadmins special case

Author: rodmgwgu

openedx_authz/api/data.py

@@ -37,6 +37,7 @@
     "RoleData",
     "ScopeData",
     "SubjectData",
+    "SuperAdminAssignmentData",
     "UserData",
 ]
 
@@ -1101,6 +1102,19 @@ def __repr__(self):
         return f"{self.subject.namespaced_key} => [{role_keys}] @ {self.scope.namespaced_key}"
 
 
+@define
+class SuperAdminAssignmentData:
+    """Represents a superadmin entry in a team member assignment list.
+
+    Used alongside RoleAssignmentData in serializer contexts where a user is a
+    staff/superuser and their access is not derived from a specific role assignment.
+    """
+
+    subject: SubjectData = None
+    is_staff: bool = False
+    is_superuser: bool = False
+
+
 @define
 class UserAssignments:
     """A user with their role assignments"""

openedx_authz/api/users.py

@@ -9,12 +9,15 @@
 (e.g., 'user^john_doe').
 """
 
+from django.contrib.auth import get_user_model
+
 from openedx_authz.api.data import (
     ActionData,
     PermissionData,
     RoleAssignmentData,
     RoleData,
     ScopeData,
+    SuperAdminAssignmentData,
     UserAssignments,
     UserAssignmentsFilter,
     UserData,
@@ -36,6 +39,9 @@
 )
 from openedx_authz.api.utils import filter_user_assignments, get_user_assignment_map
 
+User = get_user_model()
+
+
 __all__ = [
     "assign_role_to_user_in_scope",
     "batch_assign_role_to_users_in_scope",
@@ -52,6 +58,7 @@
     "get_scopes_for_user_and_permission",
     "get_users_for_role_in_scope",
     "unassign_all_roles_from_user",
+    "get_superadmins",
 ]
 
 
@@ -376,3 +383,30 @@ def unassign_all_roles_from_user(user_external_key: str) -> bool:
         bool: True if any roles were removed, False otherwise.
     """
     return unassign_subject_from_all_roles(UserData(external_key=user_external_key))
+
+
+def get_superadmins(user_external_keys: list[str] | None = None) -> list[SuperAdminAssignmentData]:
+    """Returns all superadmins as SuperAdminAssignmentData.
+
+    A superadmin is a User with a Django staff or superuser role.
+    Superadmins automatically are allowed to do any action.
+
+    Args:
+        user_external_keys (list[str] or None): To filter by usernames
+
+    Returns:
+        list[SuperAdminAssignmentData]: The superadmin data
+    """
+    # Retrieve user data to check if they are a superusers
+    requested_users = User.objects.filter(username__in=user_external_keys, is_active=True)
+    superadmin_assignments: list[SuperAdminAssignmentData] = []
+    for requested_user in requested_users:
+        if requested_user.is_staff or requested_user.is_superuser:
+            superadmin_assignments.append(
+                SuperAdminAssignmentData(
+                    subject=UserData(external_key=requested_user.username),
+                    is_staff=requested_user.is_staff,
+                    is_superuser=requested_user.is_superuser,
+                )
+            )
+    return superadmin_assignments

openedx_authz/rest_api/v1/serializers.py

@@ -287,24 +287,38 @@ class TeamMemberAssignmentSerializer(serializers.Serializer):  # pylint: disable
     scope = serializers.SerializerMethodField()
     permission_count = serializers.SerializerMethodField()
 
-    def get_is_superadmin(self, obj: api.RoleAssignmentData) -> bool:
-        """Geth whether this assignment entry is for a superadmin"""
-        return False # TODO
+    def get_is_superadmin(self, obj: api.RoleAssignmentData | api.SuperAdminAssignmentData) -> bool:
+        """Get whether this assignment entry is for a superadmin."""
+        return isinstance(obj, api.SuperAdminAssignmentData)
 
-    def get_role(self, obj: api.RoleAssignmentData) -> str:
+    def get_role(self, obj: api.RoleAssignmentData | api.SuperAdminAssignmentData) -> str:
         """Get the role for the given role assignment."""
-        return obj.roles[0].external_key if obj.roles else ""
+        match obj:
+            case api.SuperAdminAssignmentData():
+                return "django.superuser" if obj.is_superuser else "django.staff"
+            case api.RoleAssignmentData():
+                return obj.roles[0].external_key if obj.roles else ""
 
-    def get_org(self, obj: api.RoleAssignmentData) -> str:
+    def get_org(self, obj: api.RoleAssignmentData | api.SuperAdminAssignmentData) -> str:
         """Get the org for the given role assignment."""
-        if isinstance(obj.scope, (api.ContentLibraryData, api.OrgContentLibraryGlobData)):
-            return obj.scope.org
-        return ""
+        match obj:
+            case api.SuperAdminAssignmentData():
+                return "*"
+            case api.RoleAssignmentData():
+                return getattr(obj.scope, "org", None)
 
-    def get_scope(self, obj: api.RoleAssignmentData) -> str:
+    def get_scope(self, obj: api.RoleAssignmentData | api.SuperAdminAssignmentData) -> str:
         """Get the scope for the given role assignment."""
-        return obj.scope.external_key
+        match obj:
+            case api.SuperAdminAssignmentData():
+                return "*"
+            case api.RoleAssignmentData():
+                return obj.scope.external_key
 
-    def get_permission_count(self, obj: api.RoleAssignmentData) -> int:
+    def get_permission_count(self, obj: api.RoleAssignmentData | api.SuperAdminAssignmentData) -> int | None:
         """Get the permission count for the given role assignment."""
-        return len(obj.roles[0].permissions) if obj.roles else 0
+        match obj:
+            case api.SuperAdminAssignmentData():
+                return None
+            case api.RoleAssignmentData():
+                return len(obj.roles[0].permissions) if obj.roles else 0

openedx_authz/rest_api/v1/views.py

@@ -20,7 +20,8 @@
 from rest_framework.views import APIView
 
 from openedx_authz import api
-from openedx_authz.api.users import get_user_role_assignments_for_user_filtered
+from openedx_authz.api.data import RoleAssignmentData, SuperAdminAssignmentData
+from openedx_authz.api.users import get_superadmins, get_user_role_assignments_for_user_filtered
 from openedx_authz.api.utils import get_user_map
 from openedx_authz.constants import permissions
 from openedx_authz.rest_api.data import RoleOperationError, RoleOperationStatus
@@ -629,15 +630,18 @@ def get(self, request: HttpRequest, username: str) -> Response:
         serializer.is_valid(raise_exception=True)
         query_params = serializer.validated_data
 
-        user_role_assignments = get_user_role_assignments_for_user_filtered(
+        user_role_assignments: list[RoleAssignmentData | SuperAdminAssignmentData] = []
+
+        # Retrieve superadmin assignments (django staff or superuser users), as they always have access to everything
+        user_role_assignments += get_superadmins(user_external_keys=[username])
+
+        user_role_assignments += get_user_role_assignments_for_user_filtered(
             user_external_key=username,
             orgs=query_params.get("orgs"),
             roles=query_params.get("roles"),
             allowed_for_user_external_key=request.user.username,
         )
 
-        # TODO if calling user has permission to see superadmins, get them here and prepand to user_role_assignments
-
         assignments = TeamMemberAssignmentSerializer(user_role_assignments, many=True).data
         for backend in self.filter_backends:
             assignments = backend().filter_queryset(request, assignments, self)

openedx_authz/tests/rest_api/test_views.py

@@ -1318,7 +1318,14 @@ class TestTeamMemberAssignmentsAPIView(ViewTestMixin):
                         regular_7 (library_contributor), regular_8 (library_user)
 
     URL: /authz/v1/users/<username>/assignments
-    Response fields per item: role, org, scope, permission_count
+    Response fields per item: is_superadmin, role, org, scope, permission_count
+
+    Superadmin entry:
+        admin_1..3 are staff/superusers. Querying any of them always prepends one
+        SuperAdminAssignmentData entry: role="django.superuser" (or "django.staff"),
+        org="*", scope="*", permission_count=None, is_superadmin=True.
+        This entry is always included regardless of org/role filters, since those
+        filters are applied only to the role assignments, not to the superadmin entry.
 
     Visibility via filter_allowed_assignments:
         - Staff/superuser: sees all assignments for any user
@@ -1344,26 +1351,30 @@ def _url(self, username: str) -> str:
     # -------------------------------------------------------------------- #
 
     @data(
-        # Staff/superuser sees all assignments for any user
-        ("admin_1", "admin_1", 1),
-        ("admin_1", "admin_2", 1),
-        ("admin_1", "admin_3", 1),
+        # Staff/superuser targets get 1 superadmin entry + their role assignment(s)
+        ("admin_1", "admin_1", 2),  # superadmin entry + library_admin in Org1
+        ("admin_1", "admin_2", 2),  # superadmin entry + library_user in Org2
+        ("admin_1", "admin_3", 2),  # superadmin entry + library_admin in Org3
+        # Regular user targets get only their role assignments (no superadmin entry)
         ("admin_1", "regular_5", 1),
-        # regular_1 has VIEW_LIBRARY on Org1:LIB1 only → sees admin_1's Org1 assignment
-        ("regular_1", "admin_1", 1),
-        # regular_1 cannot see admin_2's Org2 assignment
-        ("regular_1", "admin_2", 0),
-        # regular_9 has no assignments → sees nothing for any user
-        ("regular_9", "admin_1", 0),
+        # The superadmin entry is always included for superadmin targets, visible to all callers
+        ("regular_1", "admin_1", 2),  # superadmin entry + library_admin in Org1 (visible via Org1 access)
+        # regular_1 cannot see admin_2's Org2 role assignment, but superadmin entry is still included
+        ("regular_1", "admin_2", 1),  # superadmin entry only
+        # regular_9 has no assignments but superadmin entry is still included for admin targets
+        ("regular_9", "admin_1", 1),  # superadmin entry only
     )
     @unpack
     def test_visibility_limited_to_accessible_scopes(self, caller: str, target: str, expected_count: int):
-        """Calling user only sees assignments for scopes it has view access to.
+        """Calling user only sees role assignments for scopes it has view access to.
+
+        The superadmin entry is always included when the target is a superadmin,
+        regardless of the calling user's permissions.
 
         Expected result:
-            - Staff/superuser sees all assignments for any user.
-            - Regular users only see assignments in scopes they can view.
-            - Users with no assignments see no results for any user.
+            - Superadmin targets always include the superadmin entry.
+            - Role assignments are filtered by the calling user's permissions.
+            - Regular user targets return only their visible role assignments.
         """
         self.client.force_authenticate(user=User.objects.get(username=caller))
 
@@ -1400,14 +1411,14 @@ def test_unknown_user_returns_empty(self):
     # ------------------------------------------------------------------ #
 
     @data(
-        # admin_3 has library_admin in lib:Org3:LIB3
-        ("admin_3", "Org3", 1),
-        ("admin_3", "Org1", 0),
-        # regular_5 has library_admin in lib:Org3:LIB3
+        # admin_3 has library_admin in lib:Org3:LIB3; superadmin entry is always included
+        ("admin_3", "Org3", 2),  # superadmin entry + Org3 role assignment
+        ("admin_3", "Org1", 1),  # superadmin entry only (no Org1 role assignment)
+        # regular_5 has library_admin in lib:Org3:LIB3 (no superadmin entry)
         ("regular_5", "Org3", 1),
         ("regular_5", "Org1", 0),
-        # non-existent org returns no results
-        ("admin_1", "OrgX", 0),
+        # non-existent org: superadmin entry still included for admin targets
+        ("admin_1", "OrgX", 1),  # superadmin entry only
     )
     @unpack
     def test_filter_by_orgs(self, target: str, orgs: str, expected_count: int):
@@ -1442,13 +1453,14 @@ def test_filter_by_multiple_orgs(self):
     # ------------------------------------------------------------------ #
 
     @data(
-        ("admin_1", roles.LIBRARY_ADMIN.external_key, 1),
-        ("admin_1", roles.LIBRARY_USER.external_key, 0),
+        # role filter applies only to role assignments; superadmin entry is always included for admin targets
+        ("admin_1", roles.LIBRARY_ADMIN.external_key, 2),  # superadmin entry + library_admin
+        ("admin_1", roles.LIBRARY_USER.external_key, 1),  # superadmin entry only
         ("regular_5", roles.LIBRARY_ADMIN.external_key, 1),
         ("regular_5", roles.LIBRARY_USER.external_key, 0),
         ("regular_6", roles.LIBRARY_AUTHOR.external_key, 1),
         ("regular_6", roles.LIBRARY_ADMIN.external_key, 0),
-        ("admin_1", "non_existent_role", 0),
+        ("admin_1", "non_existent_role", 1),  # superadmin entry only
     )
     @unpack
     def test_filter_by_roles(self, target: str, role_filter: str, expected_count: int):
@@ -1463,20 +1475,20 @@ def test_filter_by_roles(self, target: str, role_filter: str, expected_count: in
         self.assertEqual(response.data["count"], expected_count)
 
     def test_filter_by_multiple_roles(self):
-        """Multiple roles are OR-combined.
+        """Multiple roles are OR-combined for role assignments; superadmin entry always included.
 
         Expected result:
-            - Returns assignments matching any of the given roles.
+            - Returns assignments matching any of the given roles, plus the superadmin entry.
         """
-        # regular_6 has library_author, regular_7 has library_contributor — use admin_3
-        # who has library_admin in Org3:LIB3; filter for admin + author returns 1
+        # admin_3 has library_admin in Org3:LIB3; filter for admin + author returns
+        # 1 role assignment + 1 superadmin entry = 2
         response = self.client.get(
             self._url("admin_3"),
             {"roles": f"{roles.LIBRARY_ADMIN.external_key},{roles.LIBRARY_AUTHOR.external_key}"},
         )
 
         self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data["count"], 1)
+        self.assertEqual(response.data["count"], 2)
 
     # ------------------------------------------------------------------ #
     # Sorting                                                            #
@@ -1566,24 +1578,35 @@ def test_pagination(self, query_params: dict, expected_page_count: int, has_next
     def test_response_shape(self):
         """Each result item contains the expected fields.
 
+        admin_1 is a superuser, so the response contains two items:
+        - A superadmin entry with role="django.superuser", org="*", scope="*",
+          permission_count=None, is_superadmin=True
+        - A regular role assignment entry with concrete values and is_superadmin=False
+
         Expected result:
             - Returns 200 OK.
-            - Each item has role, org, scope, and permission_count.
-            - Values match the known assignment for admin_1.
+            - Each item has is_superadmin, role, org, scope, and permission_count.
         """
         response = self.client.get(self._url("admin_1"))
 
         self.assertEqual(response.status_code, status.HTTP_200_OK)
-        self.assertEqual(response.data["count"], 1)
-        item = response.data["results"][0]
-        self.assertIn("role", item)
-        self.assertIn("org", item)
-        self.assertIn("scope", item)
-        self.assertIn("permission_count", item)
-        self.assertEqual(item["role"], roles.LIBRARY_ADMIN.external_key)
-        self.assertEqual(item["org"], "Org1")
-        self.assertEqual(item["scope"], "lib:Org1:LIB1")
-        self.assertGreater(item["permission_count"], 0)
+        self.assertEqual(response.data["count"], 2)
+
+        superadmin_item = next(item for item in response.data["results"] if item["is_superadmin"])
+        self.assertIn(superadmin_item["role"], ("django.superuser", "django.staff"))
+        self.assertEqual(superadmin_item["org"], "*")
+        self.assertEqual(superadmin_item["scope"], "*")
+        self.assertIsNone(superadmin_item["permission_count"])
+
+        role_item = next(item for item in response.data["results"] if not item["is_superadmin"])
+        self.assertIn("role", role_item)
+        self.assertIn("org", role_item)
+        self.assertIn("scope", role_item)
+        self.assertIn("permission_count", role_item)
+        self.assertEqual(role_item["role"], roles.LIBRARY_ADMIN.external_key)
+        self.assertEqual(role_item["org"], "Org1")
+        self.assertEqual(role_item["scope"], "lib:Org1:LIB1")
+        self.assertGreater(role_item["permission_count"], 0)
 
 
 @ddt