Sun OpenSSO Enterprise 8.0 Technical Overview

Chapter 15 Recording Events with the Logging Service

Sun OpenSSO Enterprise provides its own logging feature that records information such as user login, user logout, session creation, and policy evaluation. This chapter describes how OpenSSO Enterprise logging works. It contains the following sections:

Logging Service Overview

The Logging Service enables OpenSSO Enterprise components to record information such as access denials and approvals, authentication events, and authorization violations. Administrators can use the logs to track user actions, analyze traffic patterns, audit system usage, review authorization violations, and troubleshoot. The logged information is recorded in one centralized directory. The Client SDK enables external applications to access the Logging Service. This section contains the following:

About the Logging Service

The purpose of the Logging Service is to provide the facilities to record events that can then be used to assign responsibility for actions occurring through OpenSSO Enterprise. For example, an individual's attempts to compromise the security of OpenSSO Enterprise, and to what extent those attempts penetrate, can be monitored. A global service configuration file named amLogging.xml defines the Logging Service attributes. These attributes include configuration information such as maximum log size, log location, and log format (flat file or relational database). The attribute values are applied across the OpenSSO Enterprise deployment and inherited by every configured realm. The structure of amLogging.xml is defined by file sms.dtd.

Note –

The Logging Service is fundamentally an extension of the java.util.logging.LogManager, java.util.logging.Logger, java.util.logging.LogRecord, java.util.logging.Formatter and java.util.logging.Handler classes.

Configuring the Logging Service

When OpenSSO Enterprise starts or when any logging configuration data is changed using the administration console, the Logging Service configuration data is loaded (or reloaded) into the Logging Service. This data includes the log message format, maximum log size, and the number of history files. Authenticated and authorized entities (for example, an application) can then use the Client SDK to access the Logging Service features from a local or remote server. The Client SDK uses an XML over HTTP layer to send logging requests to the Logging Service on the server where OpenSSO Enterprise is installed.

Recording Events

Log records are created using the com.sun.identity.log.LogRecord class, and then logged by authenticated and authorized entities using the com.sun.identity.log.Logger class. Log records can be logged by:

The following table summarizes the default items logged in the LogRecord.

Table 15–1 Events Recorded in LogRecord




The date (YYYY-MM-DD) and time (HH:MM:SS) at which the log message was recorded. This field is not configurable.


Variable data pertaining to the log records's MESSAGE ID. This field is not configurable.


Name of the OpenSSO Enterprise service or application being logged. Additional information on the value of this field can be found in “Adding Log Data” on page 88. 


OpenSSO Enterprise domain to which the user (whom the log record is regarding) belongs. This information is taken from the session token passed in the LogRecord(level,msg,token) call.


The Java 2 Platform, Standard Edition (J2SE) version 1.4 log level of the log record. 


The identifier of the user (taken from the session token) as the subject of the log record. 


IP address from which the operation was performed. 


User who writes the log record. The information is taken from the session token passed during logger.log(logRecord, ssoToken).


Host name associated with the IP address above. This is present if the Log Record Resolve Host Name attribute is enabled. If not, the IP address is printed. 


Non-internationalized message identifier for this log record's message. 


Session identifier associated with a particular login session. The session identifier is for the entity about whom the log record is regarding. 

Log File Formats and Log File Types

The following sections contain information about OpenSSO Enterprise log files:

Log File Formats

Log records generated for one event are entered as two separate records. The first log record records the attempt to perform an action; the second log record records the result of the attempt. The following example illustrates this two record approach.

Example 15–1 Log Record Example

Data:	 agroupSubscription1|group|/
MessageID:	CONSOLE-1


Data:	agroupSubscription1|group|/
MessageID:	CONSOLE-2

In this example, CONSOLE-1 indicates an attempt to create an identity object, and CONSOLE-2 indicates that the attempt to create the identity object was successful. The root organization is noted by a forward slash (/). The variable parts of the messages (agroupSubscription1, group, and /) are separated by a pipe character (|) and continue to go into the Data field of each log record. The MessageID string is not internationalized in order to facilitate machine-readable analysis of the log records in any locale. OpenSSO Enterprise can record events in either of the following formats:

Flat File Format

The default flat file format is the W3C Extended Log Format (ELF). OpenSSO Enterprise uses this format to record the default fields in each log record. See Recording Events for a list of default fields and their descriptions. Example 15–2 illustrates an authentication log record formatted for a flat file. The fields are in this order: Time, Data, ModuleName, MessageID, Domain, ContextID, LogLevel, LoginID, IPAddr, LoggedBy, and HostName.

Example 15–2 Flat File Record From amAuthentication.access

"2005-08-01 16:20:28"   "Login Success" LDAP    AUTHENTICATION-100 
   dc=example,dc=com       e7aac4e717dda1bd01      INFO 
"cn=exampleuser,ou=Example Users,dc=example,dc=com" exampleHost

Relational Database Format

When OpenSSO Enterprise uses a relational database to log messages, the messages are stored in a database table. OpenSSO Enterprise uses Java Database Connectivity (JDBC), which provides connectivity to a wide range of databases. (Oracle® and MySQL databases are currently supported.) Table 15–2 summarizes the schema for a relational database.

Table 15–2 Relational Database Log Format

Column Name 

Data Type 



Date (Oracle) 

DateTime (MySQL) 

The format is YYYY-MM-DD HH24:MI:SS (Oracle) or %Y-%m-%d %H:%i:%s (MySQL). The formats are specified in the Logging Service attributes. 


CLOB (Oracle) 


The data type is specified in the Logging Service attributes. 



