feat: add role assignment audit trail

Introduces RoleAssignmentAudit, a read-only log of role assignment and
removal events. Records store namespaced key strings (subject, role, scope)
rather than FK references to live objects, so the audit history survives
deletions independently of the authorization state.

- Model and migration (0008)
- Handler wired to ROLE_ASSIGNMENT_CREATED/DELETED signals
- Read-only Django admin with scope-type filter and namespace-stripped display
- Display properties (subject_display, role_display, scope_display) on the model
- AUTHZ_POLICY_ATTRIBUTES_SEPARATOR moved to constants/ to avoid circular import
- ADR 0012 updated with independence guarantee, actor exception, and filter rationale

Author: mariajgrimaldi

docs/decisions/0012-auditability.rst

@@ -99,6 +99,16 @@ Audit table
 ``RoleAssignmentAudit`` mirrors the event payload. Registered in Django admin, filterable by
 user, role, scope, actor, and timestamp.
 
+Subject, role, and scope are stored as plain namespaced key strings (e.g. ``user^alice``,
+``role^instructor``, ``lib^lib:Org1:lib1``). There are no FK references to live ``Subject``,
+``Scope``, or Casbin tables. Audit records survive the deletion of the underlying objects by
+design: the value of an audit log depends on its unconditional durability.
+
+Because there are no FK references, the namespace prefix embedded in each string is the only
+available signal for categorizing records by type. Admin filters (e.g. "content library",
+"course") rely on ``scope__startswith`` lookups against that prefix rather than relational
+joins.
+
 Developer extensibility
 -----------------------
 
@@ -169,6 +179,15 @@ Both flows
   in the authorization library.
 - ``RoleAssignmentAudit`` is not tamper-proof. Compliance-grade immutability is a
   later-phase concern.
+- Audit records are independent from live authorization state. Deleting a subject, scope, or
+  role does not remove its audit history. Records may reference identifiers that no longer
+  exist in the system.
+- ``actor`` is the exception: it is stored as a FK to the ``User`` model with ``SET_NULL``.
+  Deleting a user sets ``actor`` to ``None``, losing attribution for any audit records they
+  produced. This is an accepted trade-off: user deletion is rare in Open edX (the standard
+  path is retirement, which anonymizes rather than hard-deletes), and the FK enables direct
+  admin filtering by actor. If unconditional attribution durability is needed, ``actor``
+  should be changed to a plain string field.
 
 Alternatives Considered
 ***********************

openedx_authz/admin.py

@@ -4,7 +4,10 @@
 from django import forms
 from django.contrib import admin
 
+from openedx_authz.api.data import ContentLibraryData, CourseOverviewData
+from openedx_authz.constants import AUTHZ_POLICY_ATTRIBUTES_SEPARATOR
 from openedx_authz.models import ExtendedCasbinRule
+from openedx_authz.models.core import RoleAssignmentAudit
 
 
 class CasbinRuleForm(forms.ModelForm):
@@ -48,3 +51,69 @@ class CasbinRuleAdmin(admin.ModelAdmin):
     # TODO: In a future, possibly we should only show an inline for the rules that
     # have an extended rule, and show the subject and scope information in detail.
     inlines = [ExtendedCasbinRuleInline]
