Chapter 15 Reading and Writing Log Records

Sun^TM OpenSSO Enterprise provides the Logging Service to record information such as user activity, traffic patterns, and authorization violations. This chapter describes how to implement and customize the logging functionality, including:

• About the Logging Service

• Using the Logging Interfaces

• Implementing Remote Logging

• Running the Command-Line Logging Sample (LogSample.java)

About the Logging Service

When processing a logging request, the Logging Service extracts information from a user's session data structure and writes it to the configured log format, which can be either a flat file or a relational database. For example, this information can include access denials and approvals, authentication events, and authorization violations.

Administrators can then use the logs to track user actions, analyze traffic patterns, audit system usage, review authorization violations, and troubleshoot. Logged information is recorded in a centralized directory; which by default, is:

ConfigurationDirectory/depoly-uri/log

• ConfigurationDirectory is the name of the directory specified during the initial configuration of OpenSSO Enterprise server instance using the Configurator. This directory is created in the home directory of the user who ran the Configurator.

• deply-uri is the OpenSSO Enterprise deployment descriptor.

For example: /opensso/opensso/log

For more information about user sessions and the session data structure, see Chapter 6, Models of the User Session and Single Sign-On Processes, in Sun OpenSSO Enterprise 8.0 Technical Overview.

For information about how the Logging Service works, see Chapter 15, Recording Events with the Logging Service, in Sun OpenSSO Enterprise 8.0 Technical Overview.

Using the Logging Interfaces

The Logging Service contains both an application programming interface (API) and service provider interface (SPI). You can use the logging APIs to add logging functionality to a client application and the SPIs to develop custom plug-ins to add functionality to the Logging Service.

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.

• Writing Log Records

• Reading Log Records

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.

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.

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

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.

Implementing Remote Logging

• Logging to a Second OpenSSO Enterprise Server Instance

• Logging to OpenSSO Enterprise Server From a Remote Client

Logging to a Second OpenSSO Enterprise Server Instance

An OpenSSO Enterprise server instance can use the Logging Service of another OpenSSO Enterprise server instance, if both instances are configured as part of the same site. The remote OpenSSO Enterprise server sets its Logging Service URL in the Administration Console (Configuration > System > Naming) to the target OpenSSO Enterprise server instances's Logging Service, by changing the attribute's protocol, host, port, and uri values, accordingly. For example:

https://ssohost2.example.com:58080/opensso/loggingservice

Reading log records remotely from another server or from a client program using the client SDK is not supported.

Logging to OpenSSO Enterprise Server From a Remote Client

A remote client can use the OpenSSO Enterprise client SDK to log to an OpenSSO Enterprise server. In order for the remote client to log to the target OpenSSO Enterprise server, the entity making the logging request must have Log Writing permission on the target OpenSSO Enterprise server. For information, see Running the Command-Line Logging Sample (LogSample.java).

Running the Command-Line Logging Sample (LogSample.java)

OpenSSO Enterprise provides a command-line logging sample to show log writing from a client using the OpenSSO client SDK. This sample (and other samples) are in the opensso-client.zip file, which is part of the opensso_enterprise_80.zip file.

After you unzip opensso-client.zip, the command-line logging sample is:

• Solaris and Linux systems: opensso-client-zip-root/sdk/scripts/CommandLineLogging.sh

• Windows systems: opensso-client-zip-root\sdk\scripts\CommandLineLogging.bat

opensso-client-zip-root is where you unzipped the opensso-client.zip file.

The command-line logging sample runs in a stand alone JVM and does not require a web container.

To run the command-line logging sample, OpenSSO Enterprise server must be running and accessible from the client server. You will also need to know this information:

• Protocol (http or https) used by the OpenSSO Enterprise server web container instance.

• Fully qualified domain name (FQDN) of the OpenSSO Enterprise server host.

• Port for the OpenSSO Enterprise server.

• Deployment URI for the OpenSSO Enterprise server (default is opensso).

• Default agent user (UrlAccessAgent) password that you entered when you ran the OpenSSO Enterprise Configurator.

• OpenSSO Enterprise server amadminpassword, if amadmin is the logging requestor in the sample.

To Run the Command-Line Logging Sample

1. If necessary, unzip opensso_enterprise_80.zip and then unzip zip-root/opensso/samples/opensso-client.zip.

2. Make sure that your JAVA_HOME environment variable points to a JDK 1.5 or 1.4 installation.

3. Change to the opensso-client-zip-root/sdk directory.

   Note: You can invoke the sample scripts only from the /sdk parent directory and not directly from the /scripts directory.

4. Follow the instructions in the README file to configure the AMConfig.properties file and to setup and compile the sample applications.

   Note: You need to setup and compile the sample command-line applications only once. If the sample applications are already compiled, continue with the next step.

5. Run the sample command-line logging sample script from the /sdk directory. For example:

   • Solaris and Linux systems: scripts/CommandLineLogging.sh

   • Windows: scripts\CommandLineLogging.bat

6. The logging sample program prompts you for the subject user's identifier and password, log file to use, message to log, logging user's identifier and password, and the realm (both users must be in the same realm).

   Either accept the default values for the prompts or specify your preferred values. For example:

   Subject Userid [user1]: accepted default
   Subject Userid user1 password [user1password]: user1-password
   Log file [TestLog]: accepted default
   Log message [Test Log Record]: accepted default
   LoggedBy Userid [amadmin]: accepted default
   LoggedBy Userid's password [amadminpswd]: amadmin-password
   Realm [/]: accepted default
   ==>Authentication SUCCESSFUL for user user1
   ==>Authentication SUCCESSFUL for user amadmin
   LogSample: Logging Successful !!! 

7. Check the TestLog created in the OpenSSO Enterprise server log directory.

   The default log directory is ConfigurationDirectory/depoly-uri/log.

   For example: /opensso/opensso/log