Implementing Logging with the Logging Service API (Sun OpenSSO Enterprise 8.0 Developer's Guide)

Sun OpenSSO Enterprise 8.0 Developer's Guide

Implementing Logging with the Logging Service API

The Logging Service API provides the interfaces for the OpenSSO Enterprise internal services and remote applications running the Client SDK to create and submit log records. Retrieving log records cannot be done using the client SDK. The logging API is in the com.sun.identity.log package, which is documented in the Sun OpenSSO Enterprise 8.0 Java API Reference.

The Logging Service API extends the core logging APIs in the Java SE. For more information about the Java SE APIs, see http://java.sun.com/javase/reference/index.jsp.

The following sections have more information.

For more information see the Sun OpenSSO Enterprise 8.0 Java API Reference.

Writing Log Records

When writing log records, the Logging Service verifies that the logging requester has the proper authority to log and then writes the information to the configured location, formatting and completing the columns in the log records.

An application makes logging calls using the getLogger() method, which returns a Logger object. Each Logger keeps track of a log level and discards log requests that are below this level. (There is one Logger object per log file.) The applications allocates a LogRecord, which is written to the log file using the log() method. An SSOToken, representing the user's session data, is passed to the LogRecord constructor and used to populate the appropriate fields to be logged.

OpenSSO Enterprise contains plug-ins to write log records to:

The host's flat file system
The host's flat file system with added signing of the LogRecord and periodic verification
A relational database
A remote instance of OpenSSO Enterprise

The Logging Service requires two session tokens:

Creating the LogRecord requires an SSOToken for the subject about whom the LogRecord is being written.
Writing the LogRecord requires an SSOToken for the entity requesting the logging of the record.

Note –

If your application also invokes utilities that log without using the OpenSSO Logging Service API, then you might also need to include the following:

import com.sun.identity.log.Logger;
Logger.token.set(ssoToken);

where ssoToken is the SSOToken of the entity requesting the logging. Also, once done, the following statement should be executed:

Logger.token.set(null); to clear the entity's SSOToken from the Logging Service.

The following parameters can have values logged when the addLogInfo() method is invoked. All columns except for time, Data, and NameID can be selected for exclusion from the record written to the log file.

time

The date and time is retrieved from OpenSSO Enterprise and added by the Logging Service.

Data

The event being logged as defined in the message string specified in the LogRecord() constructor call.

ModuleName

The value specified for the LogConstants.MODULE_NAME property in the addLogInfo() call. For example, the RADIUS module might be specified in an authentication attempt.

Note –

If no value is specified, this field will be logged as Not Available.

MessageID

The value specified for the LogConstants.MESSAGE_ID property in an addLogInfo() call.

Note –

If no value is specified, this field will be logged as Not Available.

Domain

The value for this field is extracted from the SSOToken and corresponds to either the subject userID's domain, or organization.

ContextID

The value for this field is extracted from the SSOToken and corresponds to the subject userID's session context.

LogLevel

The logging level, passed to the LogRecord() constructor, at which this record is being logged.

LoginID

The value for this field is extracted from the SSOToken and corresponds to the subject userID's Principal name.

NameID

The value specified for the LogConstants.NAME_ID property in an addLogInfo() call. It is an alias that maps to the actual userID.

Note –

If no value is specified, this field will be logged as Not Available.

IPAddr

The value for this field is extracted from the SSOToken and corresponds to the originating point of the action being logged.

LoggedBy

The identifier in this field is extracted from the logging requestor's SSOToken specified in the Logger.log() call.

HostName

The host name corresponding to the originating point of the action being logged is derived from the IPAddr in the user's SSOToken, if it can be resolved.

Note –

Resolving host names is disabled by default; enable this feature by toggling the Log Record Resolve Host Name system configuration attribute under Logging Service. If disabled, the HostName value is taken from the user's SSOToken and the IPAddr value is logged as Not Available.

Reading Log Records

When handling log reading requests, a valid SSOToken must be provided. The Logging Service verifies that the requester has the proper authority, and then it retrieves the requested records from the configured log location. The LogReader class provides the mechanism to read a log file and return the appropriate data to the caller. It provides the authorization check, reads the data, applies the query (if any), and returns the result as a string. The LogQuery is constructed using the getLogQuery() method.

Note –

Reading log records from a remote client program using the client SDK is not supported.

Unless all records from a log file are to be retrieved, at least one LogQuery must be constructed. The LogQuery objects qualify the search criteria.

A LogQuery can specify a list of QueryElements, each containing a value for a field (column) and a relationship. The QueryElement supports the following relationships:

QueryElement.GT: Greater than
QueryElement.LT: Less than
QueryElement.EQ: Equal to
QueryElement.NE: Not equal to
QueryElement.GE: Greater than or equal to
QueryElement.LE: Less than or equal to
QueryElement.CN: Contains
QueryElement.SW: Starts with
QueryElement.EW: Ends with

Caution –

Log files and tables in particular can become very large. If you specify multiple logs in a single query, create queries that are very specific or limited in the number of records to return (or both specific and limited). If a large number of records are returned, the OpenSSO Enterprise resource limits (including those of the host system) can be exceeded.

The following sample code queries for all successful authentications in realm dc=example,dc=com, and returns the time, Data, MessageID, ContextID, LoginID, and Domain fields, sorted on the LoginID field:

ArrayList al = new ArrayList();
al.add (LogConstants.TIME);
al.add (LogConstants.Data);
al.add (LogConstants.MESSAGE_ID);
al.add (LogConstants.CONTEXT_ID);
al.add (LogConstants.LOGIN_ID);
al.add (LogConstants.DOMAIN);
LogQuery lq = new LogQuery(LogQuery.ALL_RECORDS,
    LogQuery.MATCH_ALL_CONDITIONS,
    LogConstants.LOGIN_ID);

QueryElement qe1 = new QueryElement(LogConstants.MESSAGE_ID,
    "AUTHENTICATION-105",
    QueryElement.EQ);
lq.addQuery(qe1);

QueryElement qe2 = new QueryElement(LogConstants.DOMAIN,
    "dc=example,dc=com",
    QueryElement.EQ);
lq.addQuery(qe2);

In this code, assuming that dc=example,dc=com is the root realm, changing the qe2 relationship field to QueryElement.EW or QueryElement.CN changes the query to include all successful authentications in all realms. To read the example query from the amAuthentication.access log, assuming presence of an SSOToken, add the following:

 String[][] result = new String[1][1];
    result = read("amAuthentication.access", lq, ssoToken);

The first record in a log (row 0) contains the field and column names.