7 Using the Logging Service

The Oracle OpenSSO Security Token Service (OpenSSO STS) logging service records information such as access denials and 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 is recorded in one centralized directory. This chapter contains the following topics:

About the Logging Service
Configuring Global Logging Attributes
Using OpenSSO STS Component Logs
Using Secure Logging
Using Database Logging

7.1 About the Logging Service

The log files record a number of events for each of the OpenSSO STS services. These files should be checked by the administrator on a regular basis. The default directory for the log files is ConfigurationDirectory/uri/log/, where ConfigurationDirectory is the configuration directory, and uri is the OpenSSO deployment URI specified during OpenSSO configuration and deployment time. These tags are interpreted at run time. Each deployed OpenSSO instance has its own logging directory. This is particularly useful when there are multiple OpenSSO instances per system. The log file directory can be configured in the logging service by using the OpenSSO STS console or ssoadm command-line utility. An absolute path may also be configured as the log file directory. For detailed configuration steps, see "Configuring Global Logging Attributes".

7.1.1 Log Records

Log records are created using the com.sun.identity.log.LogRecord class, and then logged by authenticated and authorized entities using the com.sun.identity.log.Logger class. Log records can be logged by:

Other components of the OpenSSO STS server.
Utilities installed on the OpenSSO STS server system.
Other OpenSSO STS servers using a second instance of OpenSSO STS acting as the log server.
Remote client applications (for example, policy agents) using the OpenSSO STS Logging Service.

The following table summarizes the events logged by default in the LogRecord, and a brief description of each event.

Table 7-1 Events Recorded in LogRecord

Event	Description
Time	The date (YYYY-MM-DD) and time (HH:MM:SS) at which the log message was recorded. This field is not configurable.
Data	Variable data pertaining to the log records's MESSAGE ID. This field is not configurable.
ModuleName	Name of the OpenSSO STS service or application being logged.
Domain	OpenSSO STS domain to which the user (whom the log record is regarding) belongs. This information is taken from the session token passed in the LogRecord(level,msg,token) call.
LogLevel	The Java 2 Platform, Standard Edition (J2SE) version 1.4 log level of the log record.
LoginID	The identifier of the user (taken from the session token) as the subject of the log record.
IPAddress	User who writes the log record. The information is taken from the session token passed during logger.log (l`ogRecord`, `ssoToken`).
HostName	Host name associated with the IP address above. This is present if the Log Record Resolve Host Name attribute is enabled. If not, the IP address is printed.
MESSAGEID	Non-internationalized message identifier for this log record's message.
ContextID	Session identifier associated with a particular login session. The session identifier is for the entity about whom the log record is regarding.

7.1.2 Error Logs and Access Logs

Access log files and error log files are the two types of log files used in OpenSSO STS. Access log files record general auditing information concerning the OpenSSO STS 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, it 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.

Tip:

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.

7.1.3 Log File Formats

Log records generated for one event are entered as two separate records. The first log record records the attempt to perform an action. The second log record records the result of the attempt. The following example illustrates this two-record approach.

Example 7-1 Log Record Example

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

and

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

In this example, CONSOLE-1 indicates an attempt to create an identity object, and CONSOLE-2 indicates that the attempt to create the identity object was successful. The root organization is noted by 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 MessageID string is not internationalized in order to facilitate machine-readable analysis of the log records in any locale.

OpenSSO STS can record events in either flat file format or relational database format.

Flat log files are appended with the .error or .access extension. Database column names end with _ERROR or _ACCESS for an Oracle database, or _error or _access for MySQL databases. For example, a flat file logging console events is named amConsole.access, while a database column logging the same events is named AMCONSOLE_ACCESS.

7.1.3.1 Flat File Format

The default flat file format is the W3C Extended Log Format (ELF). OpenSSO STS uses this format to record the default fields in each log record. See Table 7-0, "Log Records" for a list of default fields. 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 7-2 Flat File Log Record Example

"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

7.1.3.2 Relational Database Format

When OpenSSO STS uses a relational database to log messages, the messages are stored in a database table. OpenSSO STS uses Java Database Connectivity (JDBC), which provides connectivity to a wide range of databases. (Oracle® and MySQL databases are currently supported.) The following table summarizes the schema for a relational database.

Table 7-2 Relational Database Log Format

