Skip to content

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) and AGENT_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

30 seconds, no sound. Read the audit status, send a test event and open the realm's Logging settings. Recorded on the current release.

Common tasks

  1. Search audit events — in your audit tool, filter by type, actor, realm, outcome or time range to investigate activity.
  2. Trace an authentication issue — find the user's authentication events (which carry the realm) to see successes and failures.
  3. Audit a sensitive action — confirm credential resets and impersonation are recorded against the responsible admin.
  4. Check your log pipeline — on the master console, Send test event writes a marked AUDIT_TEST event; search for its eventId in 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:

curl -s -b cookies.txt "$HELIX_URL/admin/audit/config"
{
  "enabled": true,
  "categories": ["AUTHN", "ADMIN"]
}

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).

curl -s -b cookies.txt "$HELIX_URL/admin/audit/status"

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.

See also