Chapter 6 Logging and the Java Enterprise System Monitoring Framework

Sun Java System Access Manager provides its own logging feature that records information such as user login, user logout, session creation, and policy evaluation. This chapter describes how Access Manager logging works, and provides some information about the Java Enterprise System Monitoring Framework. It contains the following sections:

• Logging Overview

• Log Files

• Access Manager Component Logs

• Additional Logging Features

• Java Enterprise System Monitoring Framework

Logging Overview

The Logging Service enables Access Manager services to record information such as access denials, access 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 from all Access Manager services is recorded in one centralized directory. The default location for all Access Manager log files is /var/opt/SUNWam/logs. Logging client APIs enable external applications to access the Logging framework. This section contains the following:

• Logging Service

• Logging Configuration

• Recorded Events

Logging Service

The Logging Service stores the attributes and values for the logging function. A global service configuration file named amLogging.xml defines the Logging attributes. Examples of Logging Service attributes are maximum log size, log location, and log format (flat file or relational database). The attribute values are applied across the Access Manager deployment and inherited by every configured realm. By default, amLogging.xml is located in the directory /etc/opt/SUNWam/config/xml when Access Manager is installed in a Solaris environment. (When installed on Windows, the directory is jes-install-dir\identity\config\xml; on HP-UX the directory is /etc/opt/sun/identity/config/xml.) The structure of amLogging.xml is defined by file sms.dtd.

Logging Configuration

When Access Manager starts or when any logging configuration data is changed using the Access Manager console, the logging configuration data is loaded (or reloaded) into the Logging Service. This data includes the log message format, log file name, maximum log size, and the number of history files. Applications can use the client APIs to access the Logging features from a local or remote server. The client APIs use an XML-over-HTTP layer to send logging requests to the Logging component on the server where Access Manager is installed.

Recorded Events

The client passes the Logging Service logs information to the com.sun.identity.log.LogRecord class. The following table summarizes the items logged by default in the LogRecord.

Log Files

The following sections contain information about Access Manager log files:

• Log File Formats

• Error and Access Logs

Log File Formats

Access Manager can record events in either of the following formats:

• Flat File Format

• Relational Database Format

Flat File Format

The default flat file format is the W3C Extended Log Format (ELF). Access Manager uses this format to record the default fields in each log record. See Recorded Events for a list of default fields and their descriptions. The following example 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 6–1 Flat File Record From amAuthentication.access

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

Relational Database Format

When Access Manager uses a relational database to log messages, the messages are stored in a database table. Access Manager uses Java Database Connectivity (JDBC) to access the database table. JDBC provides connectivity to a wide range of SQL databases. JDBC also provides access to other tabular data sources such as spreadsheets or flat files. Oracle® and MySQL databases are currently supported.

For log records generated by Access Manager, the Data and MessageID fields are used slightly differently than in previous versions of Access Manager. Starting with this version of Access Manager, the MessageID field is introduced as a template for types of log messages. For example, in previous versions, Access Manager would generate the following message in the Data field:

Data: "Created group
cn=agroupSubscription1,ou=Groups,dc=iplanet,dc=com"

In this version of Access Manager, two log records are recorded for the one event:

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

and

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

These log records reflect the use of identities and realms. In this example, CONSOLE-1 indicates an attempt to create an identity object, and CONSOLE-2 indicates the attempt to create an identity object was successful. The root organization notation (dc=iplanet,dc=com) is replaced with 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 MessagID string is not internationalized in order to facilitate machine-readable analysis of the log records in any locale.

The following table summarizes the schema for a relational database.

TIME

DATA

MODULENAME

DOMAIN

LOGLEVEL

LOGINID

IPADDR

LOGGEDBY

HOSTNAME

MESSAGE ID

CONTEXT ID

Error and Access Logs

There are two types of Access Manager log files:

• Access log files

• Error log files

Access log files record general auditing information concerning the Access Manager 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, the Logging Service 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.

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.

Access Manager Component Logs

The log files record a number of events for each of the Access Manager components using the Logging Service. Administrators typically review these log files on a regular basis. The default location for all Access Manager log files is /var/opt/SUNWam/logs when Access Manager is installed in a Solaris environment. (When installed on Windows, the directory is jes-install-dir\identity\logs; on HP-UX the directory is /var/opt/sun/identity/logs.) The following table provides a brief description of the log files produced by each Access Manager component.

For detailed reference information about events recorded in each type of Access Manager log, see the Sun Java System Access Manager 7.1 Administration Guide.

Additional Logging Features

You can enable a number of logging features for added functionality. The additional features include:

• Secure Logging

• Remote Logging

• Log Reading

Secure Logging

This feature adds an extra measure of security to the Logging Service. When secure logging is enabled, the Logging component 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 Access Manager. 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 the Sun Java System Access Manager 7.1 Administration Guide.

Remote Logging

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

• When the login URL in the Naming Service of an Access Manager instance points to a remote Access Manager instance, and a trust relationship between the two instances has been configured.

• When the Access Manager APIs are installed in a remote Access Manager instance, and a client application or a simple Java class running on the Access Manager server uses the logging APIs.

• When logging APIs are used by Access Manager agents.

Log Reading

Access Manager provides Logging APIs for writing your own custom log reading program. You can set up queries to retrieve specific records from the log file or database. This is useful for auditing purposes. For more information, see the Sun Java System Access Manager 7.1 Developer’s Guide.

Java Enterprise System Monitoring Framework

Access Manager 7.1 integrates with the Java Enterprise System (JES) monitoring framework through Java Management Extensions (JMX). JMX technology provides the tools for building distributed, web-based, modular, and dynamic solutions for managing and monitoring devices, applications, and service-driven networks. Typical uses of the JMX technology include: consulting and changing application configuration, accumulating statistics about application behavior, notification of state changes and erroneous behaviors. Data is delivered to centralized monitoring console. Access Manager 7.1 uses the Java ES Monitoring Framework to capture statistics and service-related data such as:

• Number of attempted, successful, and failed authentications

• Number of active sessions, statistics from session failover DB

• Session failover database statistics

• Policy caching statistics

• Policy evaluation transaction times

• Number of assertions for a given provider in a SAML/Federation deployment

For comprehensive information about how the JES monitoring framework works and how you can use the monitoring framework with Access Manager, see the Sun Java Enterprise System 5 Monitoring Guide.