feat: add role assignment audit trail (#261)

Emits ROLE_ASSIGNMENT_CREATED and ROLE_ASSIGNMENT_DELETED events after
role assignment operations commit, so consumers can stay up to date on
the authorization state of the system. Each event includes the subject,
role, scope, and the actor performing the operation (via get_current_user()).

Also adds the auditability ADR (0012) documenting the design decisions
behind this feature.

Author: mariajgrimaldi

CHANGELOG.rst

@@ -14,6 +14,16 @@ Change Log
 Unreleased
 **********
 
+1.13.0 - 2026-04-22
+*******************
+
+Added
+=====
+
+* Add ``RoleAssignmentAudit`` model to record role assignment and removal events, including operation type, subject, role, scope, actor database ID, and timestamp.
+* Emit ``ROLE_ASSIGNMENT_CREATED`` and ``ROLE_ASSIGNMENT_DELETED`` Open edX public signal events via ``transaction.on_commit`` after every successful role assignment or removal.
+* Add Django admin for ``RoleAssignmentAudit`` with filters by operation type and scope type (course, content library), date hierarchy, and search by subject, role, and scope.
+
 1.12.0 - 2026-04-20
 *******************
 

docs/decisions/0012-auditability.rst

@@ -0,0 +1,213 @@
+0012: Auditability for Authorization Changes
+############################################
+
+Status
+******
+
+**Draft**
+
+Context
+*******
+
+The existing architecture (see `ADR 0005`_) introduced ``ExtendedCasbinRule``, which adds
+``created_at``, ``updated_at``, and a ``metadata`` JSON field to the ``CasbinRule`` table.
+This is not an audit trail: there is no actor, no operation type, and no mechanism for
+downstream consumers to react to changes.
+
+Operators and developers need answers the current system cannot provide:
+
+- Who assigned this role, and when?
+- Who removed a user's access, and was it intentional?
+- Why was a permission check denied?
+
+A spike (OEPM-Spike: RBAC AuthZ Auditability) examined how peer systems approach this.
+Auditability decomposes into three dimensions:
+
+1. **Attribution**: who changed access? (role assignments, removals)
+2. **Explainability**: why was access granted or denied? (policy evaluation at check time)
+3. **Usage**: who used access? (resource access events, business operations)
+
+`SpiceDB`_ and `OpenFGA`_ track the full authorization graph as a versioned changelog,
+enabling historical reconstruction. Keycloak uses event listeners on administrative actions.
+openedx-authz sits between these: a mutable policy store with no built-in audit layer.
+(See `OEPM-Spike\: RBAC AuthZ Auditability`_ for the peer system analysis.)
+
+The pycasbin ecosystem has no audit plugin. Two transitive dependencies cover what is needed:
+``django-crum`` (via ``edx-django-utils``) for actor capture, and ``django-simple-history``
+(via ``edx-organizations``) for point-in-time state reconstruction.
+
+Decision
+********
+
+Three independent mechanisms, each answering a different question:
+
+- ``OpenedxPublicSignal``: something happened, react now
+- ``RoleAssignmentAudit``: what happened, in what order, performed by whom
+- ``django-simple-history`` on ``ExtendedCasbinRule``: what was the full state at time T
+  (future work)
+
+See the `OEPM-Spike\: RBAC AuthZ Auditability`_ for the architecture diagram of the three
+flows.
+
+#. Attribution: Role Lifecycle Events and Audit Table
+=====================================================
+
+Emit an ``OpenedxPublicSignal`` from ``openedx_authz.api.roles`` after every successful role
+assignment or removal, via ``transaction.on_commit``. A synchronous Django signal receiver
+writes the event to ``RoleAssignmentAudit`` in the same process.
+
+The handler is enabled by default. Operators with Aspects or a SIEM can disable it via a
+Django setting to avoid the redundant write. If the handler fails, the Casbin write and the
+event are unaffected.
+
+Event payload
+-------------
+
+.. code:: python
+
+    {
+        "operation": "created" | "deleted",
+        "subject":   "<namespaced subject key, e.g. user^alice>",
+        "role":      "<namespaced role key, e.g. role^instructor>",
+        "scope":     "<namespaced scope key, e.g. course-v1^course-v1:Org+Course+Run>",
+        "actor_id":  <database ID of the caller (int), or None for system actor>,
+    }
+
+The actor is resolved from ``django_crum.get_current_user()`` at API call time. No callers
+need to pass ``actor_id=`` explicitly.
+
+Audit table
+-----------
+
+``RoleAssignmentAudit`` mirrors the event payload. Registered in Django admin, filterable by
+user, role, scope, actor_id, 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
+-----------------------
+
+Plugin authors register handlers on the ``OpenedxPublicSignal`` to react to role lifecycle
+events (notifications, cache updates, analytics). Developers without an event bus can consume
+the underlying Django signal directly. If an event bus is configured, events are forwarded to
+Aspects or external systems automatically.
+
+#. Explainability: Real-Time Decision Context
+=============================================
+
+Expose ``enforce_ex()`` through the public Python API. It returns ``(result, explain_rule)``:
+the boolean decision and the matched policy rule. Callers get the exact rule that allowed or
+denied the request.
+
+Enforcement events are opt-in via ``AUTHZ_ENFORCEMENT_EVENTS_ENABLED``. When enabled, each
+check fires an ``OpenedxPublicSignal`` forwarded to plugin consumers or an event bus. No audit
+table is written: the volume makes per-check storage impractical.
+
+Historical explainability ("why did this user have access last Tuesday?") is deferred. Two
+options are available, both requiring a breaking change to ``is_user_allowed`` to accept
+``as_of``:
+
+- **Option A (event replay):** Replay ``ASSIGN``/``REMOVE`` events from ``RoleAssignmentAudit``
+  up to T. No extra infrastructure; the data is already there once attribution is implemented.
+  The `Auth0 FGA Logging API`_ uses this same pattern: their logging API is an event store
+  that you replay to answer historical questions.
+- **Option B (snapshots):** Add ``HistoricalRecords()`` to ``ExtendedCasbinRule`` and use
+  ``as_of(T)`` for the full rule state, including policy definitions. History collection must
+  start before the target timestamp.
+
+``authz.policy`` is loaded into the DB and covered by Option B. ``model.conf`` is not
+persisted. A ``model_hash`` field on ``ExtendedCasbinRule`` would let historical queries
+detect whether the model changed.
+
+Consequences
+************
+
+#. **Operators get a filterable role assignment history in Django admin.** No external
+   tooling required.
+
+#. **Developers get a stable** ``OpenedxPublicSignal`` **extension point.** First formally
+   defined event in openedx-authz. Callers of ``openedx_authz.api.roles`` need no signature
+   changes.
+
+#. **Events are best-effort.** If the audit write fails, the Casbin policy is still durable.
+   Consumers requiring guaranteed delivery must implement their own retry logic.
+
+#. **``actor_id`` is nullable.** Non-request contexts (management commands, background tasks)
+   record ``None``, logged as a system operation. ``actor_id`` is stored as a plain integer
+   (the database ID of the caller) rather than a FK to ``User``. This avoids a dependency
+   on the ``User`` table and keeps audit records fully independent from live data. Attribution
+   is preserved unconditionally: deleting or retiring a user does not affect existing records.
+
+#. **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.
+
+#. **``RoleAssignmentAudit`` introduces a new migration.** No existing table is modified.
+
+#. **The** ``OpenedxPublicSignal`` **schema is a public API surface.** Field additions are
+   backward-compatible; removals and renames are breaking changes.
+
+#. **``RoleAssignmentAudit`` is not tamper-proof.** Compliance-grade immutability is a
+   later-phase concern.
+
+#. **No new dependencies introduced.** ``django-crum`` and ``django-simple-history`` are
+   already transitive dependencies.
+
+#. **Usage auditing belongs at the application layer** (Open edX tracking events, Aspects),
+   not in the authorization library.
+
+#. **Developers can retrieve the matched policy rule at check time** for "why was this
+   denied?" debugging. The explanation is point-in-time only; historical explainability is
+   deferred.
+
+#. **Enforcement events are opt-in by design.** Enabling them without an external consumer
+   produces events that are emitted and discarded.
+
+Alternatives Considered
+***********************
+
+``django-simple-history`` on ``ExtendedCasbinRule`` as the attribution audit trail
+===================================================================================
+
+Rejected for three reasons:
+
+- ``save_policy`` (`casbin-django-orm-adapter adapter.py`_) uses ``QuerySet.delete()`` and
+  ``bulk_create``, both of which bypass model signals. History snapshots reflect when the
+  table was written, not when a role was assigned.
+- ``ExtendedCasbinRule`` fields (``ptype``, ``v0``--``v5``) are semi-opaque and require an
+  interpretation layer. ``RoleAssignmentAudit`` translates at write time.
+
+``django-simple-history`` remains the right tool for Option B (point-in-time state
+reconstruction), where it is a snapshot mechanism, not an operation log.
+
+References
+**********
+
+- `ADR 0002`_
+- `ADR 0004`_
+- `ADR 0005`_
+- `Auth0 FGA Logging API`_
+- `openedx-events documentation`_
+- `django-simple-history documentation`_
+- `django-crum documentation`_
+- `OEPM-Spike: RBAC AuthZ Auditability`_
+
+.. _ADR 0002: https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0002-authorization-model-foundation.rst
+.. _ADR 0004: https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0004-technology-selection.rst
+.. _ADR 0005: https://github.com/openedx/openedx-authz/blob/main/docs/decisions/0005-architecture-and-data-modeling.rst
+.. _Auth0 FGA Logging API: https://auth0.com/blog/auth0-fga-logging-api-a-complete-audit-trail-for-authorization/
+.. _SpiceDB: https://github.com/authzed/spicedb
+.. _OpenFGA: https://openfga.dev/
+.. _openedx-events documentation: https://docs.openedx.org/projects/openedx-events/en/latest/
+.. _django-simple-history documentation: https://django-simple-history.readthedocs.io/
+.. _django-crum documentation: https://pypi.org/project/django-crum/
+.. _casbin-django-orm-adapter adapter.py: https://github.com/officialpycasbin/django-orm-adapter/blob/main/casbin_adapter/adapter.py
+.. _OEPM-Spike\: RBAC AuthZ Auditability: https://openedx.atlassian.net/wiki/spaces/OEPM/pages/6045859842/Spike+-+RBAC+AuthZ+-+Auditability

openedx_authz/__init__.py

@@ -4,6 +4,6 @@
 
 import os
 
-__version__ = "1.12.0"
+__version__ = "1.13.0"
 
 ROOT_DIRECTORY = os.path.dirname(os.path.abspath(__file__))

openedx_authz/admin.py

@@ -7,7 +7,9 @@
 from django.contrib import admin
 from django.utils.html import format_html
 
+from openedx_authz.api.data import ContentLibraryData, CourseOverviewData
 from openedx_authz.models import AuthzCourseAuthoringMigrationRun, ExtendedCasbinRule
+from openedx_authz.models.core import RoleAssignmentAudit
 
 
 def pretty_json(value) -> str:
@@ -87,3 +89,68 @@ class AuthzCourseAuthoringMigrationRunAdmin(admin.ModelAdmin):
     def pretty_metadata(self, obj):
         """Return formatted JSON for the metadata field."""
         return pretty_json(obj.metadata)
+
+
+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.for_scope_namespace(self.value())
+        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_id", "timestamp")
+    list_filter = ("operation", ScopeTypeFilter)
+    search_fields = ("subject", "role", "scope")
+    date_hierarchy = "timestamp"
+    readonly_fields = ("operation", "subject", "role", "scope", "actor_id", "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