16.1.1.4. Authentication log endpoints

GET /authenticationlog/

Return a paginated, filtered page of authentication-log entries.

Requires the policy action authentication_log_read. An admin with that action set in the admin scope may read the log; if the policy is scoped to realms, resolvers and/or users, only entries matching that scope are returned. A user with the action set in the user scope may read only their own entries – those of their account, identified by resolver and user id rather than by their login name, so an entry that resolved to no account is not among them however it was addressed.

Each of resolvers, uids, realms, usernames, user_roles, event_types, reasons, source_ips, peer_ips, source_ip_sources, serials, transaction_ids, attempt_ids, client_labels, client_label_sources and endpoints may be passed as a query parameter to filter on it. A value may be a comma-separated list (e.g. event_types=MFA_FAIL,PIN_FAIL), matching entries that equal any of the values. A value may contain a * wildcard (e.g. serials=TOTP*) to match by prefix/pattern instead of exactly. Note, using wildcards filtering is always case-insensitive.

Query Parameters:
  • page – page number, 1-indexed (default 1).

  • page_size – entries per page (default 15).

  • sort_column – column to sort by (id, timestamp, event_type, resolver, uid, realm, username, source_ip, peer_ip, source_ip_source, client_label, client_label_source, endpoint, serial, transaction_id, attempt_id). An entry’s reasons are a list, so they are not sortable.

  • sort_order – asc or desc (default desc).

  • start_time – only entries at/after this ISO 8601 timestamp.

  • end_time – only entries at/before this ISO 8601 timestamp.

  • case_insensitive – if set, plain (non-wildcard) filter values match case-insensitively (wildcard values always match case-insensitively).

  • ca_action_types – only entries with a conditional-access outcome of one of these action types (e.g. LOCK_USER). Takes a list and a wildcard like the other filters, so ca_action_types=* means “conditional access acted on this request at all”.

  • ca_policy_names – only entries with an outcome recorded for one of these conditional-access policy names.

  • ca_dry_run – true for only entries with a dry-run outcome, false for only entries with an enforced one; omit it to get both. The three ca_* filters apply to the same outcome, so an entry matches when one of its outcomes satisfies all of them.

Each entry records how its client was determined as well as what it was determined to be. source_ip is the effective address - the one authorization and conditional access act on - while peer_ip is the TCP peer the request arrived from, source_ip_source names where the effective address was taken from (REMOTE_ADDR, REMOTE_ADDR_UNMAPPED when an OverrideAuthorizationClient is configured but this peer may not map any further, X_FORWARDED_FOR or CLIENT_PARAM), and ip_chain is the whole path that was considered, peer first, with the chosen hop marked "effective": true. The chain is recorded even when no override is configured and the header is therefore ignored. client_label_source says whether the label is the client_id the client chose (client_id) or its User-Agent (user_agent).

null in any of these means the entry predates the recording, and nothing may be inferred from it - in particular a null source_ip_source does not mean “direct connection”.

Status Codes:
  • 200 OK – paginated result in result.value with auth_logs, count, current, prev, next.

GET /authenticationlog/reasons

Return the list of all defined authentication-log reasons.

Requires the policy action authentication_log_read, like the log read endpoint. The list is the authoritative set of AuthEventReason values - why an event came out the way it did - exposed for the same reason the event types are: so the WebUI offers the vocabulary it can filter on instead of redefining it. It does not depend on the caller or on any logged data.

Status Codes:
  • 200 OK – result.value is a list of reason names, in definition order.

GET /authenticationlog/endpoints

Return the list of endpoints an authentication can arrive at.

Requires the policy action authentication_log_read, like the log read endpoint. The list is AUTHENTICATING_ENDPOINTS, the request paths that record an authentication-log row, so the WebUI offers the endpoints filter as a selection instead of a path typed by hand. It is not derived from the logged data: a path an admin can select but that nothing has hit yet still belongs in the list, and a filter may still name a value of its own (a wildcard such as /validate/*, or the path of a route that has since been renamed).

Status Codes:
  • 200 OK – result.value is a sorted list of request paths.

GET /authenticationlog/statistics

Return a summary of the authentication log over a time window, as counts of authentication attempts grouped by the event type that classifies each of them and bucketed over the window.

Requires the policy action authentication_log_read and is restricted to the same entries the log listing shows the caller, so an admin scoped to a realm counts only that realm’s attempts.

The rows sharing an attempt_id are one attempt and are counted once, classified by the event that ended them: a challenge-response login writes several rows but is a single successful attempt. event_type therefore selects attempts that ended that way, rather than every attempt that passed through such an event.

The attempts counted may be filtered on the classifying row by every filter the listing offers on an entry: resolvers, uids, realms, usernames, user_roles, event_types, reasons, source_ips, serials, transaction_ids, attempt_ids, client_labels and endpoints. Each is named in the plural because it takes a comma-separated list of values and matches an attempt equal to any of them, a value containing a * wildcard matching by pattern instead. The plural is the only name recognized: a query written in the singular, source_ip=10.0.0.1 rather than source_ips=, is no filter at all and the summary then covers every attempt in the window. The ca_* filters are not offered: they match the conditional-access outcomes of a request rather than the attempt itself.

Query Parameters:
  • start_time – start of the window, an ISO 8601 timestamp (required).

  • end_time – end of the window, an ISO 8601 timestamp (required). Both ends are inclusive.

  • bins – how many equal-width buckets to split the window into, between 1 and 100 (default 48). More than the maximum is rejected with a 400 naming the limit rather than quietly reduced, so a caller is never handed a coarser resolution than it asked for without being told. A value that is not a positive number at all falls back to the default, as page_size does on the listing.

  • case_insensitive – if set, plain (non-wildcard) filter values match case-insensitively.

Status Codes:
  • 200 OK – result.value holds window (start_time, end_time, total), bins (count and the starts of each bucket) and events, one entry per classification present in the window with its event_type, outcome, per-bucket counts and window total, most frequent first.

GET /authenticationlog/eventtypes

Return the list of all defined authentication-log event types with their outcome.

Requires the policy action authentication_log_read (in the admin or user scope, like the log read endpoint). The list is the authoritative set of AuthEventType values, each with its AuthEventOutcome (success / failure / pending), exposed so the WebUI does not have to redefine it. It does not depend on the caller or on any logged data.

Status Codes:
  • 200 OK – result.value is a list of {"name", "outcome"} objects, in definition order.