Name of the OpenSSO Enterprise component invoking the log record. 



OpenSSO Enterprise domain of the user. 



JDK 1.4 log level of the log record. 



Login ID of the user who performed the logged operation. 



IP Address of the machine from which the logged operation was performed. 



Login ID of the user who writes the log record. 



Host name of machine from which the logged operation was performed. 



Non-internationalized message identifier for this log record's message. 



Identifier associated with a particular login session. 

Log File Types: Error and Access

Access log files and error log files are the two types of log files used in OpenSSO Enterprise. Access log files record general auditing information concerning the OpenSSO Enterprise deployment. An access log may contain a single record for an event (such as a successful authentication), or multiple records for the same event. For example, when an administrator uses the console to change an attribute value, the Logging Service logs the attempt to change in one record but, it also logs the results of the execution of the change in a second record. Error log files record errors that occur within the application. While an operation error is recorded in the error log, the operation attempt is recorded in the access log file.

Flat log files are appended with the .error or .access extension. Database column names end with _ERROR or _ACCESS. For example, a flat file logging console events is named amConsole.access while a database column logging the same events is named AMCONSOLE_ACCESS or amConsole_access.

Note –

The period (.) separator in a log filename is converted to an underscore (_) in database formats. Also in databases, table names may be converted to all upper case. For example, amConsole.access may be converted to AMCONSOLE_ACCESS, or it may be converted to amConsole_access.

Secure Logging

Secure logging adds an extra measure of security to the Logging Service. When secure logging is enabled, the Logging Service can detect unauthorized changes to the security logs. No special coding is required to leverage this feature. However, secure logging uses a certificate that you must create and install in the container that runs OpenSSO Enterprise. When secure logging is enabled, a Manifest Analysis and Certification (MAC) is generated and stored for every log record, and a special signature record is periodically inserted in the log. The signature record represents the signature for the contents of the log written up to that point. The combination of the certificate and the signature record ensures that the logs have not been tampered. For detailed information about enabling secure logging, see Chapter 14, Logging Service, in Sun OpenSSO Enterprise 8.0 Administration Guide.

Remote Logging

Remote logging allows a client using the Client SDK to create log records on an instance of OpenSSO Enterprise deployed on a remote machine. Remote logging is useful in the following situations:

OpenSSO Enterprise Component Logs

The log files record a number of events for each of the OpenSSO Enterprise components using the Logging Service. Administrators typically review these log files on a regular basis. Table 15–3 provides a brief description of the log files produced by each OpenSSO Enterprise component.

Table 15–3 OpenSSO Enterprise Component Logs


Log Filename 

Information Logged 

Session Service 

  • amSSO.access

Session management attributes values such as login time, logout time, and time out limits. Also session creations and terminations. 

Administration Console 

  • amConsole.access

  • amConsole.error

User actions performed through the administration console such as creation, deletion and modification of identity-related objects, realms, and policies. amConsole.access logs successful console events while amConsole.error logs error events.

Authentication Service 

  • amAuthentication.access

  • amAuthentication.error

User logins and log outs, both successful and failed. 

Federation Services 

  • amFederation.access

  • amFederation.error

  • amLiberty.access

  • amLiberty.error

Federation-related events such as the creation of an authentication domain or the creation of a hosted provider entity. 

Policy Service (Authorization) 

  • amPolicy.access

  • amPolicy.error

  • amAuthLog

Events related to authorization such as policy creation, deletion, or modification, and policy evaluation. amPolicy.access logs policy allows, amPolicy.error logs policy error events, and amAuthLog logs policy denies.

Policy Agents 


Exceptions regarding resources that were either accessed by a user or denied access to a user. amAgent logs reside on the server where the policy agent is installed. Agent events are logged on the OpenSSO Enterprise machine in the Authentication logs.

SAML v1.x 

  • SAML.access

  • SAML.error

SAML v1.x-related events such as assertion and artifact creation or removal, response and request details, and SOAP errors. 

SAML v2 

  • SAML2.access

  • SAML2.error

SAML v2-related events such as assertion and artifact creation or removal, response and request details, and SOAP errors. 

Command Line 

  • amAdmin.access

  • amAdmin.error

Event successes and errors that occur during operations using the command line tools. Loading a service schema, creating policy, and deleting users are some examples of command line operations. 

Password Reset 

  • amPasswordReset.access

Password reset events. 

For detailed reference information about events recorded in each type of OpenSSO Enterprise log, see Chapter 14, Logging Service, in Sun OpenSSO Enterprise 8.0 Administration Guide.

Logging Service Interfaces

There are two Java interfaces provided with the Logging Service. The Java application programming interface (API) com.sun.identity.log provides the means for an application external to OpenSSO Enterprise to record events to, and retrieve records from, the Logging Service. LogRecord and Logger are used for writing, while LogReader, LogQuery, and QueryElement are used for reading. With this API it is possible to write a custom log reading program by setting up queries to retrieve specific records from the log file or database. The Java service provider interface (SPI) com.sun.identity.log.spi is used to develop plug-ins to the Logging Service for authorization and other service implementations of secure logging.

Other pluggable SPI with interface definitions may be used; for example, ITimestampGenerator and SecureTimestampGenerator. Existing provider modules may be useful as models for writing additional providers. For more information, see the Sun OpenSSO Enterprise 8.0 Java API Reference and the Sun OpenSSO Enterprise 8.0 Developer’s Guide.

Note –

OpenSSO Enterprise also has a Logging Service API for C applications. For more information, see the Sun OpenSSO Enterprise 8.0 C API Reference for Application and Web Policy Agent Developers.