Skip to main content
Version: 9.2605.x RR

Event logging

nevisAuth features event logging in JSON format. Events contain data about the context at the moment when the event is raised. Event handling is enabled by setting the ch.nevis.esauth.events to INFO in the logging.yml. To disable the event logging, set the ch.nevis.esauth.events to FATAL.

The nevisAuth engine emits events on the following occasions:

  • authenticate-completed

    A completed authentication operation (the AUTH_DONE status has been reached).

  • stepup-completed

    A completed step-up operation (the AUTH_DONE status has been reached). Traditionally, a successfully completed step-up operation leads to an increased authentication level (authLevel).

    info

    A step-up may also be used for re-authentication, e.g., to trigger a password change operation. In this case, the authentication level is not increased.

  • logout-completed

    A completed logout operation requested by the user (usually via logout URL).

  • session-terminated

    A session that is killed out of the context of a user request. This can happen for various reasons (see Session end reasons).

  • bcl-logout-token-delivered

    nevisAuth delivered an OpenID Connect back-channel logout token to a client. The event contains the fields sid, clientId, issuerId, sub, and sidClaim.

  • bcl-logout-token-delivery-failed

    nevisAuth did not deliver a logout token. For network errors and HTTP 5xx responses, nevisAuth sends this event after the last retry. The event contains the fields of bcl-logout-token-delivered, plus failureReason and failureDetail. The values of failureReason are delivery-exhausted, rp-rejected-permanent, minting-exhausted, issuer-unregistered, and unexpected-error.

  • bcl-no-registered-clients

    A session with back-channel logout ended, but nevisAuth recorded no client for it. The event contains the field sid.

  • <operation>-completed

    A completed operation (leading to the AUTH_DONE status).

  • <operation>-aborted

    An aborted operation (which caused an AUTH_ERROR status).

Where the logs are written can be configured in the logging.yml where standard log4j2 configuration applies.

Event content​

A logged event contains the following data as JSON fields:

