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

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

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