From 7597a92bf25ea1e0372e974c067c501ad618a708 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20M=C3=A9ndez?= Date: Mon, 9 Nov 2026 17:10:52 -0600 Subject: [PATCH 1/4] docs: ADR Audit Trail for Custom Role Changes --- docs/decisions/0012-auditability.rst | 9 ++ ...5-authorization-schema-source-tracking.rst | 8 + .../0037-custom-role-audit-trail.rst | 148 ++++++++++++++++++ 3 files changed, 165 insertions(+) create mode 100644 docs/decisions/0037-custom-role-audit-trail.rst diff --git a/docs/decisions/0012-auditability.rst b/docs/decisions/0012-auditability.rst index f2d6cbe5..eb0fee7c 100644 --- a/docs/decisions/0012-auditability.rst +++ b/docs/decisions/0012-auditability.rst @@ -188,6 +188,13 @@ Rejected for three reasons: ``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. +Addendum (2026-11-09) +********************* + +`ADR 0037`_ records custom role changes in a separate ``RoleDefinitionAudit`` table and adds a +nullable ``role_change_id`` to ``RoleAssignmentAudit`` and the assignment event data. It links +assignments deleted or created by removing a role or moving its members to that role change. + References ********** @@ -199,10 +206,12 @@ References - `django-simple-history documentation`_ - `django-crum documentation`_ - `OEPM-Spike: RBAC AuthZ Auditability`_ +- `ADR 0037`_ .. _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 +.. _ADR 0037: 0037-custom-role-audit-trail.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/ diff --git a/docs/decisions/0025-authorization-schema-source-tracking.rst b/docs/decisions/0025-authorization-schema-source-tracking.rst index 3e9c025c..27772556 100644 --- a/docs/decisions/0025-authorization-schema-source-tracking.rst +++ b/docs/decisions/0025-authorization-schema-source-tracking.rst @@ -215,6 +215,12 @@ Consequences * Compilation must track provenance at the role-permission grain, and the apply step writes the definition, relationship, and source tables in the same transaction as the policy rows. +Addendum (2026-11-09) +********************* + +`ADR 0037`_ decides source tracking for custom (dynamic) roles: they get no source rows, and their +``created`` audit record says who created them and when. + References ********** @@ -223,9 +229,11 @@ References * `ADR 0019`_ * `ADR 0021`_ * `ADR 0023`_ +* `ADR 0037`_ .. _ADR 0017: 0017-static-authorization-schema.rst .. _ADR 0018: 0018-authorization-schema-lifecycle.rst .. _ADR 0019: 0019-authorization-schema-discovery.rst .. _ADR 0021: 0021-authorization-definition-api.rst .. _ADR 0023: 0023-extend-static-roles.rst +.. _ADR 0037: 0037-custom-role-audit-trail.rst diff --git a/docs/decisions/0037-custom-role-audit-trail.rst b/docs/decisions/0037-custom-role-audit-trail.rst new file mode 100644 index 00000000..12f3a7e3 --- /dev/null +++ b/docs/decisions/0037-custom-role-audit-trail.rst @@ -0,0 +1,148 @@ +0037: Audit Trail for Custom Role Changes +######################################### + +Status +****** + +**Draft** + +Context +******* + +`ADR 0035`_ and `ADR 0036`_ let Django staff and superusers create, edit, and remove custom roles, +and move a role's members to another role. Each change takes effect right away for every user who +holds the role. + +`ADR 0012`_ records role assignment changes in ``RoleAssignmentAudit``, through the assignment events +in openedx-events. Nothing records changes to a role definition. An assignment deleted or moved +because a role was removed or reassigned is recorded the same way as a manual change, so the audit +cannot tell why it happened. + +`ADR 0025`_ records which module contributed each static definition. It leaves source tracking for +dynamically created definitions to a future decision. This ADR is that decision for custom roles. + +Decision +******** + +1. Record custom role changes in a dedicated table +================================================== + +Every custom role change writes one record to a new ``RoleDefinitionAudit`` table, one per request: + +.. list-table:: + :header-rows: 1 + + * - Action + - Operation + * - Create, including a copy + - ``created`` + * - Edit the name, description, or permissions + - ``updated`` + * - Remove + - ``deleted`` + * - Move members to another role + - ``members_reassigned`` + * - A deployment drops grants for removed permissions (`ADR 0035`_) + - ``updated`` + +Each record stores the operation, a ``change_id`` (UUID), the namespaced role key, the change, the +``actor_id``, and a timestamp. It follows the rules of `ADR 0012`_: values are plain strings with no +foreign keys, so records survive the removal of the role, and the actor comes from +``django_crum.get_current_user()``. The actor is ``None`` for system changes such as deployments. + +Copies are recorded as ``created``. The server does not know a role was copied (`ADR 0036`_). + +2. Store what changed +===================== + +The ``changes`` field is JSON: + +* ``created`` and ``deleted``: the full role: ``display_name``, ``description``, ``scope_types``, + and ``permissions``. A ``deleted`` record also stores how the assignments were handled + (``revoke`` or ``reassign``) and the ``target_role``, if any. +* ``updated``: only the fields that changed. A name or description change stores the old and new + values. A permission change stores ``permissions_added`` and ``permissions_removed``. +* ``members_reassigned``: the ``target_role``. + +3. Link assignment changes to the role change +============================================= + +``RoleAssignmentAudit`` and the assignment event data gain a nullable ``role_change_id``. Every +assignment that is deleted or created because a role was removed or its members were moved carries +the ``change_id`` of that role change. Direct assignments and removals leave it empty. + +The API generates the ``change_id`` before any write and passes it to the role event and to each +assignment event. The link does not depend on the order in which the handlers run. + +4. Events +========= + +openedx-events gains ``ROLE_DEFINITION_CREATED``, ``ROLE_DEFINITION_UPDATED``, +``ROLE_DEFINITION_DELETED``, and ``ROLE_MEMBERS_REASSIGNED``. The payload carries the operation, +``change_id``, role, ``changes`` (as a JSON string, so the event bus can serialize it), and +``actor_id``. + +As in `ADR 0012`_, the events are sent with ``transaction.on_commit``, a handler writes the audit +record, and the same setting that disables the assignment audit handler disables this one. + +5. Provenance of custom roles +============================= + +Custom roles have no source links in the `ADR 0025`_ tables (`ADR 0035`_). Their ``created`` record +says who created them and when. No other source tracking is added for custom roles. + +6. Reading the history +====================== + +The table is registered in Django admin and can be filtered by role, operation, actor, and +timestamp. A REST endpoint for the history is deferred until a UI needs it. + +Consequences +************ + +* One migration adds ``RoleDefinitionAudit`` and the ``role_change_id`` field on + ``RoleAssignmentAudit``. +* openedx-events needs a release with the new events and the ``role_change_id`` field before this + ships. Adding a field to the assignment event data is backward-compatible (`ADR 0012`_). +* The assignments affected by removing a role or moving its members can be found by filtering + ``RoleAssignmentAudit`` by ``role_change_id``. +* The audit is best-effort, as in `ADR 0012`_. If the write fails, the role change still applies. +* Changes to static roles are not recorded here. Deployments and `ADR 0025`_ source tracking cover + them. +* The history is visible in Django admin only. No UI or REST API is added. + +Rejected Alternatives +********************* + +Reuse ``RoleAssignmentAudit`` +============================= + +Definition changes have no subject or scope, and an edit can change many permissions at once. +Mixing both kinds of record in one table would leave columns empty and make the admin filters +ambiguous. + +``django-simple-history`` on the definition tables +================================================== + +A permission edit touches many grant rows, so one request would produce many snapshots with no +single record of the change. Bulk writes also bypass model signals, the same problem `ADR 0012`_ +found for ``ExtendedCasbinRule``. + +Source rows in the `ADR 0025`_ tables +===================================== + +Those tables record which module contributed a definition, and they hold the current state. A user +is not a module, and an audit needs every change, not only the latest one. + +References +********** + +* `ADR 0012`_ +* `ADR 0025`_ +* `ADR 0035`_ +* `ADR 0036`_ + +.. _ADR 0012: 0012-auditability.rst +.. _ADR 0025: 0025-authorization-schema-source-tracking.rst +.. _ADR 0035: 0035-custom-role-persistence.rst +.. _ADR 0036: 0036-api-contract-for-custom-roles.rst From 162930f21338a82b2c507872a5664682f8b70398 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20M=C3=A9ndez?= Date: Thu, 12 Nov 2026 16:45:21 -0600 Subject: [PATCH 2/4] docs: remove reassignment feature as not planned --- .../0037-custom-role-audit-trail.rst | 27 ++++++++----------- 1 file changed, 11 insertions(+), 16 deletions(-) diff --git a/docs/decisions/0037-custom-role-audit-trail.rst b/docs/decisions/0037-custom-role-audit-trail.rst index 12f3a7e3..59a442e8 100644 --- a/docs/decisions/0037-custom-role-audit-trail.rst +++ b/docs/decisions/0037-custom-role-audit-trail.rst @@ -9,14 +9,13 @@ Status Context ******* -`ADR 0035`_ and `ADR 0036`_ let Django staff and superusers create, edit, and remove custom roles, -and move a role's members to another role. Each change takes effect right away for every user who -holds the role. +`ADR 0035`_ and `ADR 0036`_ let Django staff and superusers create, edit, and remove custom roles. +Each change takes effect right away for every user who holds the role. `ADR 0012`_ records role assignment changes in ``RoleAssignmentAudit``, through the assignment events -in openedx-events. Nothing records changes to a role definition. An assignment deleted or moved -because a role was removed or reassigned is recorded the same way as a manual change, so the audit -cannot tell why it happened. +in openedx-events. Nothing records changes to a role definition. An assignment deleted because a +role was removed is recorded the same way as a manual change, so the audit cannot tell why it +happened. `ADR 0025`_ records which module contributed each static definition. It leaves source tracking for dynamically created definitions to a future decision. This ADR is that decision for custom roles. @@ -40,8 +39,6 @@ Every custom role change writes one record to a new ``RoleDefinitionAudit`` tabl - ``updated`` * - Remove - ``deleted`` - * - Move members to another role - - ``members_reassigned`` * - A deployment drops grants for removed permissions (`ADR 0035`_) - ``updated`` @@ -58,18 +55,16 @@ Copies are recorded as ``created``. The server does not know a role was copied ( The ``changes`` field is JSON: * ``created`` and ``deleted``: the full role: ``display_name``, ``description``, ``scope_types``, - and ``permissions``. A ``deleted`` record also stores how the assignments were handled - (``revoke`` or ``reassign``) and the ``target_role``, if any. + and ``permissions``. * ``updated``: only the fields that changed. A name or description change stores the old and new values. A permission change stores ``permissions_added`` and ``permissions_removed``. -* ``members_reassigned``: the ``target_role``. 3. Link assignment changes to the role change ============================================= ``RoleAssignmentAudit`` and the assignment event data gain a nullable ``role_change_id``. Every -assignment that is deleted or created because a role was removed or its members were moved carries -the ``change_id`` of that role change. Direct assignments and removals leave it empty. +assignment that is deleted because a role was removed carries the ``change_id`` of that role +change. Direct assignments and removals leave it empty. The API generates the ``change_id`` before any write and passes it to the role event and to each assignment event. The link does not depend on the order in which the handlers run. @@ -78,7 +73,7 @@ assignment event. The link does not depend on the order in which the handlers ru ========= openedx-events gains ``ROLE_DEFINITION_CREATED``, ``ROLE_DEFINITION_UPDATED``, -``ROLE_DEFINITION_DELETED``, and ``ROLE_MEMBERS_REASSIGNED``. The payload carries the operation, +and ``ROLE_DEFINITION_DELETED``. The payload carries the operation, ``change_id``, role, ``changes`` (as a JSON string, so the event bus can serialize it), and ``actor_id``. @@ -104,8 +99,8 @@ Consequences ``RoleAssignmentAudit``. * openedx-events needs a release with the new events and the ``role_change_id`` field before this ships. Adding a field to the assignment event data is backward-compatible (`ADR 0012`_). -* The assignments affected by removing a role or moving its members can be found by filtering - ``RoleAssignmentAudit`` by ``role_change_id``. +* The assignments affected by removing a role can be found by filtering ``RoleAssignmentAudit`` by + ``role_change_id``. * The audit is best-effort, as in `ADR 0012`_. If the write fails, the role change still applies. * Changes to static roles are not recorded here. Deployments and `ADR 0025`_ source tracking cover them. From 0984fbf2e77cf4e652510fe1de63f9eb88f5f76b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20M=C3=A9ndez?= Date: Fri, 13 Nov 2026 17:26:26 -0600 Subject: [PATCH 3/4] squash!: Attend comments --- docs/decisions/0012-auditability.rst | 2 +- docs/decisions/0037-custom-role-audit-trail.rst | 7 ++++--- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/decisions/0012-auditability.rst b/docs/decisions/0012-auditability.rst index eb0fee7c..2633554f 100644 --- a/docs/decisions/0012-auditability.rst +++ b/docs/decisions/0012-auditability.rst @@ -193,7 +193,7 @@ Addendum (2026-11-09) `ADR 0037`_ records custom role changes in a separate ``RoleDefinitionAudit`` table and adds a nullable ``role_change_id`` to ``RoleAssignmentAudit`` and the assignment event data. It links -assignments deleted or created by removing a role or moving its members to that role change. +assignments deleted by removing a role to that role change. References ********** diff --git a/docs/decisions/0037-custom-role-audit-trail.rst b/docs/decisions/0037-custom-role-audit-trail.rst index 59a442e8..563c3798 100644 --- a/docs/decisions/0037-custom-role-audit-trail.rst +++ b/docs/decisions/0037-custom-role-audit-trail.rst @@ -73,9 +73,10 @@ assignment event. The link does not depend on the order in which the handlers ru ========= openedx-events gains ``ROLE_DEFINITION_CREATED``, ``ROLE_DEFINITION_UPDATED``, -and ``ROLE_DEFINITION_DELETED``. The payload carries the operation, -``change_id``, role, ``changes`` (as a JSON string, so the event bus can serialize it), and -``actor_id``. +and ``ROLE_DEFINITION_DELETED``. The payload carries the ``change_id``, role, ``changes`` (as a +JSON string, so the event bus can serialize it), and ``actor_id``. The event type gives the +operation, so the payload does not repeat it. The handler maps each event to its operation when it +writes the audit record. As in `ADR 0012`_, the events are sent with ``transaction.on_commit``, a handler writes the audit record, and the same setting that disables the assignment audit handler disables this one. From b0efcef79a890b3d2de060eee3542b2b2269afa2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rodrigo=20M=C3=A9ndez?= Date: Fri, 13 Nov 2026 17:33:47 -0600 Subject: [PATCH 4/4] squash!: Align with other ADR changes --- .../0025-authorization-schema-source-tracking.rst | 4 ++-- docs/decisions/0037-custom-role-audit-trail.rst | 15 +++++++++------ 2 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/decisions/0025-authorization-schema-source-tracking.rst b/docs/decisions/0025-authorization-schema-source-tracking.rst index 27772556..c606fc0b 100644 --- a/docs/decisions/0025-authorization-schema-source-tracking.rst +++ b/docs/decisions/0025-authorization-schema-source-tracking.rst @@ -218,8 +218,8 @@ Consequences Addendum (2026-11-09) ********************* -`ADR 0037`_ decides source tracking for custom (dynamic) roles: they get no source rows, and their -``created`` audit record says who created them and when. +`ADR 0037`_ records who created each custom (dynamic) role, and when, in its ``created`` audit +record. References ********** diff --git a/docs/decisions/0037-custom-role-audit-trail.rst b/docs/decisions/0037-custom-role-audit-trail.rst index 563c3798..94caa91b 100644 --- a/docs/decisions/0037-custom-role-audit-trail.rst +++ b/docs/decisions/0037-custom-role-audit-trail.rst @@ -17,8 +17,8 @@ in openedx-events. Nothing records changes to a role definition. An assignment d role was removed is recorded the same way as a manual change, so the audit cannot tell why it happened. -`ADR 0025`_ records which module contributed each static definition. It leaves source tracking for -dynamically created definitions to a future decision. This ADR is that decision for custom roles. +`ADR 0025`_ records which module contributed each static definition. `ADR 0035`_ stores custom roles +in the same tables with no source links, so nothing records who created a custom role or when. Decision ******** @@ -26,7 +26,8 @@ Decision 1. Record custom role changes in a dedicated table ================================================== -Every custom role change writes one record to a new ``RoleDefinitionAudit`` table, one per request: +Every custom role change writes one record to a new ``RoleDefinitionAudit`` table: one per request, +or one per affected role when a deployment drops grants from several roles. .. list-table:: :header-rows: 1 @@ -35,7 +36,7 @@ Every custom role change writes one record to a new ``RoleDefinitionAudit`` tabl - Operation * - Create, including a copy - ``created`` - * - Edit the name, description, or permissions + * - Edit the description or permissions - ``updated`` * - Remove - ``deleted`` @@ -47,6 +48,9 @@ Each record stores the operation, a ``change_id`` (UUID), the namespaced role ke foreign keys, so records survive the removal of the role, and the actor comes from ``django_crum.get_current_user()``. The actor is ``None`` for system changes such as deployments. +`ADR 0035`_ keeps a removed role's row and never reuses its ID, so each role key in the audit always +names one role, and the admin can still show a removed role's display name. + Copies are recorded as ``created``. The server does not know a role was copied (`ADR 0036`_). 2. Store what changed @@ -56,8 +60,7 @@ The ``changes`` field is JSON: * ``created`` and ``deleted``: the full role: ``display_name``, ``description``, ``scope_types``, and ``permissions``. -* ``updated``: only the fields that changed. A name or description change stores the old and new - values. A permission change stores ``permissions_added`` and ``permissions_removed``. +* ``updated``: only the fields that changed. A description change stores the old and new values. A permission change stores ``permissions_added`` and ``permissions_removed``. 3. Link assignment changes to the role change =============================================