Events & audit¶
HelixIAM writes an audit event for every login, admin change and security-relevant action as one JSON line on standard output. It keeps no audit events in its own database: your collector delivers the lines to your audit tool (SIEM, ELK, Loki, Splunk), which stores and searches them.
What it is¶
Events fall broadly into:
- Authentication events — logins, logout, MFA challenges, failures. Every authentication event carries the realm it occurred in.
- Admin events — create/update/delete operations on realm objects (users, clients, roles, groups, etc.).
- Security events — sensitive actions such as credential resets and admin impersonation.
- Agent token events —
AGENT_TOKEN_ISSUED/AGENT_TOKEN_DENIED(an agent's own token) andAGENT_DELEGATION_TOKEN_ISSUED/AGENT_DELEGATION_TOKEN_DENIED(a token to act for a user), with the agent, client, acting-for subject, scope and audience, and the reason of a refusal. See Agents.
Audit lines on stdout¶
Each event is one JSON line on standard output (log_type audit, with realm, an eventId UUID, type, actor and outcome), written before the request returns. HelixIAM sends it nowhere else: a collector that you run reads stdout and delivers it to your audit tool. See Observability & health for the line format, collector examples and routing.
Know the limits
There is no second copy. Lines the collector loses (down longer than the node keeps container logs, or a pod deleted before its lines are read) are gone, so Fluent Bit filesystem buffering (as in the shipped example) and adequate container log rotation are required for production. The audit line is not atomic with the action: a crash between them can lose the record. A per-client sign-in rate-limit refusal (429) writes no audit event.
Note
Realm admins see their realm's audit events only through the operator's audit tool, for example a per-realm Kafka topic or a Loki label as in the shipped Fluent Bit examples. The operator has to give them access.
In the console¶
The Audit page (formerly Events) lives under the Compliance & security nav group. It shows the audit status (enabled, categories, log format) and a link to the realm's audit categories (Realm settings → Logging). A realm admin sees there that the realm's audit events are in the operator's audit tool. On the master console (master-realm admins) the page also has a Send test event button. The console has no event search.
Watch: Check the audit pipeline¶
Common tasks¶
- Search audit events — in your audit tool, filter by
type,actor,realm,outcomeor time range to investigate activity. - Trace an authentication issue — find the user's authentication events (which carry the realm) to see successes and failures.
- Audit a sensitive action — confirm credential resets and impersonation are recorded against the responsible admin.
- Check your log pipeline — on the master console, Send test event writes a marked
AUDIT_TESTevent; search for itseventIdin your audit tool. Realm settings → Logging chooses which audit categories a realm writes.
Tip
Pair the audit events with Sessions: events tell you what was done, sessions tell you who is currently signed in.
Warning
Retention and tamper-evidence of audit events are those of your audit tool; HelixIAM holds no audit data to retain.
Over the API¶
The audit settings are read from the audit-config and audit-status endpoints. There is no endpoint to read audit events: search them in your audit tool. The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.
Inspect emission config — GET /admin/audit/config¶
Master-realm admins only. The audit settings of the deployment are read-only here:
Audit lines always go to stdout (JSON, for your collector); there is nothing else to configure for delivery.
Audit status — GET /admin/audit/status¶
Master-realm admins only: whether audit is enabled (enabled), the audit categories (categories) and the log format in effect (logFormat).
Send a test event — POST /admin/audit/test-event¶
Master-realm admins only. Writes an AUDIT_TEST event to stdout, whatever the audit categories are, and returns its eventId to search for in your audit tool. Answers 409 when audit is turned off and 429 beyond 5 a minute per pod. HelixIAM cannot know whether your collector received the line.
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)
curl -s -b cookies.txt -X POST -H "X-XSRF-TOKEN: $CSRF" "$HELIX_URL/admin/audit/test-event"
Per-realm audit categories — GET · PUT /admin/realms/{realm}/logging¶
A realm admin can add audit categories for the realm; only a master-realm admin can reduce them or set temporary DEBUG logging (1 to 60 minutes). See Observability & health.
| Method & path | Purpose |
|---|---|
GET /admin/audit/config |
Inspect the audit settings (enabled, categories) |
GET /admin/audit/status |
Audit status: enabled, categories, log format (master-realm admin) |
POST /admin/audit/test-event |
Write a marked test event (master-realm admin) |
GET · PUT /admin/realms/{realm}/logging |
Per-realm audit categories and temporary DEBUG |
The audit events in your audit tool are also the primary evidence source for your compliance program.