feat: Add support for global wildcard scope assignation

Author: rodmgwgu

openedx_authz/api/data.py

@@ -32,6 +32,7 @@
     "AuthzBaseClass",
     "ContentLibraryData",
     "CourseOverviewData",
+    "GlobalWildcardScopeData",
     "GroupingPolicyIndex",
     "OrgCourseOverviewGlobData",
     "OrgGlobData",
@@ -154,11 +155,11 @@ def __call__(cls, *args, **kwargs):
 
         # When working with global scopes, we can't determine subclass with an external_key since
         # a global scope it's not attached to a specific resource type. So we only use * as
-        # an external_key to mean generic scope which maps to base ScopeData class.
+        # an external_key to mean the global wildcard scope which maps to GlobalWildcardScopeData.
         # The only remaining issue is that internally the namespace key used in policies will be
         # The global scope namespace (global^*), so we need to handle that case here.
         if kwargs.get("external_key") == GLOBAL_SCOPE_WILDCARD:
-            return super().__call__(*args, **kwargs)
+            return super(ScopeMeta, GlobalWildcardScopeData).__call__(*args, **kwargs)
 
         if "namespaced_key" in kwargs:
             scope_cls = cls.get_subclass_by_namespaced_key(kwargs["namespaced_key"])
@@ -249,6 +250,11 @@ def get_subclass_by_external_key(mcs, external_key: str) -> Type["ScopeData"]:
             - This won't work for org scopes that don't have explicit namespace prefixes.
               TODO: Handle org scopes differently.
         """
+
+        # Special case: handle the global wildcard scope:
+        if external_key == "*":
+            return mcs.glob_registry.get("global")
+
         if EXTERNAL_KEY_SEPARATOR not in external_key:
             raise ValueError(f"Invalid external_key format: {external_key}")
 
@@ -288,7 +294,7 @@ def get_all_namespaces(mcs) -> dict[str, Type["ScopeData"]]:
 
         Examples:
             >>> ScopeMeta.get_all_namespaces()
-            {'global': ScopeData, 'lib': ContentLibraryData, 'org': OrganizationData}
+            {'global': GlobalWildcardScopeData, 'lib': ContentLibraryData, 'org': OrganizationData}
         """
         return mcs.scope_registry
 
@@ -326,8 +332,7 @@ class ScopeData(AuthZData, metaclass=ScopeMeta):
 
     # The 'global' namespace is used for scopes that aren't tied to a specific resource type.
     # This base class supports:
-    # 1. Global wildcard scopes (external_key='*') that apply across all resource types
-    # 2. Custom global scopes that don't map to specific domain objects (e.g., 'global:some_scope')
+    # - Custom scopes that don't map to specific domain objects (e.g., 'global:some_scope')
     # Subclasses like ContentLibraryData ('lib') represent concrete resource types with their own namespaces.
     NAMESPACE: ClassVar[str] = "global"
     IS_GLOB: ClassVar[bool] = False
@@ -400,6 +405,93 @@ def exists(self) -> bool:
         raise NotImplementedError("Subclasses must implement exists method.")
 
 