FieldDescription
logVersionThe log version value is increased when the log format is changed in a way that must be detectable.
timestampThe value is of date type and includes time zone information.
logTypeThe log type. The following log types are available: "event": Stored as an AuthEvent document type. "sessionEvent": Stored as AuthEvent and AuthSession document type.
eventTypeThe type of event. For all possible values, see the list of event types in Table 19.
trIDThe transaction ID (usually the same as the ProxyRequest.trID).
sessionIDThe nevisAuth session ID. This ID can change when a session becomes authenticated.
conversationIDThe nevisAuth conversation ID. The conversation in this case is a sequence of requests and responses that forms one operation, e.g., an authentication or a step-up operation that renders forms.
clientInformation about the client talking to the nevisAuth server (usually nevisProxy).
client.sessionIDThe nevisProxy session ID (also known as clID in other places).Note that there are spaces inserted in the example value for readability.
client.clientIDThe identification ID of the client (also known as actorId in other places).
client.entryPointThe client entry point is the human-readable name provided by the client to identify itself.In nevisProxy configurations that are generated by nevisAdmin, the entryPoint value refers to the nevisProxy instance's host name.
client.sslCipherThe SSL connection cipher.
client.sslClientDNThe distinguished name (DN), as presented in the client certificate.
client.clientIPThe IP of the client host.
agentThe end user's client. The data is provided by the intermediate client above (usually nevisProxy).
agent.userAgentThe userAgent string in the HTTP header (the same as ProxyRequest.userAgent).
agent.agentIPThe IP of the end user's client if available (should be the same as the ProxyRequest.agentIP).
agent.sslProtocolThe SSL protocol (the same as ProxyRequest.sslProtocol).
agent.sslCipherThe SSL connection cipher (the same as ProxyRequest.sslCipher).
agent.resPathThe resource requested by the originally intercepted request (without query parameters).
agent.resQueryThe query parameters of the originally intercepted request.
agent.reqPathThe URL of the current agent request that caused the nevisAuth back end to be invoked (the same as ProxyRequest.reqPath).
agent.reqQueryThe query string part of the request (without "?", the same as ProxyRequest.reqQuery).
hostNameThe host name of the internet protocol (IP) interface that received the request.
portThe port number (long type) of the internet protocol (IP) interface that received the request.
sessionStartTimestampThe start time (date type) of the current session.
sessionEndTimestampThe end time (date type) of the current session.
sessionEndReasonThe reason why the session was finished. For all possible values, see the list of session end reasons.
loginIDThis field contains the intended (but unverified) user identity (name) that is usually visible to the end user. It is set by an AuthState before successful authentication.
userIDThe principal name as provided by the authentication back end. It is set by an AuthState during the authentication process.This user ID is used to pass on the identity, e.g., via a SecToken.
authLevelThe authentication strength of the session after a successful login or step-up (e.g., if the user was authenticated by a simple password only, the authentication strength is set to weak).For possible values, see the authLevel attribute of the AuthState and ResultCond elements in your nevisAuth configuration.
rolesThe roles received by the user (based on role information from the authentication back end).
realmThe name of the SSO authentication domain.For possible names, see the Domain element in your nevisAuth configuration.
languageThe natural language (as ISO code) in which nevisAuth GUIs are rendered. The value is selected from configured languages based on the user agent's language header
eventTrailThe audit events that can be generated by AuthStates and are collected during the session.
customCollection of custom data contained in the event.
Example of logged event
{
"logVersion":"1",
"timestamp":"2017-08-07T20:10:05.083+0200",
"logType":"sessionEvent",
"eventType":"authenticate-completed",
"trID":"c0a80410-5b21-abbcd-15dbde3bbf3-0000005f",
"sessionID":"Wp7kr6_r6HbCnjej5qXyW5ccnPaxAIz630U0zlNiTxA",
"conversationID":"324143368799",
"client": {
"sessionID":"5a8f000abbcdQU6vD11PByJOzmInKMyAeC5FYB1JYtOwzdnA38DgIBAQa2",
"clientID":"23322",
"entryPoint":"nevisauth-int-test1.zh.adnovum.ch",
"sslCipher":"TLS_DHE_RSA_WITH_AES_256_CBC_SHA",
"clientIP":"10.0.205.187"
},
"agent":{
"userAgent":"Mozilla\/5.0 (X11; Linux i686; rv:24.0) Gecko\/20100101 Firefox\/24.0",
"agentIP":"192.168.4.16",
"sslProtocol":"TLSv1",
"sslCipher":"ECDHE-RSA-RC4-SHA",
"resPath":"https:\/\/nevisauth-test.adnovum.ch\/nevisauth\/rp\/",
"resQuery":". . .",
"reqPath":"https:\/\/nevisauth-test.adnovum.ch\/nevisauth\/rp\/",
"reqQuery":". . ."
},
"hostName":"nevisauth-test.adnovum.ch",
"port":8991,
"sessionStartTimestamp":"2017-08-07T20:10:05.061+0200",
"userID":"1547247750434",
"authLevel":"auth.test",
"roles":["auth.test"],
"realm":"OIDC",
"language":"en",
"eventTrail":[ ],
"custom":{ }
}

Session end reasons​

The following values can occur in the sessionEndReason field when a session ends:

ReasonDescription
expiredThe SessionReaper has removed a timed-out session.
proxy killAn external client ended the session, for example nevisProxy after a session timeout.
terminated-by-flowAn AuthState operation marked the session for termination; this value appears on that operation event, not on the final session-end event.
abortedThe authentication operation failed (that is, the AUTH_ERROR status was triggered by the configuration or a Java exception).
logoutA user-triggered logout has been completed, or an AuthState ended the session with the end reason LOGOUT.
management deleteThe session was deleted through the session management API.
rp-initiated logoutThe session was ended through OpenID Connect RP-initiated logout.
bcl receivedThe session was ended by an OpenID Connect back-channel logout from an external OpenID Provider.
throttleThe session was evicted by the concurrent session limit of the ThrottleSessionsState.
stateless-domainThe domain configuration signals stateless authentication support.
stateless-requestThe client signals stateless authentication support.

Access log​

:::Preview feature

The access log is considered a preview feature, the behaviour and logging format may change in future versions.

:::

In addition to the event types above, nevisAuth emits a lightweight per-request access log entry through its own JSON event logger. One JSON line is emitted per request that reaches nevisAuth, for the AuthenticationManagerOperations SOAP service, the WS-Trust security token service and the REST interface alike. Its purpose is to reliably record the real end-user IP address together with the trace ID, so that authentication activity (for example account creation) can be correlated with the originating IP address, for example for fraud detection and threat intelligence.

