refactor: update authorization model and enforcement command for scope-based permissions

Author: BryanttV

openedx_authz/engine/config/model.conf

@@ -5,10 +5,16 @@
 # - Scoped role assignments (user roles tied to specific contexts)
 # - Action grouping (manage → read/write/delete to reduce duplication)
 # - System-wide roles (global scope "*" applies everywhere)
-# - Granular permissions (exact resources) and broad permissions (org-level)
+# - Scope-based permissions (authorization based on context, not specific objects)
 # - Negative rules (deny overrides allow for exceptions)
-# - Namespace support (course:*, lib:*, org:*, etc.)
-# - Extensibility (new resource types just need new namespaces)
+# - Namespace support (course-v1:*, lib:*, org:*, etc.)
+# - Extensibility (new resource types only require new scope namespaces)
+#
+# DESIGN PRINCIPLE:
+# - Authorization is scope-based, not object-based
+# - Each request is explicitly scoped (course, org, global, etc.)
+# - Permissions are granted within scopes, eliminating need for object matching
+# - Containment relationships are handled by the application layer
 #
 # NOT handled here (deferred to application):
 # - Resource grouping/containment (app resolves parent-child relationships)
@@ -17,59 +23,58 @@
 ############################################
 
 [request_definition]
-# Request format: subject, action, object, scope
+# Request format: subject, action, scope
 #
 # sub   = subject/principal with namespace (e.g., "user:alice", "service:lms")
 # act   = action with namespace (e.g., "act:read", "act:manage", "act:edit-courses")
-# obj   = object/resource with namespace (e.g., "course:course-v1:OpenedX+Demo+2024", "lib:math-basics", "org:OpenedX")
-# scope = authorization scope context (e.g., "org:OpenedX", "lib:math-basics", "*" for global)
+# scope = authorization scope context (e.g., "org:OpenedX", "course-v1:...", "*" for global)
 #
 # SCOPE SEMANTICS:
-# - Scope determines which role assignments are considered
-# - "*"                    = global scope (system-wide roles)
-# - "org:OpenedX"          = organization-scoped roles
-# - "course:course-v1:..." = course-scoped roles
+# - Scope determines the authorization context and which role assignments apply
+# - "*"                    = global scope (system-wide roles apply everywhere)
+# - "org:OpenedX"          = organization-scoped roles (apply within OpenedX org)
+# - "course-v1:..." = course-scoped roles (apply within specific course)
 #
-# - Application must provide appropriate scope based on business logic
-r = sub, act, obj, scope
+# Application must provide appropriate scope based on business logic.
+r = sub, act, scope
 
 [policy_definition]
-# Policy format: subject, action, object, effect
-#
-# sub = role or direct user with namespace (e.g., "role:org_admin", "user:bob")
-# act = action identifier (e.g., "act:manage", "act:read", "act:edit-courses"). Uses g2 relation for action grouping.
-# obj = object selector - supports multiple patterns via keyMatch:
-#      - Exact ID: "course:course-v1:OpenedX+Demo+2024"
-#      - Namespace wildcard: "course:*" (matches all courses)
-#      - Prefix patterns: "course:course-v1:OpenedX+*" (matches all OpenedX courses)
-#      - Scope targets: "org:OpenedX" (organization itself)
-# eft = "allow" or "deny" (deny overrides allow for exceptions)
-p = sub, act, obj, eft
+# Policy format: subject, action, scope, effect
+#
+# sub   = role or user with namespace (e.g., "role:org_admin", "user:bob")
+# act   = action identifier (e.g., "act:manage", "act:read", "act:edit-courses"). Uses g2 relation for action grouping.
+# scope = scope where policy applies (e.g., "*", "org:OpenedX", "course-v1:...")
+# eft   = "allow" or "deny" (deny overrides allow for exceptions)
+p = sub, act, scope, eft
 
 [role_definition]
