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_sourcesandendpointsmay 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 –
ascordesc(defaultdesc).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, soca_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 –
truefor only entries with a dry-run outcome,falsefor only entries with an enforced one; omit it to get both. The threeca_*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_ipis the effective address - the one authorization and conditional access act on - whilepeer_ipis the TCP peer the request arrived from,source_ip_sourcenames where the effective address was taken from (REMOTE_ADDR,REMOTE_ADDR_UNMAPPEDwhen anOverrideAuthorizationClientis configured but this peer may not map any further,X_FORWARDED_FORorCLIENT_PARAM), andip_chainis 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_sourcesays whether the label is theclient_idthe client chose (client_id) or its User-Agent (user_agent).nullin any of these means the entry predates the recording, and nothing may be inferred from it - in particular a nullsource_ip_sourcedoes not mean “direct connection”.- Status Codes:
200 OK – paginated result in
result.valuewithauth_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
AuthEventReasonvalues - 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.valueis 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 theendpointsfilter 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.valueis 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_idare 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_typetherefore 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_labelsandendpoints. 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.1rather thansource_ips=, is no filter at all and the summary then covers every attempt in the window. Theca_*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_sizedoes on the listing.case_insensitive – if set, plain (non-wildcard) filter values match case-insensitively.
- Status Codes:
200 OK –
result.valueholdswindow(start_time,end_time,total),bins(countand thestartsof each bucket) andevents, one entry per classification present in the window with itsevent_type,outcome, per-bucketcountsand windowtotal, 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
AuthEventTypevalues, each with itsAuthEventOutcome(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.valueis a list of{"name", "outcome"}objects, in definition order.