The entry is emitted by a dedicated servlet filter mapped first in the filter chain, ahead of every other filter, so it is written for every request nevisAuth's web layer receives, independent of whether a later filter or the authentication engine ever processes the request. The filter never modifies the request itself: getRemoteAddr() and getRemoteHost() keep returning the raw, unmodified TCP peer address for every other consumer downstream (session and audit logging, the SAML SubjectConfirmationData address check, and so on). The resolved client IP is reported only in the access-log entry, alongside that same raw address, so the two can be correlated without either one overwriting the other.

The access log uses its own logger category, ch.nevis.esauth.events.access, which is independent from the general ch.nevis.esauth.events category. It is enabled by default (level INFO) and can be disabled by setting its level to FATAL in the logging.yml. As for any other logger category, where the resulting entries are written is determined by the category's AppenderRef, which can be configured with standard log4j2 configuration in the logging.yml:

# Per-request access log (client IP + trace ID). Enabled by default (INFO).
- name: ch.nevis.esauth.events.access
level: INFO
additivity: false
AppenderRef:
- ref: EVENTS

A representative access-log line looks as follows:

{"logVersion":"1","timestamp":"2026-06-22T09:05:04.689+0200","logType":"accessLog","trID":"b481edcd6da2c505cc4fa7303016e1a5","clientIP":"84.0.160.69","remoteAddress":"10.0.205.187","reqPath":"/nevisauth/auth/"}

When client IP resolution fails, the entry additionally carries an error field, and clientIP falls back to the same value as remoteAddress:

{"logVersion":"1","timestamp":"2026-06-22T09:05:04.689+0200","logType":"accessLog","trID":"b481edcd6da2c505cc4fa7303016e1a5","clientIP":"10.0.205.187","remoteAddress":"10.0.205.187","reqPath":"/nevisauth/.well-known/jwks.json","error":"TRUSTED_CLIENT_IP_HEADER_NOT_FOUND"}

Access log content​

FieldDescription
logVersionThe log format version. Increased when the format changes in a way that must be detectable.
timestampThe date and time of the request, including time zone information.
logTypeAlways accessLog for these entries, so they can be distinguished from the other JSON event entries.
trIDThe trace ID. It is the same value as trace_id in the general application log and trID in the other JSON event entries.
clientIPThe resolved real end-user IP address, see Client IP resolution below. When resolution fails, this field falls back to the same value as remoteAddress, and the failure reason is reported in error instead.
remoteAddressThe raw TCP peer address, unaffected by client IP resolution, exactly as request.getRemoteAddr() returns it to every other consumer.
reqPathThe request path, for example /nevisauth/auth/. Scheme, host and query string are never part of this value.
errorPresent only when client IP resolution failed, see Client IP resolution below for the possible values. Omitted when resolution succeeded.

Fields with no value are omitted from the line.

Because trID is shared across logs, access-log entries can be joined with the nevisIDM audit log (for example the USER_CREATE event) to attribute an account-creation event to the originating client IP.

Client IP resolution​

Two independent mechanisms decide which header is trusted, chosen by the request's URL path:

  • The AuthenticationManagerOperations SOAP service (/services/AuthenticationService) always trusts a hardcoded CLIENT-IP header. nevisProxy sets this header, carrying its own already-resolved client address, on every AuthenticationManagerOperations call it proxies from an inbound request. This mechanism is not configurable.

    Not every AuthenticationManagerOperations call originates from an inbound request. For example, nevisProxy's own session-cleanup calls have no such request to source an address from, so they reach nevisAuth without this header. This is expected, so a missing header on this path alone is not reported as an error: clientIP falls back silently to remoteAddress. A CLIENT-IP header that is present but carries more than one value is still a genuine anomaly and is reported as an error, same as for every other request.

  • Every other request (the WS-Trust security token service and REST/Jersey) trusts the header or headers named by the system property ch.nevis.esauth.trustedClientIpHeader. This property is not set by default. Its value is a comma-separated list of header names, tried in order; the first header present on the request with exactly one syntactically valid IP address wins.

    A header that carries more than one value, either as a comma-separated chain packed into a single value (for example a raw, unmodified X-Forwarded-For) or as multiple instances of the same header name, is rejected rather than picked from: resolving such a chain to the real client IP must happen upstream, at the trusted ingress, before the request reaches nevisAuth. IPv6 literals in bracketed URI notation (for example [2001:db8::1]) and with a zone ID suffix (for example fe80::1%eth0) are accepted.

