Sun Java System Access Manager 7 2005Q4 Technical Overview

Chapter 6 Logging

Access Manager provides a logging feature that records information such as user logins and logouts, session creation, policy evaluation, and other events. You can use Access Manager logs to audit system usage and to troubleshoot problems. Logging APIs enable external applications to access the Logging feature.

This chapter describes how Access Manager logging works. The chapter contains the following sections:

How the Logging Feature Works

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, and review authorization violations. The logged information from all Access Manager services are recorded in one centralized location. The default location for all Access Manager log files is /var/opt/SUNWam/logs.

Logging Architecture

When Access Manager starts up or when any logging configuration data is changed through the console, logging configuration data is loaded into the Logging component. 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.


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. The structure of amLogging.xml is defined by file sms.dtd.

Log File Formats

Access Manager can record events in flat text files or in a relational database.

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 code example illustrates an authentication log record formatted for a flat file.

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 
"cn=exampleuser,ou=Example Users,dc=example,dc=com" exampleHost

In the example, the fields are in this order: Time, Data, ModuleName, MessageID, Domain, ContextID, LogLevel, LoginID, IPAddr, LoggedBy, and HostName.

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 7.0, the Data and MessageID fields are used slightly differently than in previous Access manager versions. Starting with Access Manager 7.0, the MessageID field is introduced as a kind of 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

In Access Manager 7.0, two log records are recorded for the one event:

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


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

The log records reflect the use of identities and realms, new in Access Manager 7.0. In this example, CONSOLE-1 indicates an attempt to create an identity, and CONSOLE-2 indicates the attempt to create an identity 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.

Table 6–1 Relational Database Log Format

Column Name  

Data Type  




Date of the log in the format YYYY-MM-DD HH:MM:SS.



The variable data part of the log record pertaining to the MESSAGE ID. For MySQL, the Data Type is VARCHAR(255).  



Name of the Access Manager component invoking the log record. 



Access Manager 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 Files Directory

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. The following table describes the files in the log files directory.

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.

Table 6–2 Files in the Log Files Directory

File or Table  

Information Logged  


Policy denies 


Policy allows 


Policy error events 


Successful console events 


Console error events 


Authentication successes 


authentication failures 


Password reset events 


SSO creates/destroys 


SAML successful events 


SAML error events 


Liberty successful events 


Liberty error events 


Federation successful events 


Federation error events 


amadmin CLI successful events 


amadmin CLI error events 

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.

Table 6–3 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.

Module Name 

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


Access Manager domain to which the user belongs. 

Log Level 

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

Login ID 

ID of the user as the subject of the log record. The user ID is taken from the session token. 

IP Address 

IP address from which the operation was performed. 

Logged By 

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

Host Name 

Host name associated with the IP Address above. 


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


Identifier associated with a particular login session. 

Error and Access Logs

Two types of Access Manager log files exist: access log files and error log files.

Access log files record general auditing information concerning the Access Manager deployment. A log may contain a single record for an event such as a successful authentication. A log may contain 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. 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.

For detailed reference information about events recorded in each type of Access Manager, log see the Sun Java System Access Manager 7 2005Q4 Administration Guide. The following table provides a brief description of the log file produced by each Access Manager component.

Table 6–4 Access Manager Component Logs


Log Filename Prefix  

Information Logged  



Session management attributes values such as login time, logout time, timeout limits. 

Administration Console 


User actions performed through the administration console such as creation, deletion and modification of identity-related objects, realms, and policies. 



User logins and logouts. 

Identity Federation 


Federation-related events such as the creation of an Authentication Domain and the creation of a Hosted Provider. The federation logs are prefixed with amFederation.

Authorization (Policy) 


Policy-related events such as policy creation, deletion, or modification, and policy evaluation. 

Policy Agent 


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 Access Manager machine in the Authentication logs.



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



Event errors that occur during operations using the command line tools. Examples are: loading a service schema, creating policy, and deleting users. 

Additional Logging Features

You can enable a number of logging features for added functionality. The additional features include secure logging, command-line logging, and remote logging.

Secure Logging

This feature adds an extra measure of security to the logging feature. 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 2005Q4 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:

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 2005Q4 Developer’s Guide.