+
+
+class ScopeTypeFilter(admin.SimpleListFilter):
+    """Filter audit records by scope type (content library, course, etc.)."""
+
+    title = "scope type"
+    parameter_name = "scope_type"
+
+    def lookups(self, request, model_admin):
+        """Return the available scope type choices.
+
+        Audit records are independent from live Casbin tables and scope objects:
+        there are no FK references to filter on. The namespace prefix in the
+        stored ``scope`` string (e.g. ``lib^``, ``course-v1^``) is the only
+        available signal for categorizing records by scope type.
+        """
+        return [
+            (ContentLibraryData.NAMESPACE, "Content Library"),
+            (CourseOverviewData.NAMESPACE, "Course"),
+        ]
+
+    def queryset(self, request, queryset):
+        """Filter the queryset by scope namespace prefix."""
+        if self.value():
+            return queryset.filter(
+                scope__startswith=f"{self.value()}{AUTHZ_POLICY_ATTRIBUTES_SEPARATOR}"
+            )
+        return queryset
+
+
+@admin.register(RoleAssignmentAudit)
+class RoleAssignmentAuditAdmin(admin.ModelAdmin):
+    """Read-only admin for the role assignment audit log."""
+
+    list_display = ("operation", "display_subject", "display_role", "display_scope", "actor", "timestamp")
+    list_filter = ("operation", ScopeTypeFilter)
+    search_fields = ("subject", "role", "scope")
+    date_hierarchy = "timestamp"
+    readonly_fields = ("operation", "subject", "role", "scope", "actor", "timestamp")
+
+    @admin.display(description="subject")
+    def display_subject(self, obj):
+        """Subject key without the namespace prefix."""
+        return obj.subject_display
+
+    @admin.display(description="role")
+    def display_role(self, obj):
+        """Role name without the namespace prefix."""
+        return obj.role_display
+
+    @admin.display(description="scope")
+    def display_scope(self, obj):
+        """Scope key without the namespace prefix."""
+        return obj.scope_display
+
+    def has_add_permission(self, request):
+        """Audit records are created by the system only."""
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        """Audit records must not be modified after creation."""
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        """Audit records must not be deleted through the admin."""
+        return False

openedx_authz/api/data.py

@@ -13,6 +13,7 @@
 from opaque_keys.edx.locator import LibraryLocatorV2
 from organizations.models import Organization
 
+from openedx_authz.constants import AUTHZ_POLICY_ATTRIBUTES_SEPARATOR
 from openedx_authz.models.scopes import get_content_library_model, get_course_overview_model
 
 ContentLibrary = get_content_library_model()
@@ -35,7 +36,6 @@
     "UserData",
 ]
 
-AUTHZ_POLICY_ATTRIBUTES_SEPARATOR = "^"
 EXTERNAL_KEY_SEPARATOR = ":"
 GLOBAL_SCOPE_WILDCARD = "*"
 NAMESPACED_KEY_PATTERN = rf"^.+{re.escape(AUTHZ_POLICY_ATTRIBUTES_SEPARATOR)}.+$"

openedx_authz/api/roles.py

@@ -13,6 +13,9 @@
 from crum import get_current_user
 from django.db import transaction
 