When resolution fails, clientIP falls back to the same value as remoteAddress, and the reason is reported in error:

ValueMeaning
TRUSTED_CLIENT_IP_HEADER_NOT_CONFIGUREDch.nevis.esauth.trustedClientIpHeader is not set. Does not apply to AuthenticationManagerOperations, whose header is hardcoded and always configured.
TRUSTED_CLIENT_IP_HEADER_NOT_FOUNDA trusted header was expected but is absent, blank, or not a valid IP literal on this request. For AuthenticationManagerOperations specifically, a missing header is not reported as an error, see above.
TRUSTED_CLIENT_IP_HEADER_NOT_UNIQUEA trusted header is present but carries more than one value.

For diagnostics beyond what the access-log entry itself carries, nevisAuth logs the filter's own resolution decisions to a dedicated logger category, ClientIpAccessLog. This category is independent from ch.nevis.esauth.events.access, which only ever carries the access-log JSON entry. It defaults to WARN. Set it to DEBUG in logging.yml to trace, for every request, which header was checked, whether it was present, missing or ambiguous, and which one, if any, resolved the client IP. This is particularly useful for the non-AuthenticationManagerOperations requests (WS-Trust security token service, REST/Jersey), where the trusted header list is admin-configured and therefore more likely to need troubleshooting than the hardcoded AuthenticationManagerOperations mechanism.

# ClientIpAccessLogFilter's own diagnostic/error logging, distinct from the access-log
# entry itself (ch.nevis.esauth.events.access above). Set to DEBUG to trace every
# client-IP resolution decision per request.
- name: ClientIpAccessLog
level: WARN

Example configuration:

-Dch.nevis.esauth.trustedClientIpHeader=CF-Connecting-IP

Configure only a header that is guaranteed to be set, or overwritten, by a trusted proxy or load balancer in front of nevisAuth, for example a CDN header such as CF-Connecting-IP that the CDN itself rejects on inbound requests it did not set. Several header names can be listed, comma-separated, so a more specific header is preferred when present and a fallback is used otherwise.

Trust contract

This filter validates only that a trusted header carries a syntactically valid IP literal. It does not verify that the immediate TCP peer is actually the trusted ingress, for example nevisProxy. That check belongs to the network layer and must be in place for the resolved client IP to be trustworthy:

  • For the security token service and REST, the ingress must be restricted to the real load balancer or CDN IP ranges, and ch.nevis.esauth.trustedClientIpHeader must name only the header or headers that ingress adds or overwrites, never one a client could set directly.
  • For AuthenticationManagerOperations, whose CLIENT-IP header is trusted unconditionally with no property to disable it, the SOAP endpoint must only ever be reachable through nevisProxy, never exposed directly to a less trusted network.

If either precondition does not hold, a client can spoof clientIP simply by sending the trusted header itself. This risk is scoped entirely to this log field: getRemoteAddr()/getRemoteHost() and every other consumer downstream are never affected.

Example: nevisProxy as the trusted ingress​

For the WS-Trust security token service and REST/Jersey calls, some trusted component in front of nevisAuth must both resolve and forward the real client IP as the header named by ch.nevis.esauth.trustedClientIpHeader. nevisProxy is not required for this: any other trusted reverse proxy, API gateway or ingress can be configured the same way, as long as it resolves the real client IP and overwrites the header before forwarding the request, and its trusted-peer configuration is scoped correctly (see the trust contract above). If nevisProxy is already deployed in front of nevisAuth, it is a viable, ready-made option for this, combining two independent nevisProxy building blocks. AuthenticationManagerOperations needs no such configuration on any ingress: nevisProxy already sends its own hardcoded CLIENT-IP header for that service, see above.

  1. Apache's mod_remoteip, loaded through nevisProxy's ApacheConfigFilter, resolves the real client IP from the incoming forwarded header into REMOTE_ADDR, restricted to the actual load balancer or CDN IP ranges in front of nevisProxy. For the full configuration reference, see Optional Apache modules and CountryIpFilter in the nevisProxy reference guide.
  2. A HeaderDelegationFilter, mapped to the connector servlet that proxies the STS/REST calls to nevisAuth, for example an HttpsConnectorServlet, forwards that resolved REMOTE_ADDR onward as the header nevisAuth is configured to trust. For the full configuration reference, see HeaderDelegationFilter in the nevisProxy reference guide.

