feat: enhance ScopeMeta to support glob patterns

BryanttV · BryanttV · commit c8e02fa4a0e2 · 2026-03-13T18:21:59.000-05:00
diff --git a/openedx_authz/api/data.py b/openedx_authz/api/data.py
diff --git a/openedx_authz/api/roles.py b/openedx_authz/api/roles.py
@@ -199,6 +199,9 @@ def assign_role_to_subject_in_scope(subject: SubjectData, role: RoleData, scope:
 
     Returns:
         bool: True if the role was assigned successfully, False otherwise.
+
+    Raises:
+        ValueError: If the scope string contains invalid glob patterns.
     """
     enforcer = AuthzEnforcer.get_enforcer()
     adapter = AuthzEnforcer.get_adapter()
diff --git a/openedx_authz/api/validation.py b/openedx_authz/api/validation.py
@@ -0,0 +1,149 @@
+"""Validation utilities for OpenedX AuthZ API.
+
+This module provides validation functions for scope strings, particularly
+for glob patterns used in role assignments.
+"""
+
+from openedx_authz.api.data import (
+    EXTERNAL_KEY_SEPARATOR,
+    GLOBAL_SCOPE_WILDCARD,
+    ContentLibraryData,
+    CourseOverviewData,
+    ScopeData,
+)
+
+
+def validate_scope_with_glob(scope: ScopeData) -> None:
+    """Validate that a scope with glob patterns follows rules.
+
+    This function ensures that glob patterns (*) in scope strings are only
+    allowed at the organization level and that the referenced organization
+    exists to prevent overly broad or invalid permissions.
+
+    Rules:
+    - For course scopes: Must have exactly the format "course-v1:ORG*" where ORG exists
+    - For library scopes: Must have exactly the format "lib:ORG*" where ORG exists
+    - Wildcards must only appear at the end of the string
+    - Wildcards are only allowed at organization level (not at course, run, or slug level)
+    - Cannot have wildcards before the org identifier
+
+    Args:
+        scope (ScopeData): ScopeData instance to validate (e.g. ScopeData(external_key="course-v1:OpenedX*"))
+
+    Examples:
+        Valid scopes:
+        - CourseOverviewData(external_key="course-v1:OpenedX*")  # org-level wildcard
+        - ContentLibraryData(external_key="lib:DemoX*")  # org-level wildcard
+
+        Invalid scopes:
+        - course-v1* - wildcard before org
+        - course-v1:* - wildcard without org prefix
+        - course-v1:OpenedX+Course* - wildcard at course level (NOT allowed)
+        - lib:DemoX:Slug* - wildcard at slug level (NOT allowed)
+    """
+    external_key = scope.external_key
+
+    if GLOBAL_SCOPE_WILDCARD not in external_key:
+        return None
+
+    # Get the scope string without the trailing wildcard
+    scope_prefix = external_key[: -len(GLOBAL_SCOPE_WILDCARD)]
+
+    if isinstance(scope, CourseOverviewData):
+        return _validate_course_scope_glob(scope_prefix)
+    if isinstance(scope, ContentLibraryData):
+        return _validate_library_scope_glob(scope_prefix)
+
+    raise ValueError(f"Invalid scope: {scope}")
+
+
+def _validate_org_identifier(scope_prefix: str) -> str:
+    """Extract and structurally validate the organization identifier in a scope.
+
+    This helper only validates the structure (namespace and org position). It does
+    not check whether the organization actually exists. That is the responsibility
+    of the scope-type specific validators.
+
+    Args:
+        scope_prefix (str): The scope without the trailing wildcard
+
+    Returns:
+        str: The extracted organization identifier
+
+    Examples:
+        >>> _validate_org_identifier("course-v1:OpenedX*")
+        "OpenedX"
+        >>> _validate_org_identifier("lib:DemoX*")
+        "DemoX"
+    """
+    parts = scope_prefix.split(EXTERNAL_KEY_SEPARATOR)
+
+    if len(parts) != 2 or parts[1] == "":
+        raise ValueError("Scope glob must include exactly one organization identifier.")
+
+    return parts[1]
+
+
+def _course_org_exists(org: str) -> bool:
+    """Check if there is at least one course with the given org.
+
+    Args:
+        org (str): Organization identifier extracted from the course scope
+
+    Returns:
+        bool: True if there is at least one CourseOverview whose org field matches
+        the provided identifier in a case-sensitive way, False otherwise.
+    """
+    from openedx_authz.models.scopes import CourseOverview  # pylint: disable=import-outside-toplevel
+
+    course_obj = CourseOverview.objects.filter(org=org).only("org").last()
+    return course_obj is not None and course_obj.org == org
+
+
+def _library_org_exists(org: str) -> bool:
+    """Check if there is at least one content library with the given org.
+
+    Args:
+        org (str): Organization identifier extracted from the library scope
+
+    Returns:
+        bool: True if there is at least one ContentLibrary whose related
+        organization's short_name matches the provided identifier in a
+        case-sensitive way, False otherwise.
+    """
+    from openedx_authz.models.scopes import ContentLibrary  # pylint: disable=import-outside-toplevel
+
+    lib_obj = ContentLibrary.objects.filter(org__short_name=org).only("org").last()
+    return lib_obj is not None and lib_obj.org.short_name == org
+
+
+def _validate_course_scope_glob(scope_prefix: str) -> None:
+    """Validate a course scope with glob pattern.
+
+    Course keys have format: course-v1:ORG+COURSE+RUN
+    We only allow wildcards at the organization level (course-v1:ORG*).
+    Wildcards at course or run level are not allowed.
+
+    Args:
+        scope_prefix (str): The course scope without the trailing wildcard
+    """
+    org = _validate_org_identifier(scope_prefix)
+
+    if not _course_org_exists(org):
+        raise ValueError(f"Organization '{org}' does not exist for any course.")
+
+
+def _validate_library_scope_glob(scope_prefix: str) -> None:
+    """Validate a library scope with glob pattern.
+
+    Library keys have format: lib:ORG:SLUG
+    We only allow wildcards at the organization level (lib:ORG*).
+    Wildcards at slug level are not allowed.
+
+    Args:
+        scope_prefix (str): The library scope without the trailing wildcard
+    """
+    org = _validate_org_identifier(scope_prefix)
+
+    if not _library_org_exists(org):
+        raise ValueError(f"Organization '{org}' does not exist for any library.")
diff --git a/openedx_authz/engine/enforcer.py b/openedx_authz/engine/enforcer.py
@@ -20,6 +20,7 @@
 from uuid import uuid4
 
 from casbin import SyncedEnforcer
+from casbin.util import key_match_func
 from casbin.util.log import DEFAULT_LOGGING, configure_logging
 from casbin_adapter.enforcer import initialize_enforcer
 from django.conf import settings
@@ -279,5 +280,6 @@ def _initialize_enforcer(cls) -> SyncedEnforcer:
         adapter = ExtendedAdapter()
         enforcer = SyncedEnforcer(settings.CASBIN_MODEL, adapter)
         enforcer.add_function("is_staff_or_superuser", is_admin_or_superuser_check)
+        enforcer.add_named_domain_matching_func("g", key_match_func)
 
         return enforcer
diff --git a/openedx_authz/models/scopes.py b/openedx_authz/models/scopes.py
@@ -11,6 +11,7 @@
 from opaque_keys.edx.keys import CourseKey
 from opaque_keys.edx.locator import LibraryLocatorV2
 
+from openedx_authz.api.data import GLOBAL_SCOPE_WILDCARD, ScopeData
 from openedx_authz.models.core import Scope
 
 
@@ -81,16 +82,22 @@ class ContentLibraryScope(Scope):
     )
 
     @classmethod
-    def get_or_create_for_external_key(cls, scope):
+    def get_or_create_for_external_key(cls, scope: ScopeData) -> "ContentLibraryScope":
         """Get or create a ContentLibraryScope for the given external key.
 
         Args:
             scope: ScopeData object with an external_key attribute containing
                 a LibraryLocatorV2-compatible string.
 
         Returns:
-            ContentLibraryScope: The Scope instance for the given ContentLibrary
+            ContentLibraryScope: The Scope instance for the given ContentLibrary,
+                or None if the scope is a glob pattern (contains wildcard).
         """
+        # For glob scopes we don't create a Scope object since
+        # they don't represent a specific content library
+        if GLOBAL_SCOPE_WILDCARD in scope.external_key:
+            return None
+
         library_key = LibraryLocatorV2.from_string(scope.external_key)
         content_library = ContentLibrary.objects.get_by_key(library_key)
         scope, _ = cls.objects.get_or_create(content_library=content_library)
@@ -124,16 +131,22 @@ class CourseScope(Scope):
     )
 
     @classmethod
-    def get_or_create_for_external_key(cls, scope):
+    def get_or_create_for_external_key(cls, scope: ScopeData) -> "CourseScope":
         """Get or create a CourseScope for the given external key.
 
         Args:
             scope: ScopeData object with an external_key attribute containing
                 a CourseKey string.
 
         Returns:
-            CourseScope: The Scope instance for the given CourseOverview
+            CourseScope: The Scope instance for the given CourseOverview,
+                or None if the scope is a glob pattern (contains wildcard).
         """
+        # For glob scopes we don't create a Scope object
+        # since they don't represent a specific course
+        if GLOBAL_SCOPE_WILDCARD in scope.external_key:
+            return None
+
         course_key = CourseKey.from_string(scope.external_key)
         course_overview = CourseOverview.get_from_id(course_key)
         scope, _ = cls.objects.get_or_create(course_overview=course_overview)
diff --git a/openedx_authz/rest_api/v1/serializers.py b/openedx_authz/rest_api/v1/serializers.py
@@ -4,6 +4,7 @@
 from rest_framework import serializers
 
 from openedx_authz import api
+from openedx_authz.api.data import GLOBAL_SCOPE_WILDCARD
 from openedx_authz.rest_api.data import SortField, SortOrder
 from openedx_authz.rest_api.utils import get_generic_scope
 from openedx_authz.rest_api.v1.fields import CommaSeparatedListField, LowercaseCharField
@@ -46,9 +47,10 @@ def validate(self, attrs) -> dict:
         """Validate that the specified role and scope are valid and that the role exists in the scope.
 
         This method performs the following validations:
-        1. Validates that the scope is registered in the scope registry
-        2. Validates that the scope exists in the system
-        3. Validates that the role is defined into the roles assigned to the scope
+        1. Validates that glob patterns in scope follow security rules
+        2. Validates that the scope is registered in the scope registry
+        3. Validates that the scope exists in the system (if not using glob)
+        4. Validates that the role is defined into the roles assigned to the scope
 
         Args:
             attrs: Dictionary containing 'role' and 'scope' keys with their string values.
diff --git a/openedx_authz/tests/test_enforcement.py b/openedx_authz/tests/test_enforcement.py
@@ -11,19 +11,22 @@
 
 import casbin
 import pytest
+from casbin.util import key_match_func
 from ddt import data, ddt, unpack
 from django.contrib.auth import get_user_model
 
 from openedx_authz import ROOT_DIRECTORY
-from openedx_authz.api.data import GLOBAL_SCOPE_WILDCARD
-from openedx_authz.constants import roles
+from openedx_authz.api.data import GLOBAL_SCOPE_WILDCARD, ContentLibraryData, CourseOverviewData
+from openedx_authz.constants import permissions, roles
 from openedx_authz.engine.matcher import is_admin_or_superuser_check
 from openedx_authz.tests.test_utils import (
     make_action_key,
+    make_course_key,
     make_library_key,
     make_role_key,
     make_scope_key,
     make_user_key,
+    make_wildcard_key,
 )
 
 User = get_user_model()
@@ -73,6 +76,7 @@ def setUpClass(cls) -> None:
 
         cls.enforcer = casbin.Enforcer(model_file)
         cls.enforcer.add_function("is_staff_or_superuser", is_admin_or_superuser_check)
+        cls.enforcer.add_named_domain_matching_func("g", key_match_func)
 
     def _load_policy(self, policy: list[str]) -> None:
         """
@@ -583,6 +587,82 @@ def test_wildcard_library_access(self, scope: str, expected_result: bool):
         self._test_enforcement(self.POLICY, request)
 
 
+@ddt
+class OrgGlobEnforcementTests(CasbinEnforcementTestCase):
+    """
+    Tests for organization-level glob patterns in course and library scopes.
+
+    This test class verifies that policies defined with org-level glob patterns
+    (e.g., "course-v1:OpenedX*" or "lib:DemoX*") are correctly enforced for
+    concrete course and library scopes that belong to those organizations.
+    """
+
+    POLICY = [
+        # Policies
+        [
+            "p",
+            make_role_key(roles.COURSE_STAFF.external_key),
+            make_action_key("courses.view_course"),
+            make_wildcard_key(CourseOverviewData.NAMESPACE),
+            "allow",
+        ],
+        [
+            "p",
+            make_role_key(roles.LIBRARY_ADMIN.external_key),
+            make_action_key("content_libraries.view_library"),
+            make_wildcard_key(ContentLibraryData.NAMESPACE),
+            "allow",
+        ],
+        # Role assignments
+        [
+            "g",
+            make_user_key("user-1"),
+            make_role_key(roles.COURSE_STAFF.external_key),
+            make_course_key("course-v1:OpenedX*"),
+        ],
+        [
+            "g",
+            make_user_key("user-2"),
+            make_role_key(roles.LIBRARY_ADMIN.external_key),
+            make_library_key("lib:DemoX*"),
+        ],
+    ]
+
+    CASES = [
+        # Permission granted
+        {
+            "subject": make_user_key("user-1"),
+            "action": make_action_key(permissions.COURSES_VIEW_COURSE.action.external_key),
+            "scope": make_course_key("course-v1:OpenedX+DemoCourse+2026_T1"),
+            "expected_result": True,
+        },
+        {
+            "subject": make_user_key("user-2"),
+            "action": make_action_key(permissions.VIEW_LIBRARY.action.external_key),
+            "scope": make_library_key("lib:DemoX:OrgLevelGlobLib"),
+            "expected_result": True,
+        },
+        # Permission denied
+        {
+            "subject": make_user_key("user-1"),
+            "action": make_action_key(permissions.COURSES_VIEW_COURSE.action.external_key),
+            "scope": make_course_key("course-v1:InexistentOrg+DemoCourse+2026_T1"),
+            "expected_result": False,
+        },
+        {
+            "subject": make_user_key("user-2"),
+            "action": make_action_key(permissions.VIEW_LIBRARY.action.external_key),
+            "scope": make_library_key("lib:InexistentOrg:OrgLevelGlobLib"),
+            "expected_result": False,
+        },
+    ]
+
+    @data(*CASES)
+    def test_org_level_glob_enforcement(self, request: AuthRequest):
+        """Test that org-level glob patterns in scopes are enforced correctly."""
+        self._test_enforcement(self.POLICY, request)
+
+
 @pytest.mark.django_db
 @ddt
 class StaffSuperuserAccessTests(CasbinEnforcementTestCase):
diff --git a/openedx_authz/tests/test_utils.py b/openedx_authz/tests/test_utils.py
