Auditing
This chapter deals with the auditing of authentication-related events.
Audit events
Audit events are generated under the following circumstances:
| Event | Generated by | Condition |
|---|---|---|
| authenticate | AuthEngine | When during an authentication the response status from an AuthState execution is either AUTH_DONE (with or without error), AUTH_CONTINUE or AUTH_ERROR. |
| stepup | AuthEngine | When during a step-up the response status from an AuthState execution is either AUTH_DONE (with or without error), AUTH_CONTINUE or AUTH_ERROR. |
| stepdown | AuthEngine | When during a step-down the response status from an AuthState execution is either AUTH_DONE (with or without error), AUTH_CONTINUE or AUTH_ERROR. |
| unlock | AuthEngine | When during an unlock the response status from an AuthState execution is either AUTH_DONE (with or without error), AUTH_CONTINUE or AUTH_ERROR. |
| logout | AuthEngine | When during an explicit logout of the user the response status from an AuthState execution is either AUTH_DONE (with or without error), AUTH_CONTINUE or AUTH_ERROR.This event can also be triggered by an AuthState in case a session is invalidated. |
| timeout | SessionCache | The session has been removed from the local session store. If no other session termination event is present, the local reaper finally removed the session. |
| terminate | SessionCoordinator | The session is going to be killed locally. |
| custom | AuthState | A plug-in generates its own audit events. Check the section "Audit" in the AuthState documentation chapter. |
Audit data
The AuthEngine is called by an access proxy or caller and receives various information about the proxy, the user-agent (e.g., browser) in addition to the user's authentication data. After authentication, data from the AuthState plug-ins is also available. The following table lists the possible audit entry data. All this data may be consumed by an audit channel:
| Field | Provided by | Content |
|---|---|---|
| Timestamp | System | Audit events are immediately delivered to the audit channel. The timestamp of the event therefore needs to be extracted from the system clock by the audit-channel. |
| Event | AuthEngine, SessionCoordinator or AuthState plug-ins | See the column "Generated by" in the table Audit events. |
| Severity | NOTICE: A successful uncritical event. ALERT: a critical event that requires administrator attention. ERROR: A failed, possibly critical event. | |
| Detail | Additional information describing the event. | |
| SecRoles | AuthState | The user's current security role(s) displayed as a comma-separated list of role identifiers. |
| AuthLevel | AuthState or configuration | The user's authentication level, e.g., "auth.weak". |
| ClientIP | caller (access proxy) | Usually the (unverified) user's workstation IP address as passed by the access proxy. If the proxy is installed behind non-transparent network infrastructure (load balancers, firewalls), which replace the source address in the TCP packages, this field is not really useful, as it always contains the same IP address. |
| ClId | caller (access proxy) | The network channel ID, as generated by the access proxy. This field is used to correlate messages that are sent over the same channel. |
| ClientSec | caller (access proxy) | The security attributes of the network channel (e.g., used SSL protocol and cipher). |
| ClientType | user-agent | The user-agent (HTTP header), as forwarded by the access proxy. |
| Domain | caller (access proxy) | The authentication realm, which the access proxy wants to use to authenticate its clients. |
| DomainMap | AuthState | A list of identity mappings for back end applications. |
| EntryId | caller (access proxy) | A unique identifier that allows to distinguish between different access zones or access proxy instances. |
| AuthId | nevisAuth(configuration) | A unique identifier that allows to distinguish between different authentication zones or nevisAuth instances. |
| LoginId | user | The user name, visible to and known by the accessing user. |
| Url | caller (access proxy) | The resource, which the user wants to use, and which triggered the authentication. |
| SessId | nevisAuth(SessionCache) | The authentication session, as generated by nevisAuth. |
| ConversationId | AuthEngine | The identifier of the conversation. All requests/response contexts share this identifier until AUTH_DONE. |
| Principal | AuthState | The (global) authenticated user principal. |
| TraceId (only in SOAP deployment) | caller(access proxy) | Unique transfer ID supplied by nevisProxy or other clients. This ID links the audited operation to the issuing request at the client. |
| List of Authentication Markers | AuthEngine/ AuthState | An Authentication Marker or auth marker represents a successfully completed operation that is relevant for the authentication and authorization process. Each auth marker belongs to an AuthState.An auth marker has the following form:*<technology>:<type>". |
Audit channels
Audit channels are output-handlers for audit events. They have the following characteristics:
- They define, what (available) data to use and how to format it.
- They implement, where to output the data (file, MQ, ...).
Currently, the nevisAuth standard distribution includes the NevisAuditChannel.
It is also possible to implement a custom AuditChannel interface. For a description of the AuditChannel interface, see AuditChannel interface
NevisAuditChannel
This channel outputs all fields, listed in chapter "Audit data" and writes them (via log4j) to a file. The file can be rotated based on a size or time-policy. The output is formatted as follows (single line format, newlines added for better readability):
2015-04-24 09:08:24,683 INFO
Domain="SSO"
LoginId="xxx"
Principal="xxx"
Event="authenticate"
Detail=""
AuthLevel="auth.weak"
SecRoles="auth.weak,webmail"
DomainMap=""
ClientIP="10.22.214.122"
ClientSec="TLSv1.2;DHE-RSA-AES256-SHA"
ClientType="Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/42.0.2311.90 Safari/537.36"
EntryId="extranet.siven.ch"
ClId="59a4000aacccNFBkB7OwKRjuD5SpPsL/UccBmRn4TM9f+ySOc0F+Zpw="
Url="https://extranet.siven.ch/jira/secure/MyJiraHome.jspa"
AuthId="I1"
SessId="0L1c-sHdIRRcNKG410z0b1DsqZFX6KLmNhhBx4g-YKw"
TraceId="1d7bf899ab6ca912dd27fdf777bd90a6"
ConversationId="805056107136"
Trail: SSOLdapLogin{2015-04-24 09:08:24; LDAP:username/password(uid=xxx,ou=people,o=siven,c=ch)}
The keys in the log entry names can be mapped as follows to the field entries in section Audit data:
| Keys in NevisAuditChannel | Available audit data |
|---|---|
| Event | Event |
| Detail | Detail |
| SecRoles | ActualRoles |
| AuthLevel | AuthLevel |
| ClientIP | ClientAddress |
| ClId | ClientId |
| ClientSec | ClientSecurityInfo |
| ClientType | ClientType |
| Domain | Domain |
| DomainMap | DomainMappings |
| EntryId | EntryId |
| AuthId | EsAuthId |
| LoginId | LoginId |
| Url | Resource |
| SessId | SessionId |
| Principal | UserId |
| TraceId | TraceId (only in SOAP deployment) |
| Trail | (list of) Authentication Markers. A Trail entry consists of a sequence of Authentication Markers or auth markers. Together, these auth markers show the route of the user through various AuthStates during a specific authentication and/or authorization event. A trail can contain just one auth marker or several auth markers. A Trail entry has the following form: Trail: <AuthState1>{<date and time>; <auth marker1>}-><AuthState2>{<date and time>; <auth marker2>}->… |
Trail: SSOLdapLogin{2015-04-24 09:08:24; LDAP:username/password(uid=xxx,ou=people,o=siven,c=ch)}
Trail: SSOIdmUserIdPasswordLogin{2015-10-20 09:31:47; nevisIDM:username/password(pbu)}-->SSOIdmPostProcessing{2015-10-20 09:31:47; nevisIDM:selection(profile: Profile-pbu/1000)}
AuditChannel interface
The AuditChannel interface contains two methods:
| AuditChannel Methods | Description |
|---|---|
| init(Properties cfg) | This method is called by the AuthEngine upon initialization of the AuditChannels. Properties configured in the nevisAuth configuration are handed to the init method. |
| audit(String event, String detail, AuditEntry entry, int severity) | This method is called to deliver audit events. The channel should format and deliver the events according to the audit event destination. |
Each AuditChannel is initialized upon nevisAuth start. The configuration properties from the esauth4.xml file are handed to the init(…) method. The audit(…) method is called whenever an audit event is handled.
To write the audit log into a custom storage, implement the AuditChannel interface. Configure the classpath for the custom AuditChannel implementation in the AuthEngine classpath configuration (see Plugging authentication infrastructures). In common cases, the classpaths are put into the /var/opt/nevisauth/<inst>/plugin directory.