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:

Field	Description
logVersion	The log version value is increased when the log format is changed in a way that must be detectable.
timestamp	The value is of date type and includes time zone information.
logType	The log type. The following log types are available: "event": Stored as an AuthEvent document type. "sessionEvent": Stored as AuthEvent and AuthSession document type.
eventType	The type of event. For all possible values, see the list of event types in Table 19.
trID	The transaction ID (usually the same as the ProxyRequest.trID).
sessionID	The nevisAuth session ID. This ID can change when a session becomes authenticated.
conversationID	The 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.
client	Information about the client talking to the nevisAuth server (usually nevisProxy).
client.sessionID	The nevisProxy session ID (also known as clID in other places).Note that there are spaces inserted in the example value for readability.
client.clientID	The identification ID of the client (also known as actorId in other places).
client.entryPoint	The 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.sslCipher	The SSL connection cipher.
client.sslClientDN	The distinguished name (DN), as presented in the client certificate.
client.clientIP	The IP of the client host.
agent	The end user's client. The data is provided by the intermediate client above (usually nevisProxy).
agent.userAgent	The userAgent string in the HTTP header (the same as ProxyRequest.userAgent).
agent.agentIP	The IP of the end user's client if available (should be the same as the ProxyRequest.agentIP).
agent.sslProtocol	The SSL protocol (the same as ProxyRequest.sslProtocol).
agent.sslCipher	The SSL connection cipher (the same as ProxyRequest.sslCipher).
agent.resPath	The resource requested by the originally intercepted request (without query parameters).
agent.resQuery	The query parameters of the originally intercepted request.
agent.reqPath	The URL of the current agent request that caused the nevisAuth back end to be invoked (the same as ProxyRequest.reqPath).
agent.reqQuery	The query string part of the request (without "?", the same as ProxyRequest.reqQuery).
hostName	The host name of the internet protocol (IP) interface that received the request.
port	The port number (long type) of the internet protocol (IP) interface that received the request.
sessionStartTimestamp	The start time (date type) of the current session.
sessionEndTimestamp	The end time (date type) of the current session.
sessionEndReason	The reason why the session was finished. For all possible values, see the list of session end reasons.
loginID	This 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.
userID	The 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.
authLevel	The 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.
roles	The roles received by the user (based on role information from the authentication back end).
realm	The name of the SSO authentication domain.For possible names, see the Domain element in your nevisAuth configuration.
language	The 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
eventTrail	The audit events that can be generated by AuthStates and are collected during the session.
custom	Collection 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:

Reason	Description
expired	The SessionReaper has removed a timed-out session.
terminated-by-client	A kill call was made from an external client (such as nevisProxy reaching a session time-out).
terminated-by-flow	The session was killed by AuthState logic (e.g., through response.setInvalidateSession()).
aborted	The authentication operation failed (that is, the AUTH_ERROR status was triggered by the configuration or a Java exception).
logout	A user-triggered logout has been completed.
stateless-domain	The domain configuration signals stateless authentication support.
stateless-request	The 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.