Skip to main content
Version: 4.32.x.x LTS

Event logging

nevisAuth features the nevisevents event system. Events contain data about the context at the moment when the event is raised. Event handling is enabled by setting the system property ch.nevis.events.config to the path of the nevisevents configuration file. You can find a template for such a configuration file in the nevisAuth instance directory, typically /var/opt/nevisauth/[instname]/conf/nevisevents.xml.

The nevisAuth engine emits events on the following occasions:

Event TypeDescription
authenticate-completedA completed authentication operation (the AUTH_DONE status has been reached).
stepup-completedA 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).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-completedA completed logout operation requested by the user (usually via logout URL).
session-terminatedA session that is killed out of the context of a user request. This can happen for various reasons (see Session end reasons].
<operation>-completedA completed operation (leading to the AUTH_DONE status).
<operation>-abortedAn aborted operation (which caused an AUTH_ERROR status).

Events are consumed by event handlers. nevisAuth comes with the pre-defined handler ch.nevis.events.handlers.LogHandler, which forwards the events represented in JSON format to nevisAuth's log back end. The log back end eventually writes the events into a log file.

A typical configuration of the event system looks as follows:

<?xml version="1.0"?>
<!DOCTYPE nevisevents SYSTEM "/var/opt/nevisauth/oidcrelyingparty/conf/nevisevents.dtd">

<nevisevents name="nevisauth-events-engine">
<engine name="events">
<handler name="nevisauth-events" class="ch.nevis.events.handlers.LogHandler">
<param name="traceGroup" value="nevis.events" />
<param name="eventFormat" value="${jsonReport}" />
</handler>

<rule handler="nevisauth-events">
<event class="ch.nevis.esauth.auth.engine.events.JsonReportEvent" source="local" />
</rule>
</engine>
</nevisevents>

The code sample in the above code block defines ch.nevis.events.handlers.LogHandler as an event handler. The event handler itself is configured via the <param> elements.

The following configuration parameters are valid for ch.nevis.events.handlers.LogHandler:

  • traceGroup: Indicates the log back end's trace group to which the events are forwarded. If not set, nevisevents fetches a logger for the class of the event.
  • eventFormat: Defines in which format the events are logged. The only valid value is "${jsonReport}".

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 anAuthEventdocument 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 in the.
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.

When logged, an event may typically look as follows:

{
"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.
terminated-by-clientA kill call was made from an external client (such as nevisProxy reaching a session time-out).
terminated-by-flowThe session was killed by AuthState logic (e.g., through response.setInvalidateSession()).
abortedThe authentication operation failed (that is, the AUTH_ERROR status was triggered by the configuration or a Java exception).
redirectedA user request resulted in an AUTH_REDIRECT status.
logoutA user-triggered logout has been completed.
stateless-domainThe domain configuration signals stateless authentication support.
stateless-requestThe client signals stateless authentication support.

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 4.3.5.1 Variable expressions and 4.3.5.2Java 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.