At a high level, this looks as follows in nevisProxy's web.xml (see the linked pages for the actual parameter values):

<filter>
<filter-name>RemoteIpModuleFilter</filter-name>
<filter-class>ch:nevis:navajo:apglue:httpd_<version>_x:servlet:ApacheConfigFilter</filter-class>
<init-param>
<param-name>ServerConfig</param-name>
<param-value>
LoadModule remoteip_module <path-to-module>
RemoteIPHeader <forwarded-header-name>
RemoteIPTrustedProxy <trusted-proxy-ip-range>
</param-value>
</init-param>
</filter>

<filter>
<filter-name>ClientIpDelegationFilter</filter-name>
<filter-class>ch::nevis::isiweb4::filter::delegation::HeaderDelegationFilter</filter-class>
<init-param>
<param-name>DelegateToBackend</param-name>
<param-value><header-name>:ENV:REMOTE_ADDR</param-value>
</init-param>
</filter>

<!-- Maps the delegation filter above to the connector servlet that proxies STS/REST calls
to nevisAuth, for example the HttpsConnectorServlet-based connector configured for
the WS-Trust security token service and REST endpoints. -->
<filter-mapping>
<filter-name>ClientIpDelegationFilter</filter-name>
<servlet-name>NevisAuthHttpConnector</servlet-name>
</filter-mapping>

The forwarded header name used in RemoteIPHeader and the <header-name> delegated in step 2 must match the header (or one of the headers) named by ch.nevis.esauth.trustedClientIpHeader on the nevisAuth side, and the servlet-name in the filter-mapping must match the connector servlet that proxies STS/REST calls to nevisAuth, NevisAuthHttpConnector above being only an example name.

Known limitations​

Because the filter is mapped first in the filter chain, an access-log entry is written for effectively every request handled by nevisAuth's web layer, including ones later rejected by a later filter, by the REST or SOAP framework, or by the authentication engine itself. Unlike the events described earlier on this page, no session or authentication context needs to exist for the entry to be logged.

A request that never reaches nevisAuth's web layer at all, for example one rejected by the network layer or an upstream reverse proxy before it is forwarded, produces no access-log entry.

Customize event content​

Standard nevisAuth events can be enriched with context-specific information. This information is added to the set of custom information within every event. When logged, this information is nested in the custom { } block of the events.

Custom properties to be added to the custom data of every event can be configured using the <EventData> tag in the nevisAuth configuration:

<EventsData>
<CustomField name="profileId" value="${!empty sess['ch.adnovum.nevisidm.profileId']?sess['ch.adnovum.nevisidm.profileId']:notes['userInfos.profile.profileId']}" format="JSON" />
<CustomField name="unitId" value="${sess:ch.nevis.idm.User.unit.extId}" format="JSON" />
<CustomField name="unitDisplayName" value="${sess:ch.nevis.idm.User.unit.displayName}" />
<CustomField name="unitLocalizedHname" value="${sess:ch.nevis.idm.User.unit.localizedHname}" />
<CustomField name="unitHierarchy" value="[${StringUtils.strip(sess['ch.nevis.idm.User.unit.hname'].replace('/',','),',')}]" format="JSON" />
</EventsData>

Custom fields to be contained in every event must be defined by declaring a name, a value and optionally a format. This can be done by setting the following attributes in a <CustomField> tag:

  • name

    Name of the custom field.

  • value

    Value of the custom field. Besides common strings, this attribute accepts variable expressions and Java EL Expression. See Variable expressions and Java EL expressions for details.

  • format

    Format of the custom field. If set to "JSON", the value of the field is considered and treated as a JSON object instead of a plain string. Values other than "JSON" are ignored.