+@define
+class GlobalWildcardScopeData(ScopeData):
+    """The global wildcard scope representing access across all scopes.
+
+    This scope is used when a role assignment should apply globally (i.e., not
+    tied to any specific resource). It corresponds to the ``global^*`` namespaced
+    key in Casbin policies.
+
+    The global wildcard scope always exists and does not map to a concrete domain
+    object. It is automatically instantiated by the ``ScopeMeta`` metaclass when
+    ``ScopeData(external_key='*')`` is called.
+
+    Attributes:
+        NAMESPACE (str): 'global'.
+        external_key (str): Always ``'*'``.
+        namespaced_key (str): Always ``'global^*'``.
+
+    Examples:
+        >>> scope = ScopeData(external_key='*')
+        >>> isinstance(scope, GlobalWildcardScopeData)
+        True
+        >>> scope.exists()
+        True
+        >>> scope.namespaced_key
+        'global^*'
+    """
+
+    # The 'global' namespace is used for scopes that aren't tied to a specific resource type.
+    # This class supports Global wildcard scopes (external_key='*') that apply across all resource types
+    NAMESPACE: ClassVar[str] = "global"
+    IS_GLOB: ClassVar[bool] = True
+
+    @classmethod
+    def validate_external_key(cls, external_key: str) -> bool:
+        """Validate the external_key format for GlobalWildcardScopeData.
+
+        Only the wildcard ``'*'`` is accepted.
+
+        Args:
+            external_key: The external key to validate.
+
+        Returns:
+            bool: True if the key is ``'*'``, False otherwise.
+        """
+        return external_key == GLOBAL_SCOPE_WILDCARD
+
+    @classmethod
+    def get_admin_view_permission(cls) -> PermissionData:
+        """No admin view permission for the global scope.
+
+        Global scope assignments are managed exclusively by superadmins
+        at the REST API layer, so no granular permission is needed.
+
+        Returns:
+            None
+        """
+        return VIEW_LIBRARY_TEAM
+
+    @classmethod
+    def get_admin_manage_permission(cls) -> PermissionData:
+        """No admin manage permission for the global scope.
+
+        Global scope assignments are managed exclusively by superadmins
+        at the REST API layer, so no granular permission is needed.
+
+        Returns:
+            None
+        """
+        return None
+
+    def get_object(self) -> None:
+        """The global wildcard scope does not map to a concrete domain object.
+
+        Returns:
+            None: Always returns None.
+        """
+        return None
+
+    def exists(self) -> bool:
+        """The global wildcard scope always exists.
+
+        Returns:
+            bool: Always True.
+        """
+        return True
+
+
 @define
 class ContentLibraryData(ScopeData):
     """A content library scope for authorization in the Open edX platform.
@@ -690,6 +782,9 @@ class OrgGlobData(ScopeData):
         - ``course-v1:DemoX+*`` (all courses in org ``DemoX``)
     """
 
+    # This NAMESPACE should be overriden by specific scope subclasses,
+    # Setting this here so it doesn't conflict with GlobalWildcardScopeData's 'global' namespace
+    NAMESPACE: ClassVar[str] = "orgglob"
     IS_GLOB: ClassVar[bool] = True
     ID_SEPARATOR: ClassVar[str]
     ORG_NAME_VALID_PATTERN: ClassVar[re.Pattern] = r"^[a-zA-Z0-9._-]*$"

openedx_authz/engine/matcher.py

@@ -6,6 +6,7 @@
 from openedx_authz.api.data import (
     ContentLibraryData,
     CourseOverviewData,
+    GlobalWildcardScopeData,
     OrgContentLibraryGlobData,
     OrgCourseOverviewGlobData,
     ScopeData,
@@ -21,6 +22,7 @@
     (CourseOverviewData.NAMESPACE, CourseOverviewData),
     (OrgContentLibraryGlobData.NAMESPACE, OrgContentLibraryGlobData),
     (OrgCourseOverviewGlobData.NAMESPACE, OrgCourseOverviewGlobData),
+    (GlobalWildcardScopeData.NAMESPACE, GlobalWildcardScopeData),
 }
 
 

openedx_authz/rest_api/v1/permissions.py

@@ -282,6 +282,28 @@ def has_permission(self, request, view) -> bool:
         return any(api.get_scopes_for_user_and_permission(request.user.username, permission) for permission in required)
 
 