-# g: Role assignments with scope
-# Format: user/subject, role, scope
+# g: Role assignments (without scope)
+# Format: user/subject, role
+#
+# This is a simplified role assignment where users are assigned roles globally,
+# without being tied to specific scopes. All role assignments apply system-wide.
 #
 # Examples:
-# g, user:alice, role:org_admin, org:OpenedX                 # Alice is org admin for OpenedX
-# g, user:bob, role:course_instructor, course:course-v1:...  # Bob is instructor for specific course
-# g, user:carol, role:platform_admin, *                      # Carol is global platform admin
-# g, service:lms, role:system_service, *                     # LMS service has system-wide access
+# g, user:alice, role:org_admin                 # Alice is org admin
+# g, user:bob, role:course_instructor           # Bob is course instructor
+# g, user:carol, role:platform_admin            # Carol is platform admin
+# g, service:lms, role:system_service           # LMS service has system-wide access
 #
 # Role hierarchy (optional):
-# g, role:org_admin, role:org_editor, org:OpenedX            # org_admin inherits org_editor permissions
-g = _, _, _
+# g, role:org_admin, role:org_editor            # org_admin inherits org_editor permissions
+#
+# NOTE: Without scope in role assignments, authorization control must rely entirely
+# on policy definitions (p) to restrict access to appropriate scopes/contexts.
+g = _, _
 
 # g2: Action grouping and implications
 # Maps high-level actions to specific actions to reduce policy duplication
 #
 # Examples:
-# g2, act:manage, act:read        # manage implies read
 # g2, act:manage, act:edit        # manage implies edit
-# g2, act:manage, act:write       # manage implies write
 # g2, act:manage, act:delete      # manage implies delete
-# g2, act:edit-courses, act:read  # edit-courses implies read (for resource grouping)
-# g2, act:edit-courses, act:write # edit-courses implies write
+# g2, act:edit-courses, act:read  # edit-courses implies read (for resource access)
+# g2, act:edit-courses, act:write # edit-courses implies write (for resource modification)
 g2 = _, _
 
 [policy_effect]
@@ -87,21 +92,26 @@ e = some(where (p.eft == allow)) && !some(where (p.eft == deny))
 [matchers]
 # Authorization matching logic
 #
-# SCOPE MATCHING:
-# - g(r.sub, p.sub, r.scope): check if subject has role in requested scope
-# - g(r.sub, p.sub, "*"): check if subject has global role (applies everywhere)
-#
-# OBJECT MATCHING:
-# - keyMatch(r.obj, p.obj): pattern-based object matching
-#   Supports wildcards like "course:*" matching "course:course-v1:OpenedX+Demo+2024"
-#   Also supports exact matches when no wildcards are used
+# SUBJECT MATCHING:
+# - g(r.sub, p.sub): check if request subject matches policy subject (role assignment)
+#   This handles user-to-role mappings defined in the role_definition section
 #
 # ACTION MATCHING:
-# - g2(p.act, r.act): policy action implies requested action via action grouping
+# - g2(p.act, r.act): policy action implies requested action via grouping
 #   Allows high-level actions (manage) to grant specific actions (read/write/delete)
 #
+# SCOPE MATCHING:
+# - keyMatch(r.scope, p.scope): check if request scope matches policy scope
+#   Supports wildcard matching (e.g., "*" matches any scope)
+#   Enables hierarchical scope matching for nested authorization contexts
+#
 # All conditions must be true for a policy to match:
-# 1. Subject must have the required role in scope OR globally
-# 2. Object must match the policy object pattern
-# 3. Policy action must imply the requested action
-m = (g(r.sub, p.sub, r.scope) || g(r.sub, p.sub, "*")) && keyMatch(r.obj, p.obj) && g2(p.act, r.act)
+# 1. Subject must have the required role (via role assignment)
+# 2. Policy action must imply the requested action (via action grouping)
+# 3. Request scope must match the policy scope (with wildcard support)
+#
+# SCOPE-BASED AUTHORIZATION:
+# The matcher uses keyMatch for flexible scope matching, allowing policies
+# to apply to specific scopes (org:OpenedX) or globally (*), providing
+# fine-grained control over authorization contexts.
+m = g(r.sub, p.sub) && g2(p.act, r.act) && keyMatch(r.scope, p.scope)