Event	Format	Description
TIME	Date (Oracle) DateTime (MySQL)	The format is YYYY-MM-DD HH24:MI:SS (Oracle) or %Y-%m-%d %H:%i:%s (MySQL). The formats are specified in the Logging Service attributes.
DATA	CLOB (Oracle) LONGTEXT (MySQL)	The data type is specified in the Logging Service attributes.
MODULE NAME	VARCHAR(255)	Name of the OpenSSO STS component invoking the log record.
DOMAIN	VARCHAR(255)	OpenSSO STS domain of the user.
LOGLEVELJDK	VARCHAR(255)	JDK 1.4 log level of the log record.
LOGINID	VARCHAR(255)	Login ID of the user who performed the logged operation.
IPADDRESS	VARCHAR(255)	IP Address of the machine from which the logged operation was performed.
LOGGEDBY	VARCHAR(255)	Login ID of the user who writes the log record.
HOSTNAME	VARCHAR(255)	Host name of machine from which the logged operation was performed.
MESSAGEID	VARCHAR(255)	Non-internationalized message identifier for this log record's message.
CONTEXTID	VARCHAR(255)	Identifier associated with a particular login session.

7.2 Configuring Global Logging Attributes

Configuring global attributes in the Logging Service configuration affects logging output. The Log Status can be set to Inactive to disable all logging output. The Logging Level can be set to one of the java.util.logging.Level values other than the default INFO to get more or less detailed logging output.

7.2.1 To Configure Global Logging Attributes

On the Configuration tab, click the System subtab.
On the System Configuration page, in the System Attributes list, click Logging.

Provide values for the Global Logging attributes. The following table provides a listing and descriptions of the attributes you can configure.

Table 7-3 Global Logging Attributes