+class GlobalScopePermission(BaseScopePermission):
+    """Permission handler for the global wildcard scope.
+
+    Only superadmins (``is_superuser`` or ``is_staff``) are allowed to assign roles to the
+    global scope (``*``). Staff members without superuser status are denied.
+
+    This class is automatically selected by ``DynamicScopePermission`` when
+    the request scope resolves to the ``global`` namespace.
+    """
+
+    NAMESPACE: ClassVar[str] = "global"
+    """``global`` for global wildcard scopes."""
+
+    def has_permission(self, request, view) -> bool:
+        """Allow only superusers to operate on the global scope.
+
+        Returns:
+            bool: True if the user is a superadmin, False otherwise.
+        """
+        return request.user.is_superuser or request.user.is_staff
+
+
 class ContentLibraryPermission(MethodPermissionMixin, BaseScopePermission):
     """Permission handler for content library scopes.
 

openedx_authz/rest_api/v1/serializers.py

@@ -6,7 +6,7 @@
 from rest_framework import serializers
 
 from openedx_authz import api
-from openedx_authz.api.data import UserAssignments
+from openedx_authz.api.data import GLOBAL_SCOPE_WILDCARD, UserAssignments
 from openedx_authz.rest_api.data import (
     AssignmentSortField,
     ScopesTypeField,
@@ -95,6 +95,10 @@ def _validate_scope_and_role(self, scope_value: str, role_value: str) -> None:
         if not scope.exists():
             raise serializers.ValidationError({"scope": f"Scope '{scope_value}' does not exist"})
 
+        # Special case for global wildcard
+        if scope_value == GLOBAL_SCOPE_WILDCARD:
+            return
+
         role = api.RoleData(external_key=role_value)
         generic_scope = get_generic_scope(scope)
         role_definitions = api.get_role_definitions_in_scope(generic_scope)
@@ -160,15 +164,11 @@ def validate(self, attrs) -> dict:
         role_value = validated_data["role"]
 
         if scope and scopes is not None:
-            raise serializers.ValidationError(
-                "Provide either 'scope' or 'scopes', not both."
-            )
+            raise serializers.ValidationError("Provide either 'scope' or 'scopes', not both.")
 
         scopes_list = scopes if scopes is not None else ([scope] if scope else None)
         if not scopes_list:
-            raise serializers.ValidationError(
-                "Either 'scope' or 'scopes' must be provided."
-            )
+            raise serializers.ValidationError("Either 'scope' or 'scopes' must be provided.")
 
         for scope_value in scopes_list:
             self._validate_scope_and_role(scope_value, role_value)
@@ -401,6 +401,9 @@ def get_org(self, obj: api.RoleAssignmentData | api.SuperAdminAssignmentData) ->
             case api.SuperAdminAssignmentData():
                 return "*"
             case api.RoleAssignmentData():
+                if obj.scope.external_key == GLOBAL_SCOPE_WILDCARD:
+                    # Special case for global wildcard scope
+                    return "*"
                 return getattr(obj.scope, "org", "")
 
     def get_scope(self, obj: api.RoleAssignmentData | api.SuperAdminAssignmentData) -> str:

openedx_authz/tests/api/test_data.py

@@ -11,6 +11,7 @@
     CCXCourseOverviewData,
     ContentLibraryData,
     CourseOverviewData,
+    GlobalWildcardScopeData,
     OrgContentLibraryGlobData,
     OrgCourseOverviewGlobData,
     PermissionData,
@@ -249,7 +250,8 @@ def test_scope_data_registration(self):
         """Test that ScopeData and its subclasses are registered correctly.
 
         Expected Result:
-            - 'global' namespace maps to ScopeData class
+            - 'global' namespace maps to ScopeData class in scope_registry
+            - 'global' namespace maps to GlobalWildcardScopeData in glob_registry
             - 'lib' namespace maps to ContentLibraryData class
         """
         self.assertIn("global", ScopeData.scope_registry)
@@ -261,7 +263,9 @@ def test_scope_data_registration(self):
         self.assertIn("ccx-v1", ScopeData.scope_registry)
         self.assertIs(ScopeData.scope_registry["ccx-v1"], CCXCourseOverviewData)
 
-        # Glob registries for organization-level scopes
+        # Glob registries for organization-level scopes and global wildcard
+        self.assertIn("global", ScopeMeta.glob_registry)
+        self.assertIs(ScopeMeta.glob_registry["global"], GlobalWildcardScopeData)
         self.assertIn("lib", ScopeMeta.glob_registry)
         self.assertIs(ScopeMeta.glob_registry["lib"], OrgContentLibraryGlobData)
         self.assertIn("course-v1", ScopeMeta.glob_registry)
@@ -320,6 +324,7 @@ def test_get_subclass_by_namespaced_key(self, namespaced_key, expected_class):
         ("course-v1:OpenedX+*", OrgCourseOverviewGlobData),
         ("lib:edX:Demo", ContentLibraryData),
         ("global:generic_scope", ScopeData),
+        ("*", GlobalWildcardScopeData),
     )
     @unpack
     def test_get_subclass_by_external_key(self, external_key, expected_class):
@@ -361,11 +366,11 @@ def test_scope_validate_external_key(self, external_key, expected_valid, expecte
         self.assertEqual(result, expected_valid)
 
     @data(
-        "unknown:DemoX",
-        "unknown:DemoX:*",
+        "undefined:DemoX",
+        "undefined:DemoX:*",
     )
-    def test_get_subclass_by_external_key_unknown_scope_raises_value_error(self, external_key):
-        """Unknown namespace should raise ValueError, including wildcard keys."""
+    def test_get_subclass_by_external_key_undefined_scope_raises_value_error(self, external_key):
+        """Undefined namespace should raise ValueError, including wildcard keys."""
         with self.assertRaises(ValueError):
             ScopeMeta.get_subclass_by_external_key(external_key)
 
@@ -464,25 +469,28 @@ def test_empty_external_key_raises_value_error(self):
             SubjectData(external_key="")
 
     def test_scope_data_with_wildcard_external_key(self):
-        """Test that ScopeData instantiated with wildcard (*) returns base ScopeData.
+        """Test that ScopeData instantiated with wildcard (*) returns GlobalWildcardScopeData.
 
-        When using the global scope wildcard '*', the metaclass should return a base
-        ScopeData instance rather than attempting subclass determination.
+        When using the global scope wildcard '*', the metaclass should return a
+        GlobalWildcardScopeData instance rather than attempting subclass determination
+        from the external_key format.
 
         Expected Result:
-            - ScopeData(external_key='*') creates base ScopeData instance
+            - ScopeData(external_key='*') creates GlobalWildcardScopeData instance
             - namespaced_key is 'global^*'
-            - No subclass determination occurs
+            - exists() returns True
+            - get_object() returns None
         """
         scope = ScopeData(external_key="*")
 
-        expected_namespaced = f"{ScopeData.NAMESPACE}{ScopeData.SEPARATOR}*"
+        expected_namespaced = f"{GlobalWildcardScopeData.NAMESPACE}{GlobalWildcardScopeData.SEPARATOR}*"
 
         self.assertIsInstance(scope, ScopeData)
-        # Ensure it's exactly ScopeData, not a subclass
-        self.assertEqual(type(scope), ScopeData)
+        self.assertIsInstance(scope, GlobalWildcardScopeData)
         self.assertEqual(scope.external_key, "*")
         self.assertEqual(scope.namespaced_key, expected_namespaced)
+        self.assertTrue(scope.exists())
+        self.assertIsNone(scope.get_object())
 
 
 @ddt

openedx_authz/tests/api/test_roles.py

@@ -922,7 +922,7 @@ class TestRoleAssignmentAPI(RolesTestSetupMixin):
     """
 
     @ddt_data(
-        (["mary", "john"], roles.LIBRARY_USER.external_key, "global:batch_test", True),
+        (["mary", "john"], roles.LIBRARY_USER.external_key, "*", True),
         (
             ["paul", "diana", "lila"],
             roles.LIBRARY_CONTRIBUTOR.external_key,