Logging and auditing

Since: 1.2 (Previous version: 1.0 )

The logging and auditing functionality is a fundamental part of the OpenASelect architecture. The error handling, debug messages, logging and auditing are different aspects of the same topic: how to track events within the OpenASelect system. This document aims to describe how this functionality is implemented within the OpenASelect Server.

Logging implementation

OpenASelect logging is implemented using the apache commons logging library. The default log engine is log4j which makes the OpenASelect logging functionality highly flexible.

Types of logging

The OpenASelect logging is logically divided into four parts:

Debug logging

Logging that can be helpful for development purposes

System logging

Logging indicating information regarding system behavior. This information is useful for administrators, to find configuration errors, and developers, to remotely determine what is wrong with a OA server

Event logging

Logging of user and actions. This logging can be used by the administrator to determine user behavior throughout the system. Requestors, like applications, which use the OA server as an IDP can also be regarded as users of the OA Server.

Access log

The access log can be performed by the web and/or application server and is beyond the scope of this page

Debug and system logging

Debug and system logging are both handled by the OA System logger.

Purpose

System logging has the purpose of tracking all possible application faults during initiation and runtime of the A-Select System. In addition information messages are logged which describe default configuration used and status of the A-Select subsystems.

Logging details

The system logging is by default sent to the console and contains the following items:

• Timestamp
• Level
• Descriptive error message
• Error code
• If available the session identifier of the session in which the problem occurred is logged.

In debug mode the following additional items can be added by means of configuration:

• Class name
• Method name
• Filename and line number of the originated class file
• Stack traces
• SQL queries

Event logging

Event logging has the purpose to track users throughout the authentication process. The event log can be used to conduct audits. It is important to define the granularity of the logged actions small enough to be able to determine precisely what path the user followed during his session at the server.

Purpose

The purpose of authentication logging is to log user behavior throughout the system. The resulting logs should be used to provide useful information to the administrator, when an audit is required.

Logging details

The authentication log should only contain truly important events (you have to keep audit trails for a long time, and debug or informational messages are wasteful). The audit trail should contain all phases of the authentication session.

The authentication logging should be logged centrally. Ensure that audit logs are sent to trusted systems, via a trusted and secure channel.

In order to ensure that the logging is useful and can be linked to other events, the following scheme is used:

• Timestamp
  • Can be used to determine the sequence in which a user’s actions have taken place.
• Session ID
  • The value that identifies the user session. All actions of a certain user can be linked by referencing to the session id.
• Ticket Granting Ticket (TGT) ID
  • The value that identifies the user TGT. All actions of a certain user can be linked by referencing to the TGT.
• Session state
  • The state of the authentication session
• Event
  • The event that occurred
• User name
• User organization
• User IP address
• Requestor
  • The id of the requestor which initiated the authentication
• Event detail
  • Optional details of the event which can be event specific
• Authority
  • Unique name of the components that perform event logging

Configuration

The OpenASelect Logging can be configured using a log4j property file which can be found within the unpacked 'openaselect.war' distribution at 'openaselectserver/WEB-INF/classes/log4j.properties'.

The following example shows a simple log configuration for production sites:

# Set root category priority to INFO and appender to CONSOLE.
log4j.rootCategory=INFO, CONSOLE

# Set the OA system logging priority to INFO
log4j.logger.com.alfaariss.oa.ManagerServlet=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.OAContextListener=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.OAServlet=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.engine=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.authentication=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.authorization=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.sso=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.helper=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.profile=INFO, FILE_OA
log4j.logger.com.alfaariss.oa.util=WARN, FILE_OA

# Set the OA Event logging category priority to INFO
log4j.logger.com.alfaariss.oa.EventLogger=INFO, FILE_OA_EVENT
log4j.logger.com.alfaariss.oa.UserProvisioningEventLogger=INFO, FILE_OA_EVENT

# CONSOLE is set to be a ConsoleAppender using a PatternLayout.
log4j.appender.CONSOLE=org.apache.log4j.ConsoleAppender
log4j.appender.CONSOLE.layout=org.apache.log4j.PatternLayout
log4j.appender.CONSOLE.layout.ConversionPattern=[%d{yyyy-MM-dd HH:mm:ss}] [%p] %c{1} %m%n