+from openedx_events.authz.data import RoleAssignmentData as RoleAssignmentEventData
+from openedx_events.authz.signals import ROLE_ASSIGNMENT_CREATED, ROLE_ASSIGNMENT_DELETED
+
 from openedx_authz.api.data import (
     GroupingPolicyIndex,
     PermissionData,
@@ -25,8 +28,7 @@
 from openedx_authz.api.permissions import get_permission_from_policy
 from openedx_authz.engine.enforcer import AuthzEnforcer
 from openedx_authz.models import ExtendedCasbinRule
-from openedx_events.authz.signals import ROLE_ASSIGNMENT_CREATED, ROLE_ASSIGNMENT_DELETED
-from openedx_events.authz.data import RoleAssignmentData as RoleAssignmentEventData
+from openedx_authz.models.core import RoleAssignmentAudit
 
 __all__ = [
     "get_permissions_for_single_role",
@@ -232,10 +234,10 @@ def assign_role_to_subject_in_scope(subject: SubjectData, role: RoleData, scope:
     transaction.on_commit(
         lambda: ROLE_ASSIGNMENT_CREATED.send_event(
             role_assignment=RoleAssignmentEventData(
-                operation=RoleAssignmentEventData.OPERATIONS.created,
-                subject=subject,
-                role=role,
-                scope=scope,
+                operation=RoleAssignmentAudit.OPERATIONS.created,
+                subject=subject.namespaced_key,
+                role=role.namespaced_key,
+                scope=scope.namespaced_key,
                 actor=get_current_user()
             )
         )
@@ -283,10 +285,10 @@ def unassign_role_from_subject_in_scope(subject: SubjectData, role: RoleData, sc
         transaction.on_commit(
             lambda: ROLE_ASSIGNMENT_DELETED.send_event(
                 role_assignment=RoleAssignmentEventData(
-                    operation=RoleAssignmentEventData.OPERATIONS.deleted,
-                    subject=subject,
-                    role=role,
-                    scope=scope,
+                    operation=RoleAssignmentAudit.OPERATIONS.deleted,
+                    subject=subject.namespaced_key,
+                    role=role.namespaced_key,
+                    scope=scope.namespaced_key,
                     actor=get_current_user()
                 )
             )

openedx_authz/constants/__init__.py

@@ -0,0 +1,7 @@
+"""Shared low-level constants for openedx_authz.
+
+Defined here rather than in api.data so that models and other modules at the
+bottom of the import chain can use them without creating circular imports.
+"""
+
+AUTHZ_POLICY_ATTRIBUTES_SEPARATOR = "^"

openedx_authz/handlers.py

@@ -9,9 +9,10 @@
 from casbin_adapter.models import CasbinRule
 from django.db.models.signals import post_delete
 from django.dispatch import receiver
+from openedx_events.authz.signals import ROLE_ASSIGNMENT_CREATED, ROLE_ASSIGNMENT_DELETED
 
 from openedx_authz.api.users import unassign_all_roles_from_user
-from openedx_authz.models.core import ExtendedCasbinRule
+from openedx_authz.models.core import ExtendedCasbinRule, RoleAssignmentAudit
 
 try:
     from openedx.core.djangoapps.user_api.accounts.signals import USER_RETIRE_LMS_CRITICAL
@@ -82,3 +83,33 @@ def unassign_roles_on_user_retirement(sender, user, **kwargs):  # pylint: disabl
 # Only register the handler if the signal is available (i.e., running in Open edX)
 if USER_RETIRE_LMS_CRITICAL is not None:
     USER_RETIRE_LMS_CRITICAL.connect(unassign_roles_on_user_retirement)
+
+
+@receiver(ROLE_ASSIGNMENT_CREATED)
+@receiver(ROLE_ASSIGNMENT_DELETED)
+def create_audit_record_on_role_assignment_change(sender, role_assignment, **kwargs):  # pylint: disable=unused-argument
+    """
+    Create an audit record when a role assignment is created or deleted.
+
+    This handler listens for both creation and deletion of role assignments and logs the changes
+    for auditing purposes.
+
+    Args:
+        sender: The signal class (ROLE_ASSIGNMENT_CREATED or ROLE_ASSIGNMENT_DELETED).
+        role_assignment: RoleAssignmentEventData carrying the operation, subject, role, scope, and actor.
+        **kwargs: Additional keyword arguments from the signal.
+    """
+    try:
+        RoleAssignmentAudit.objects.create(
+            operation=role_assignment.operation,
+            subject=role_assignment.subject,
+            role=role_assignment.role,
+            scope=role_assignment.scope,
+            actor=role_assignment.actor,
+            timestamp=kwargs["metadata"].time,
+        )
+    except Exception as exc:  # pylint: disable=broad-exception-caught
+        logger.exception(
+            "Error creating audit record for role assignment change: %s",
+            exc,
+        )

openedx_authz/migrations/0008_roleassignmentaudit.py

@@ -0,0 +1,56 @@
+# Generated by Django 4.2.24 on 2026-04-14 09:51
+
+from django.conf import settings
+from django.db import migrations, models
+import django.db.models.deletion
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        migrations.swappable_dependency(settings.AUTH_USER_MODEL),
+        ("openedx_authz", "0007_coursescope"),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name="RoleAssignmentAudit",
+            fields=[
+                (
+                    "id",
+                    models.BigAutoField(
+                        auto_created=True,
+                        primary_key=True,
+                        serialize=False,
+                        verbose_name="ID",
+                    ),
+                ),
+                (
+                    "operation",
+                    models.CharField(
+                        choices=[("created", "created"), ("deleted", "deleted")],
+                        max_length=20,
+                    ),
+                ),
+                ("subject", models.CharField(max_length=255)),
+                ("role", models.CharField(max_length=255)),
+                ("scope", models.CharField(max_length=255)),
+                ("timestamp", models.DateTimeField()),
+                (
+                    "actor",
+                    models.ForeignKey(
+                        blank=True,
+                        null=True,
+                        on_delete=django.db.models.deletion.SET_NULL,
+                        related_name="performed_role_assignment_audits",
+                        to=settings.AUTH_USER_MODEL,
+                    ),
+                ),
+            ],
+            options={
+                "verbose_name": "Role Assignment Audit",
+                "verbose_name_plural": "Role Assignment Audits",
+                "ordering": ["-timestamp"],
+            },
+        ),
+    ]

openedx_authz/models/core.py

@@ -5,13 +5,17 @@
 schema that focuses on the core authorization logic.
 """
 
-from typing import ClassVar
+from typing import ClassVar, NamedTuple
 
+from django.contrib.auth import get_user_model
 from django.db import models, transaction
 
+from openedx_authz.constants import AUTHZ_POLICY_ATTRIBUTES_SEPARATOR
 from openedx_authz.engine.filter import Filter
 
 
+User = get_user_model()
+
 class BaseRegistryModel(models.Model):
     """Base model that supports automatic subclass registration.
 
@@ -231,3 +235,65 @@ def create_based_on_policy(
             )
 
         return extended_rule
+
+
+class RoleAssignmentAudit(models.Model):
+    """Model to audit role assignments and unassignments.
+
+    .. no_pii:
+
+    This model captures the history of role assignments and unassignments for subjects
+    within specific scopes. It can be used for auditing purposes to track changes in
+    role assignments over time.
+    """
+
+    class Operations(NamedTuple):
+        created: str = "created"
+        deleted: str = "deleted"
+
+    OPERATIONS = Operations()
+
+    operation = models.CharField(
+        max_length=20,
+        choices=[(op, op) for op in OPERATIONS],
+    )
+    subject = models.CharField(
+        max_length=255,
+        help_text="Namespaced key of the subject (e.g. 'user^john_doe').",
+    )
+    role = models.CharField(
+        max_length=255,
+        help_text="Namespaced key of the role (e.g. 'role^library_admin').",
+    )
+    scope = models.CharField(
+        max_length=255,
+        help_text="Namespaced key of the scope (e.g. 'course-v1^course-v1:org+course+run') or glob pattern.",
+    )
+    actor = models.ForeignKey(
+        User,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="performed_role_assignment_audits",
+    )
+    timestamp = models.DateTimeField()
+
+    class Meta:
+        verbose_name = "Role Assignment Audit"
+        verbose_name_plural = "Role Assignment Audits"
+        ordering = ["-timestamp"]
+
+    @property
+    def subject_display(self) -> str:
+        """Subject key without the namespace prefix (e.g. ``john_doe`` for ``user^john_doe``)."""
+        return self.subject.split(AUTHZ_POLICY_ATTRIBUTES_SEPARATOR, 1)[-1]
+
+    @property
+    def role_display(self) -> str:
+        """Role name without the namespace prefix (e.g. ``library_admin`` for ``role^library_admin``)."""
+        return self.role.split(AUTHZ_POLICY_ATTRIBUTES_SEPARATOR, 1)[-1]
+
+    @property
+    def scope_display(self) -> str:
+        """Scope key without the namespace prefix (e.g. ``lib:Org1:lib1`` for ``lib^lib:Org1:lib1``)."""
+        return self.scope.split(AUTHZ_POLICY_ATTRIBUTES_SEPARATOR, 1)[-1]