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. 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 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. ADR 0035 stores custom roles in the same tables with no source links, so nothing records who created a custom role or when.
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,
or one per affected role when a deployment drops grants from several roles.
Action |
Operation |
|---|---|
Create, including a copy |
|
Edit the description or permissions |
|
Remove |
|
A deployment drops grants for removed permissions (ADR 0035) |
|
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.
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#
The changes field is JSON:
createdanddeleted: the full role:display_name,description,scope_types, andpermissions.updated: only the fields that changed. A description change stores the old and new values. A permission change storespermissions_addedandpermissions_removed.
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 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.
4. Events#
openedx-events gains ROLE_DEFINITION_CREATED, ROLE_DEFINITION_UPDATED,
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.
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
RoleDefinitionAuditand therole_change_idfield onRoleAssignmentAudit.openedx-events needs a release with the new events and the
role_change_idfield before this ships. Adding a field to the assignment event data is backward-compatible (ADR 0012).The assignments affected by removing a role can be found by filtering
RoleAssignmentAuditbyrole_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.