openedx_authz/management/commands/enforcement.py

@@ -8,15 +8,15 @@
 The command supports:
 - Loading Casbin model from the built-in model.conf file
 - Using custom policy files (specified via --policy-file-path argument)
-- Interactive testing with format: subject action object scope
+- Interactive testing with format: subject action scope
 - Real-time enforcement results with visual feedback (✓ ALLOWED / ✗ DENIED)
 - Display of loaded policies, role assignments, and action grouping rules
 
 Example usage:
     python manage.py lms enforcement --policy-file-path /path/to/authz.policy
 
 Example test input:
-    user:alice act:read lib:test-lib org:OpenedX
+    user:alice act:read org:OpenedX
 """
 
 import os
@@ -38,7 +38,7 @@ class Command(BaseCommand):
 
     help = (
         "Interactive mode for testing Casbin enforcement policies using model.conf and a custom policy file. "
-        "Provides real-time authorization testing with format: subject action object scope. "
+        "Provides real-time authorization testing with format: subject action scope. "
         "Use --policy-file-path to specify the policy file location."
     )
 
@@ -114,7 +114,7 @@ def _run_interactive_mode(self, enforcer: casbin.Enforcer) -> None:
         """Start the interactive enforcement testing shell.
 
         Provides a continuous loop where users can input enforcement requests
-        in the format 'subject action object scope' and receive immediate
+        in the format 'subject action scope' and receive immediate
         authorization results with visual feedback.
 
         Args:
@@ -127,8 +127,8 @@ def _run_interactive_mode(self, enforcer: casbin.Enforcer) -> None:
         self.stdout.write("Test custom enforcement requests interactively.")
         self.stdout.write("Enter 'quit', 'exit', or 'q' to exit the interactive mode.")
         self.stdout.write("")
-        self.stdout.write("Format: subject action object scope")
-        self.stdout.write("Example: user:alice act:read lib:test-lib org:OpenedX")
+        self.stdout.write("Format: subject action scope")
+        self.stdout.write("Example: user:alice act:read org:OpenedX")
         self.stdout.write("")
 
         while True:
@@ -154,29 +154,28 @@ def _test_interactive_request(self, enforcer: casbin.Enforcer, user_input: str)
 
         Args:
             enforcer (casbin.Enforcer): The Casbin enforcer instance to use for testing.
-            user_input (str): The user's input string in format 'subject action object scope'.
+            user_input (str): The user's input string in format 'subject action scope'.
 
         Expected format:
             subject: The requesting entity (e.g., 'user:alice')
             action: The requested action (e.g., 'act:read')
