The starter includes an audit logging system that tracks user actions and data changes throughout your application, providing a historical record for compliance, security investigations, and debugging.
Compliance & Regulations
Many Northwestern applications handle sensitive data subject to regulations requiring audit trails:
Security & Forensics
Audit logs help detect and investigate security incidents:
Debugging & Troubleshooting
Audit trails assist with diagnosing issues:
Accountability & Transparency
Complete audit trails provide:
All models extending BaseModel log the following Eloquent events with before/after state:
Each audit log entry includes:
The system also logs custom events for critical operations:
Role Assignment & Removal
When roles are assigned to or removed from users:
Permission Syncing
When a role’s permissions are modified:
Impersonation Sessions
When an administrator starts impersonating a user, LogImpersonationAccess (listening for TakeImpersonation) writes an ImpersonationLog to the user_impersonation_logs table with:
Nothing records when an impersonation ends. Audit entries for changes made while impersonating carry the administrator’s ID in impersonator_user_id.
API Credentials
OAuth clients and tokens have UUID or string keys, which the audits table can’t store, so their changes are recorded as custom events on a person instead:
| Event | Recorded on | When |
|---|---|---|
service_client_created, service_client_revoked, service_client_ip_restrictions_updated | The API user that owns the client | A service client is created, rotated, restricted or revoked |
application_registered, application_updated, application_secret_regenerated, application_revoked | The administrator who acted | An administrator manages an application |
mcp_client_revoked | The administrator who acted | An administrator revokes an MCP client |
personal_access_token_revoked | The token’s owner | An administrator revokes someone else’s token |
application_disconnected | The person | An administrator disconnects an application for someone |
None of them records a secret. Updates record the values before and after; revoking an application records how many connections it removed.
Audit entries are kept forever by default. Set AUDIT_RETENTION_DAYS to delete older entries; the scheduler’s daily model:prune removes them. Impersonation logs work the same way with IMPERSONATION_LOG_RETENTION_DAYS. Check your record-keeping requirements before setting either. See Data Retention.
You can exclude fields from audit logs at the model level:
// Within an Eloquent model extending BaseModel
protected array $auditExclude = [ 'password', 'remember_token',];Security
Prevent sensitive data from being stored in audit logs:
Volume Control
Exclude fields that change too frequently:
Relevance
Skip technical fields not meaningful for audits:
Storage Efficiency
Reduce audit table size and improve performance:
For actions that don’t fit standard CRUD operations, log custom audit events. Each one is a case of App\Domains\Core\Enums\AuditEvent, which also says how it’s shown: its label, icon and color in the audit tables, the record timeline and exports, and its place in the Event filter. Add a case for a new event:
case ReportExported = 'report_exported';A model with the RecordsAuditEvents trait, as User and Role have, records one in a line:
$user->recordAuditEvent(AuditEvent::ReportExported, new: ['report' => $report->name]);The audit’s user is whoever is signed in. tags are stored with the audit, and each context entry is added as a key: value tag, as AuditsRoles does with the modification origin and a reason. An event with nothing before or after isn’t recorded.
By default, Laravel Auditing disables audit logging for console commands (the audit.console config is false). Seeders that create or update Auditable models, such as RoleSeeder and PermissionSeeder, would not produce audit entries by default.
For production seeders that manage security-relevant data (roles, permissions, stakeholder assignments), this creates a gap in the audit trail. The AuditsSeederChanges trait solves this by registering the AuditableObserver directly on specified models.
Add the trait to your seeder and wrap the seeding logic in withAuditing():
use Northwestern\SysDev\Chassis\Seeding\Concerns\AuditsSeederChanges;
class RoleSeeder extends Seeder implements IdempotentSeederInterface{ use AuditsSeederChanges;
public function run(): void { $this->withAuditing([Role::class], function () { // Role creation and permission syncing logic... }); }}| Seeder | Audited Model | What gets audited |
|---|---|---|
RoleSeeder | Role | Role creation, attribute updates |
PermissionSeeder | Permission | Permission creation, metadata updates |
The StakeholderSeeder uses assignRoleWithAudit() instead, which fires custom audit events that bypass the console check entirely.