Attribute	Description
Maximum Log Size	Specify the maximum number of bytes to allow for an OpenSSO STS log file. The default value is 100000000. This attribute applies to only the FILE logging type. When the logging type is set to DB, there are no history files and no size limit explicitly set by OpenSSO STS.
Number of History File	Specify the number of backup log files to be retained for historical analysis. You can enter any integer based on the partition size and available disk space of the local computer system. The default value is 1. Entering a value of 0 is interpreted to be the same as a value of 1. If you specify 0, a history log file will be created. This attribute applies to only the FILE logging type. When the logging type is set to DB, there are no history files and no size limit explicitly set by OpenSSO STS.
Log File Location	Specify a path to a directory where OpenSSO STS log files can be stored. The default location is: OpenSSO-deploy-base/uri/log You can set this value an explicit path, but the base path should be the value of OpenSSO-deploy-base to avoid permissions problems. OpenSSO-deploy-base/uri/log represents the base configuration directory and the OpenSSO STS deployment URI. These are specified during post-installation configuration. At runtime, the Logging service determines the instance's proper directory for logging. If a non-default directory is specified, OpenSSO STS will create the directory if it does not already exist. You must then set the appropriate permissions for that directory. Example: 0700. When configuring the log location for DB (database) logging such as, Oracle or MySQL, part of the log location is case sensitive. For example, if you are logging in to an Oracle database, the log location is case-sensitive as in the following example: jdbc:oracle:thin:@machine.domain:port:DBName To configure logging to DB, add the JDBC driver files to the web container's JVM classpath. You must manually add JDBC driver files to the classpath of the ssoadm script. Otherwise ssoadm logging can not load the JDBC driver. Changes to logging attributes usually take effect after you save them. This does not require you to restart the server. If you are changing to secure logging, however, you should restart the server.
Log Status	Specify whether logging is turned on (ACTIVE) or off (INACTIVE). Value is set to ACTIVE during installation.
Log Record Resolve Host Name	When set to false, host lookups will not be performed to populate the LogRecord's HostName field.
Logging Type	Specify one of the following: File, - for flat file logging DB - for database logging If the Database User Name or Database User Password is invalid, it will seriously affect OpenSSO STS processing. If OpenSSO STS or the console becomes unstable, set the Log Status attribute to Inactive. After you have set the property, restart the server. You can then log in to the console and reset the logging attribute. Then, change the Log Status property to ACTIVE and restart the server.
Database User Name	Specify the name of the user that will connect to the database when the Logging Type attribute is set to DB.
Database User Password	Specify the database user password when the Logging Type attribute is set to DB.
Database User Password (confirm)	Type the Database User Password again to confirm it.
Database Driver Name	Specify the driver used for the logging implementation class.
Configurable Log Fields	Specify the fields that are to be logged. By default, all of the following fields are logged: CONTEXTID DOMAIN HOSTNAME IPADDRESS LOGGED BY LOGINID LOGLEVEL MESSAGEID MODULENAME NAMEID At minimum you should log CONTEXTID, DOMAIN, HOSTNAME, LOGINID and MESSAGEID.
Log Verification Frequency	Specify in seconds the how often the server should verify the logs to detect tampering. The default time is 3600 seconds. This parameter applies to secure logging only.
Log Signature Time	Specify in seconds how often that the log will be signed. The default time is 900 seconds. This parameter applies to secure logging only.
Secure Logging
Secure Logging Signing Algorithm	When enabled, secure logging detects unauthorized changes or tampering of security logs. By default, secure logging disabled. Secure logging can only be used for flat files. This option does not work for Database (DB) logging.
Logging Certificate Store Location	Choose one of the following RSA or DSA encryption signing algorithms. Each has private keys for signing and a public key for verification: MD2 w/RSA MD2 w/RSA SHA1 w/DSA SHA1 w/RSA MD2, MD5 and RSA are one-way hashes. For example, if you select the signing algorithm MD2 w/RSA, the secure logging feature generates a group of messages with MD2 and encrypts the value with the RSA private key. This encrypted value is the signature of the original logged records and will be appended to the last record of the most recent signature. For validation, it well decrypt the signature with the RSA public key and compare the decrypted value to the group of logged records. The secure logging feature will then will detect any modifications to any logged record.
Maximum Number of Records	Specify the maximum number of records that the Java LogReader interfaces should return, regardless of how many records match the read query. By default, it is set to 500. This attribute can be overridden by the caller of the Logging API through the LogQuery class.
Number of Files per Archive	This attribute is applicable to only secure logging. Specify when the log files and keystore must be archived, and the secure keystore regenerated, for subsequent secure logging. The default is five, and means that the log files and keystore are archived after five log files have been created.
Buffer Size	Specify the maximum number of log records to be buffered in memory before the logging service attempts to write them to the logging repository. The default is one record.
DB Failure Memory Buffer Size	Specify the maximum number of log records held in memory if database (DB) logging fails. This attribute is only applicable when DB logging is specified. When the OpenSSO STS Logging service loses connection to the DB, it buffers up to the number of records specified here. The default value is two times of the value defined in the Buffer Size attribute.
Buffer Time	Specify the number of seconds that the log records will be buffered in memory before they are sent to the Logging service to be written. This attribute applies if Time Buffering is ON. The default is 3600 seconds.
Time Buffering	When ON is selected, OpenSSO STS sets a time limit for log records to be buffered in memory before they are written. The amount of time is set in the Buffer Time attribute.
Logging Level	Specify the degree of detail to be contained in all OpenSSO STS log files. The default is the INFO level. FINE, FINER, FINEST provide more detail and more log records. Use the OFF level to turn off logging, which is essentially the same as setting the Log Status attribute to INACTIVE.

Click Save.

7.3 Using OpenSSO STS Component Logs

The log files record a number of events for each of the OpenSSO STS components using the logging service. Administrators typically review these log files on a regular basis. The following table provides a brief description of the log files produced by each OpenSSO STS component.

Table 7-4 OpenSSO STS Component Logs

Component	Log Filename	Description
Session Service	amSSO.access	Session management attributes values such as login time, logout time, and time out limits. Also session creations and terminations.
Administration Console	amConsole.access amConsole.error	User actions performed through the administration console such as creation, deletion and modification of identity-related objects, realms, and policies. amConsole.access logs successful console events while amConsole.error logs error events.
Authentication Service	amAuthentication.access amAuthentication.error	User logins and log outs, both successful and failed.
Federation Services	amFederation.access amFederation.error amLiberty.access amLiberty.error	Federation-related events such as the creation of an authentication domain or the creation of a hosted provider entity.
Policy Service (Authorization)	amPolicy.access amPolicy.error amAuthLog	Events related to authorization such as policy creation, deletion, or modification, and policy evaluation. amPolicy.access logs policy allows, amPolicy.error logs policy error events, and amAuthLog logs policy denies.
Policy Agents	amAgent	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 OpenSSO STS machine in the Authentication logs.
SAML v1.x	SAML.access SAML.error	SAML v1.x-related events such as assertion and artifact creation or removal, response and request details, and SOAP errors.
SAML v2	SAML2.access SAML2.error	SAML v2-related events such as assertion and artifact creation or removal, response and request details, and SOAP errors.
Command Line	amAdmin.access amAdmin.error	Event successes and errors that occur during operations using the command line tools. Loading a service schema, creating policy, and deleting users are some examples of command line operations.
Password Reset	amPasswordReset.access	Password reset events.
Web Services Security	WebServiceSecurity.access	Event successes that occur during operations using the command-line tools.

