# Overview.Admin

## What it does

Login Audit records successful logins, failed attempts, logouts, other-device logouts, device details, and recent activity. It can flag suspicious patterns, notify the affected user and an admin notification group, and expose a read-only security summary on user records.

## Setup requirements

Run the package and settings migrations, then keep Laravel's scheduler running. The package schedules `authentication-log:purge` daily, without overlapping and on one server. A successful run stores **Last purged at** in Login Audit settings; check that value and Diagnostics rather than assuming retention is active.

Keep a queue worker running when login notifications are enabled. The affected user's new-device, failed-login, and suspicious-activity notifications implement queued delivery through the channels defined by that user model. Admin alerts are separate persistent Filament broadcast/database notifications. Configure recipients in the `login_audit_security_alerts` admin notification group; its default recipients are global administrators and the configured super-admin role.

Set a stable `CAPELL_LOGIN_AUDIT_HASH_SECRET` before collecting data. It falls back to `APP_KEY`; changing that secret later changes IP and user-agent fingerprints, so older records will no longer match new activity by hash.

## Configure collection and alerts

Open **Login Audit** under package settings. Important controls are:

- **Show login audits** controls whether the admin surface is shown; it does not disable authentication-event capture.
- **Track user IP addresses** stores or omits the keyed IP fingerprint. Plaintext IP addresses are removed, but user agent, device name/ID, timestamps, status, suspicious reason, and optional location remain.
- **Track admin activity** updates the last-activity time for matching sessions. Disabling it does not stop login, failure, or logout records.
- **Retention days** controls the daily vendor purge; new settings default to 90 days and are clamped to at least one day.
- Suspicious detection can flag repeated failures, a success after recent failures from the same device, rapid country changes when location data exists, and optionally logins outside the configured usual hours. The admin form exposes the failed-attempt threshold/window and the unusual-time toggle; the remaining windows/hours come from deployment config.

With a failed-attempt threshold of **5** and a window of **60 minutes**, attempts one to four remain ordinary failed records. The exact fifth record is processed after its database transaction commits, is marked suspicious, and produces one configured suspicious-login admin alert. Processing is keyed to that created record rather than a later row for the same account.

Enabling a new-device, failed-login, or suspicious-login alert updates both the affected-user notification and the admin alert of that type. Geo-location lookup is off by default and is used only when the host supplies the optional geo-IP integration.

## Review and export access

Go to **Users > Access Logs** to review the actor, success state, IP fingerprint, time, and optional user-agent, device, trusted, activity, logout, cleared, and location columns. Filters cover successful logins, date range, user-cleared entries, and trusted state. These fields report recorded state; this package's table does not provide an action to trust a device, revoke a session, or force a logout.

For an investigation, follow the alert to detection evidence, filter Access Logs to the matching status and time range, locate the notified record ID, and compare the surrounding account, device, fingerprint, and location history. Confirm the activity with the account owner and record any response in your organisation's incident system; Login Audit provides the evidence trail, not case management.

When the user-resource bridge is enabled in both Admin and Login Audit settings, a user's edit page shows recent login/failure/device/session counts and a read-only authentication history. The **active sessions** number means successful rows without a logout timestamp; it is not proof that the underlying session is still usable.

**Export CSV** streams every matching record, or the selected user's records from their relation manager. It includes actor IDs/name, IP fingerprint, full user agent, device/trust state, timestamps, cleared state, and suspicious reason. Formula-like cells are neutralised, but the file remains sensitive and is not site-filtered.

## Access, privacy, and retention

Access Logs require a global administrator and `View:LoginAudit` (or its view-any equivalent). Site-assigned administrators cannot use this resource, because authentication history spans the installation rather than a site.

The table is read-only through the admin, but it contains account identifiers, browser/device data, behavioural timestamps, optional location, and security findings in plaintext. IP and user-agent fingerprints use keyed HMACs rather than reversible encryption. Limit exports and notification recipients, and include queued mail, notification tables, logs, and backups in the retention review.

When Privacy Center is installed, Login Audit contributes a subject export that omits internal IDs and fingerprints, and an eraser that deletes all audit rows for that subject. The daily retention task deletes old audit rows; it does not remove exported CSV files, delivered notifications, or backups.