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 Type | Description |
|---|---|
| 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).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). |
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:
| 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 anAuthEventdocument 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 in the. |
| 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. |
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:
| 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). |
| redirected | A user request resulted in an AUTH_REDIRECT status. |
| 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 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.