-            object: The target resource (e.g., 'lib:test-lib')
             scope: The authorization context (e.g., 'org:OpenedX')
         """
         try:
             parts = [part.strip() for part in user_input.split()]
-            if len(parts) != 4:
-                self.stdout.write(self.style.ERROR(f"✗ Invalid format. Expected 4 parts, got {len(parts)}"))
-                self.stdout.write("Format: subject action object scope")
-                self.stdout.write("Example: user:alice act:read lib:test-lib org:OpenedX")
+            if len(parts) != 3:
+                self.stdout.write(self.style.ERROR(f"✗ Invalid format. Expected 3 parts, got {len(parts)}"))
+                self.stdout.write("Format: subject action scope")
+                self.stdout.write("Example: user:alice act:read org:OpenedX")
                 return
 
-            subject, action, obj, scope = parts
-            result = enforcer.enforce(subject, action, obj, scope)
+            subject, action, scope = parts
+            result = enforcer.enforce(subject, action, scope)
 
             if result:
-                self.stdout.write(self.style.SUCCESS(f"✓ ALLOWED: {subject} {action} {obj} {scope}"))
+                self.stdout.write(self.style.SUCCESS(f"✓ ALLOWED: {subject} {action} {scope}"))
             else:
-                self.stdout.write(self.style.ERROR(f"✗ DENIED: {subject} {action} {obj} {scope}"))
+                self.stdout.write(self.style.ERROR(f"✗ DENIED: {subject} {action} {scope}"))
 
         except (ValueError, IndexError, TypeError) as e:
             self.stdout.write(self.style.ERROR(f"✗ Error processing request: {str(e)}"))

openedx_authz/tests/config/authz.policy

@@ -1,56 +1,64 @@
-# ===== POLICIES (p) =====
+############################################
+# Example Policies for Scope-based Model
+############################################
 
-# Platform-level permissions
+# ===== Policies (p) =====
+# Format: p, subject(role), action, scope, effect
+# Note: Scope-based authorization naturally prevents cross-scope access
+
+# Global platform admin: can manage everything
 p, role:platform_admin, act:manage, *, allow
 
-# Organization-level permissions
-p, role:org_admin, act:manage, lib:*, allow
-p, role:org_editor, act:edit, lib:*, allow
+# Org admin: can manage all resources within org OpenedX
+p, role:org_admin, act:manage, org:OpenedX, allow
+
+# Org editor: can edit resources within org OpenedX
+p, role:org_editor, act:edit, org:OpenedX, allow
+
+# Course instructor: can manage resources within a specific course
+p, role:course_instructor, act:manage, course-v1:OpenedX+DemoX+CS101, allow
 
-# Library-specific permissions
-p, role:library_author, act:edit, lib:*, allow
-p, role:library_reviewer, act:read, lib:*, allow
-p, role:editor, act:edit, lib:*, allow
+# Reviewer: can only read within a specific library
+p, role:library_reviewer, act:read, lib:math-basics, allow
 
-# Report permissions
-p, role:report_viewer, act:read, report:*, allow
+# Org admin all: can manage all orgs
+p, role:org_admin_all, act:manage, org:*, allow
 
-# Access restrictions and exceptions
-p, role:org_editor, act:edit, lib:restricted-content, deny
-p, role:org_admin, act:manage, lib:another-restricted-content, deny
+# Explictly deny the org admin for one org
+p, role:org_admin_all, act:manage, org:2U, deny
 
 
-# ===== ROLE ASSIGNMENTS (g) =====
+# ===== Role Assignments (g) =====
+# Format: g, user, role
 
-# Platform administrators
-g, user:admin, role:platform_admin, *
+# Alice is platform admin
+g, user:alice, role:platform_admin
 
-# Organization administrators
-g, user:alice, role:org_admin, org:OpenedX
+# Bob is org admin
+g, user:bob, role:org_admin
 
-# Organization editors
-g, user:bob, role:org_editor, org:MIT
-g, user:paul, role:editor, org:OpenedX
+# Eve is org editor
+g, user:eve, role:org_editor
 
-# Library authors
-g, user:mary, role:library_author, lib:math-basics
-g, user:john, role:library_author, lib:science-101
+# Carol is course instructor
+g, user:carol, role:course_instructor
 
-# Library reviewers
-g, user:sarah, role:library_reviewer, lib:math-basics
+# David is library reviewer
+g, user:david, role:library_reviewer
 
-# Report viewers
-g, user:maria, role:report_viewer, org:OpenedX
+# Steve is org admin (all orgs)
+g, user:steve, role:org_admin_all
 
 
-# ===== ACTION GROUPING (g2) =====
+# ===== Action Grouping (g2) =====
+# Format: g2, high-level-action, implied-action
 
-# manage implies edit, delete, read, write
+# manage implies all other actions
 g2, act:manage, act:edit
+g2, act:manage, act:read
+g2, act:manage, act:write
 g2, act:manage, act:delete
-g2, act:edit, act:read
-g2, act:edit, act:write
 
-# edit implies read, write
+# edit implies read and write
 g2, act:edit, act:read
 g2, act:edit, act:write