Sun ONE Identity Server Programmer's Guide
|
Sun ONE Identity Server Programmer's Guide |
Chapter 10 Logging Service
The Sun™ One Identity Server provides a Logging Service to record information such as user activity, traffic patterns, and authorization violations. In addition, Identity Server includes a Logging API to allow external applications to take advantage of the Logging Service. This chapter explains the service and the API. It contains the following sections:
Overview
The Logging Service enables all Identity Server services to record information that might be useful to the administrator in one centralized location. The recorded information may include access denials and approvals, authorization violations and code exceptions. This information allows administrators to analyze user activity, Identity Server traffic patterns and authorization violations. As with all Identity Server services, the Logging Service uses a global configuration file, named amLogging.xml, to define its attributes (such as maximum log size and log location), or whether the log information is written to a flat file or a relational database.
Logging Architecture
External Java applications use the Logging API to access the Logging Service. These interfaces may reside on a remote server or on the same server as the Logging Service. If the APIs live remotely, the PLL Communication Component, an XML over HTTP interface, is used to send the logging request to the Logging Service.
An application accesses the Logging Service by calling the Logging API. Upon receiving a request, the Logging Service loads the configuration data stored in the Directory Server using the Identity Server SDK. Any exception message will be logged, based on these configuration values. On any error, a LoginException is thrown. Figure 10-1 illustrates the architecture of the Logging Service.
Figure 10-1 Logging Service Architecture
Logging Service XML File
The Logging Service holds the attributes and values for the logging function. These attributes and values are defined in the amLogging.xml service file located in <identity_server_root>/SUNWam/config/xml. The values defined in amLogging.xml are applied across the Identity Server deployment and are inherited by every configured organization. More information on the Logging Service and its attributes can be found in the Sun ONE Identity Server Administration Guide.
Log Security
An optional logging feature adds additional security to the log files in terms of tamper detection. No special coding is required to leverage this feature. Please refer to the Sun ONE Identity Server Administration Guide for steps to turn on and configure this secure logging feature.
Log Message Formats
Identity Server supports logging messages stored in both, a text file and a relational database. The following sections explain the data storage formats used in these formats.
Flat File Format
The default flat file format is the W3C Extended Log Format (ELF). In leveraging this format, the Logging Service records time, Data, HostName, LoginID, LogLevel, Domain and IPAddr fields in each log record.
time is the date (yyyy/mm/dd) and time (hh:mm:ss) at which the log message was recorded.
Data is the description of the user activity, errors or other useful information which the application wants to log.
HostName is the hostname from which the operation was performed.
LoginID is the ID of the user attempting to access the application.
LogLevel corresponds to the JDK1.4 l LogLevel of the log record.
Domain is the Identity Server domain to which the user belongs.
IPAddr is the IP address from which the operation was performed.
Code Example 10-1 illustrates a log record formatted for a flat file.
Code Example 10-1 Flat File Formatted Log Record Sample
Relational Database Format
For applications using a relational database to log messages, the message is stored in a database table. Identity Server uses Java Database Connectivity (JDBC) to access data from Java programs in an Oracle® environment. The database schema is as follows:
Table 10-1 Relational Database Log Format
|
|
||
|
|
||
|
|
Host name of machine from which the logged operation was performed. |
|
|
|
||
|
|
||
|
|
||
|
|
IP Address of the machine from which the logged operation was performed. |
|
There is a limitation in the log name length for Oracle JDBC logging: the length of the log name cannot exceed 30 characters. Oracle does not support longer names. |
Logging API
The Logging API provides log management tools for all Identity Server services as well as providing a set of Java classes for external applications to create, retrieve, submit, or delete log information. These API extend the JDK 1.4 API. The main classes are Logger and LogRecord. They are contained in the package com.sun.identity.log.
Logger Class
This Logger class provides the methods for applications to use in creating log files and writing log information to them.
The getLogger() method returns a logger object and simultaneously creates a log in the designated logging location.
The log() method records a single piece of log information or a LogRecord. It allows an application to submit a logging message to a predetermined log.
LogRecord Class
The LogRecord class provides the means to represent the information that needs to be logged. Each instance represents a single piece of log information or LogRecord that comes from the application.
Logging Exceptions
There are a number of exceptions that can be thrown using the Logging APIs. The generic LogException is probably the most common. It signals an error condition while logging a message. Other exceptions include:
ConnectionException—This exception is thrown when the connection to the database fails.
DriverLoadException—This exception is thrown when the JDBC driver load fails.
InvalidLogNameException—This exception is thrown when the log name is invalid.
LogAlreadyExistException—This exception is thrown when the log already exists.
LogCreateException—This exception is thrown when log creation fails.
LogDeleteException—This exception is thrown when the log deletion fails.
LogException—A LogException is thrown when applications are denied log access because they don't have the privileges or a valid session.
LogFatalException—This exception is thrown when a fatal error occurs.
LogHandlerException—A LogException is thrown when a log handler error is encountered.
LogInactiveException—A LogException is thrown when the log is in inactive status. (Inactive/active status is not currently supported.)
LogInvalidSessionException—This exception is thrown when an application accesses a log which does not exist.
LogNotFoundException—This exception is thrown when an application accesses a log which does not exist.
LogPrivDeniedException—A LogException is thrown when the access privilege is denied.
LogProfileException—A LogException is thrown when access privilege is denied.
LogReadExceedsMaxException—A LogException is thrown when the log size exceeds the maximum size defined in the Logging service.
LogReadException—A LogException is thrown when an error is encountered in retrieving the log information.
LogTypeException—This exception is thrown when a log type error occurs.
LogWriteException—This exception is thrown when the log record submission fails.
NullLocationException—This exception is thrown when the location is null.
Sample Logging Code
Code Example 10-2 provides sample code to illustrate uses for the Identity Server logging classes.
Code Example 10-2 Logging API Samples
Logging SPI
The Logging Service framework allows a customer to plug in a class which can decide whether a LogRecord should be retained or discarded based on the authorization of the owner of the SSOToken to perform predefined log operations. For using this facility, the customer must define a logging policy using the policy framework and use it from his plugin to take the decision whether the owner of the SSOToken has permissions to perform the requested logging operation.
Plugin Log Verifier
If secure logging is enabled, the log files are verified periodically to detect any attempt of tampering. The customers can customize the action taken if a tampering is detected, by following the steps below.
Implement the com.sun.identity.log.spi.IVerifierOutput interface, programming it for the desired functionality.
Add the implementing class in the classpath of Identity Server.
Modify the property iplanet-am-logging-verifier-action-class in the <identity_server_root>/SUNWam/config/xml/amLogging.xml file with the name of the new class.
Plugin Authorization Mechanism
The logging framework allows the customer to plugin a class which decides whether a LogRecord should be logged or discarded based on the authorization of the owner of the SSOToken to perform predefined log operations. For using this facility, the customer must define his logging policy using the policy framework and use it from his plugin to take the decision whether the owner of the SSOToken has permissions to perform the requested logging operation.
Implement the com.sun.identity.log.spi.IAuthorizer interface programming it for the desired functionality.
Add the implementing class in the classpath of Identity Server.
Modify the property iplanet-am-logging-authz-class in the <identity_server_root>/SUNWam/config/xml/amLogging.xml file with the name of the new class.
Log Files
By default, Identity Server currently records events in four logs. These files should be monitored by the administrator on a regular basis. The directory for the log files can be found in var/opt/SUNWam.
SSO-related Logs
The Logging Service logs the following events for the SSO component:
Login
Logout
Session Idle TimeOut
Session Max TimeOut
Failed To Login
Session Reactivation
Session Destroy
The log file is called amSSO and is stored in the var/opt/SUNWam/logs directory.
Console-related Logs
The Identity Server console logs record the creation, deletion and modification of identity-related objects, policies and services including, among others, organizations, organizational units, users, roles, policies and groups. It also records modifications of user attributes including passwords and the addition or removal of users to or from roles and groups. The log is named amConsole and is stored in the var/opt/SUNWam/logs directory.
Authentication-related Logs
The Logging component logs user logins and logouts. The log is named amAuthentication and is stored in the var/opt/SUNWam/logs directory.
Federation-related Logs
The Federation component logs federation-related events including, but not limited to, the creation of an Authentication Domain and the creation of a Hosted Provider. The log is named amFederation and is stored in the var/opt/SUNWam/logs directory.
Debug Files
Debug files are stored in var/opt/SUNWam/debug. This location, along with the level of the debug information, is configurable in the AMConfig.properties file, located in the <identity_server_root>/SUNWam/lib/ directory. The debug files may be monitored in the event of, for example, a product crash. The administrator can try to understand the reason for an error situation from these files.
Secure Logging
Secure Logging enables the detection of unauthorized changes or tampering with the security logs. The Identity Server administrator can enable secure logging by following this procedure:
Create a web server certificate with the name Logger and install it in the Sun ONE Web Server running the Identity Server.
Select the Logging Service under the Service Configuration module, turn on Secure Logging and click Save.
Create a file in the <identity_server_root>/SUNWam/config directory named .wtpass which contains the Web Server administrator password.
Restart the Web Server after making these changes.
Previous Contents Index Next
Copyright 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated December 02, 2002