# RollingFileAppender using a PatternLayout.
log4j.appender.FILE_OA=org.apache.log4j.RollingFileAppender
log4j.appender.FILE_OA.File=${catalina.home}/logs/openaselect/system.log
log4j.appender.FILE_OA.MaxFileSize=10MB
log4j.appender.FILE_OA.MaxBackupIndex=5
log4j.appender.FILE_OA.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE_OA.layout.ConversionPattern=[%d{yyyy-MM-dd HH:mm:ss}] %-5p %c{1}.%M() -> %m%n

# RollingFileAppender using a PatternLayout.
log4j.appender.FILE_OA_EVENT=org.apache.log4j.RollingFileAppender
log4j.appender.FILE_OA_EVENT.File=${catalina.home}/logs/openaselect/event.log
log4j.appender.FILE_OA_EVENT.MaxFileSize=10MB
log4j.appender.FILE_OA_EVENT.MaxBackupIndex=5
log4j.appender.FILE_OA_EVENT.layout=org.apache.log4j.PatternLayout
log4j.appender.FILE_OA_EVENT.layout.ConversionPattern=[%d{yyyy-MM-dd HH:mm:ss}] %m%n

Logging your events to a relational database

OpenASelect supports storing the event logging in a relational database. An example of the database scheme in sql is given here:

DROP TABLE IF EXISTS event_log;
CREATE TABLE event_log ( 
	id SERIAL NOT NULL PRIMARY KEY,
	log_timestamp TIMESTAMP DEFAULT NOW() NOT NULL,
	session_id VARCHAR(24) DEFAULT NULL,
	tgt_id VARCHAR(172) DEFAULT NULL,
	state INTEGER DEFAULT NULL,
	event VARCHAR(255) DEFAULT NULL,
	user_id VARCHAR(256) DEFAULT NULL,
	organization_id VARCHAR(255) DEFAULT NULL,
	ip VARCHAR(15) DEFAULT NULL,
	requestor_id VARCHAR(255) DEFAULT NULL,
	message VARCHAR(255) DEFAULT NULL,
	authority VARCHAR(255) DEFAULT NULL
);

GRANT INSERT ON event_log TO oa_log_user;
GRANT UPDATE ON sequence event_log_id_seq TO oa_log_user;

• oa_log_user should be the user configured in the database connection who has access to the database.

To enable the database event logging the following configuration can be added to the log4j properties:

# Set the OA Event logging category priority to INFO
log4j.logger.com.alfaariss.oa.EventLogger=INFO, DB_OA_EVENT
log4j.logger.com.alfaariss.oa.UserProvisioningEventLogger=INFO, DB_OA_EVENT

# OA EventJDBCAppender
log4j.appender.DB_OA_EVENT=com.alfaariss.oa.util.logging.EventJDBCAppender
log4j.appender.DB_OA_EVENT.driver=[driver]
log4j.appender.DB_OA_EVENT.url=[url]
log4j.appender.DB_OA_EVENT.username=[username]
log4j.appender.DB_OA_EVENT.password=[password]
log4j.appender.DB_OA_EVENT.table=[event_log_table]
#log4j.appender.DB_OA_EVENT.maxActive=10
#log4j.appender.DB_OA_EVENT.maxIdle=10
#log4j.appender.DB_OA_EVENT.minIdle=5
#log4j.appender.DB_OA_EVENT.initialSize=5
#log4j.appender.DB_OA_EVENT.maxWait=10

#log4j.appender.DB_OA_EVENT.environmentContext=[environment_context]
#log4j.appender.DB_OA_EVENT.resourceRef=[resource-ref]

• [driver] The JDBC driver used to connect with the back-end.
• [url] The URL of the JDBC database. For example jdbc:postgresql://[host]/[oa_internal_logging_database]
• [username] The username to be passed to the JDBC driver to establish a connection with the JDBC back-end.
• [password] The password to be passed to the JDBC driver to establish a connection with the JDBC back-end.
• [event_log_table]The name of the event logging table. According to the database scheme above event_log.
• [maxactive] (optional) Maximum number of database connections in pool. Make sure you configure your mysqld max_connections large enough to handle all of your db connections. Set to 0 for no limit.
• [maxidle] (optional) Maximum number of idle database connections to retain in pool. Set to -1 for no limit.
• [maxwait] (optional) Maximum time to wait for a database connection to become available in ms. Set to -1 to wait indefinitely.

It is also possible to use specific database connections configured outside the OAS with the following parameters:

• [environment_context] The reference to the context name where to find the datasource.
• [resource-ref] The reference to the resource defined within te environment context.

In case these parameters are used the previous parameters concerning the database connection (driver, url, username, password, maxactive, maxidle and maxwait) will be ignored.

---

Back to the configuration reference