Authentication Audit Logging Pipeline

Overview#

The Authentication Audit Logging Pipeline provides dual-write logging of all authentication events to both the document store and PostgreSQL, ensuring a consistent, queryable, and tamper-evident record of login activity across the platform. Every authentication event -- successful logins, failed login attempts, account lockouts, and lockout resets -- is recorded with structured metadata and written to both persistence layers in the same operation.

The dual-write approach eliminates the risk of stale or divergent authentication state between the document store and PostgreSQL, which previously caused lockout fields to fall out of sync when only one store was updated.

Key Features#

• Dual-Write Consistency - Authentication events are written to both the document store and PostgreSQL in every operation. Lockout state fields (failed login attempts, account locked until) are mirrored to PostgreSQL after every update, ensuring structured queries against PostgreSQL return current lockout information.

• Structured Auth Log Records - Each log entry captures event type, user identifier, tenant identifier, IP address, user agent, timestamp, and extensible metadata. Event types include login_failed, account_locked, login_success, and lockout_reset.

• Account Lockout Mirroring - When a failed login triggers an account lockout, the lockout state is persisted to PostgreSQL in the same operation. When login attempts are reset (after successful authentication or administrative action), the cleared state is mirrored immediately.

• Cross-Path Coverage - Both the standard web authentication path and the mobile authentication path generate identical auth log records, ensuring consistent audit coverage regardless of how the user authenticates.

• Organisation-Scoped Queries - All auth log queries are scoped by tenant and organisation, preventing cross-tenant visibility into authentication events and maintaining data sovereignty compliance.

• Upsert Semantics - Auth log persistence uses upsert (ON CONFLICT UPDATE) semantics on the log identifier, preventing duplicate entries from retry logic or transient failures.

Use Cases#

• Security Incident Investigation - Query the auth_logs table for all failed login attempts against a specific user or from a specific IP address to identify brute-force attacks, credential stuffing, or compromised accounts.
• Compliance Reporting - Generate audit reports showing all authentication events for a tenant over a given period, with structured fields suitable for SOC 2, ISO 27001, and EDF compliance evidence.
• Lockout Diagnostics - Investigate account lockout events by tracing the sequence of failed login attempts that triggered the lockout, including IP addresses and user agents for each attempt.
• Operational Monitoring - Monitor authentication event volumes and failure rates across the platform to detect anomalous patterns that may indicate systemic issues or attack campaigns.

Integration#

The auth logging pipeline feeds into the platform audit trail for unified event visibility, the security monitoring dashboard for real-time authentication metrics, and the compliance reporting system for regulatory evidence. All auth log entries are accessible through the admin interface and the platform API.

Last Reviewed: 2026-04-02