7.4 Using Secure Logging

Secure logging can only be used for flat files. Secure logging does not work for Database (DB) logging.

Secure logging adds an extra measure of security to the logging service. When secure logging is enabled, the logging service 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 OpenSSO STS. 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.

There are two methods to enable secure logging; through a through a Java Cryptography Extension (JCE) provider and through a Java Security Server (JSS) provider.

7.4.1 To Enable Secure Logging through a JSS Provider

Create a certificate with the name Logger and install it in the key store specified by the Logging Service configuration's Logging Certificate Store Location.

The key store's password is expected to be the same as the top-level administrator password. The default location set during OpenSSO STS configuration is ConfigurationDirectory/uri/Logger.jks/, where ConfigurationDirectory is the configuration directory, and uri is the OpenSSO deployment URI specified during OpenSSO configuration. These tags are interpreted at run time. Each deployed OpenSSO instance has its own key store. It is particularly useful when there are multiple OpenSSO instances per system.
Turn on Secure Logging in the logging service configuration using the OpenSSO STS administration console and save the change. See Section 7.2, "Configuring Global Logging Attributes."The administrator can also modify the default values for the other logging service attributes.

If the logging directory is changed from the default /log directory, make sure that the directory is writable by the user ID and that the OpenSSO STS's web application is running. Also set the directory's permissions to 0700, as the logging service will create the directory, if it does not exist, with permissions set to 0755.
Verify Secure Log Archives.

To detect unauthorized changes or tampering of the secure logs, look for error messages that are written by the Logging Service's periodic verification process to ConfigurationDirectory/uri/debug/amLog. To manually check for tampering, run the amverifyarchive command-line utility, which is included in the ssoAdminTools.zip file.
Changing from a JCE Provider to a JSS Provider

The default secure log helper provider is the JCE provider, com.sun.identity.log.secure.impl.SecureLogHelperJCEImpl, as specified by the iplanet-am-logging-secure-log-helper attribute in the iPlanetAMLoggingService's schema. Refer to the opensso/xml/amLogging.xml file from the opensso.zip file.

7.4.2 To Change from a JCE Provider to a JSS Provider

The default secure log helper provider is the JCE provider, com.sun.identity.log.secure.impl.SecureLogHelperJCEImpl, as specified by the iplanet-am-logging-secure-log-helper attribute in the iPlanetAMLoggingService's schema. Refer to the opensso/xml/amLogging.xml file from the opensso.zip file.

Execute the following ssoadm command:

./ssoadm set-attr-defs --servicename iPlanetAMLoggingService --schematype global --attributevalues iplanet-am-logging-secure-log-helper-class-name= com.sun.identity.log.secure.SecureLogHelperJSSImpl --adminid amadmin --password-file amadminpass

Verify the change:

./ssoadm get-attr-defs --servicename iPlanetAMLoggingService --attributenames iplanet-am-logging-secure-log-helper-class-name --schematype global --adminid amadmin --password-file amadminpass

7.5 Using Database Logging

This feature provides logging to Oracle or MySQL databases. No special coding is required to enable this feature.

The DB Failure Memory Buffer Size specifies how many records per table to buffer if the connection to the database fails. If more records are queued before the connection is reestablished, older records will be discarded.

The ssoadm command line interface cannot log to the database directly. In addition to adding the JDBC driver to the web application's classpath, remove -D"com.sun.identity.log.dir=the_specified_log_dir.

7.5.1 To Enable Database Logging

On the Configuration tab, click the System subtab.
On the System Configuration page, in the System Attributes list, click Logging.
Set the Logging Type to DB.
Set the Database User Name, Database User Password, and Database Driver Name.
- For Oracle, the default driver name set is oracle.jdbc.driver.OracleDriver.
- For MySQL, it is typically com.mysql.jdbc.Driver.
Specify values for other fields.

See Section 7.2.1, "To Configure Global Logging Attributes."

Be sure to put the JDBC driver's .zip or .jar file in the OpenSSO STS web application's classpath (for example, WEB-INF/lib or jre/lib/ext).