Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Identity Server Customization and API Guide

Chapter 10
Auditing Features

Sun™ ONE Identity Server provides a Logging Service to record information such as user activity, traffic patterns, and authorization violations. The Logging API allow external applications to take advantage of the Logging Service. In addition, the debug files allow administrators to troubleshoot their installation. This chapter explains these auditing features. It contains the following sections:

Logging Service Overview

The Logging Service enables all Identity Server services to record information that might be useful to the administrator in one centralized location. The information may include access denials and approvals, authorization violations and code exceptions. Logging 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 service 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). The default location for all log files is /var/opt/SUNWam/logs.

Note

This default log directory can be reconfigured after installation by modifying the Log Location attribute in the Logging Service. More information can be found in the Logging Service Attributes chapter in the Sun ONE Identity Server Administration Guide..

Logging Architecture

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 Identity Server. An application accesses the Logging Service by calling the Logging API. (If remote, the API uses a XML over HTTP layer to send the logging request to the Logging Service.) The Identity Server SDK loads the configuration data (stored in Directory Server) into the Logging Service when Identity Server starts up or when any logging configuration data is changed via the console. This data includes the log message format, log file name, maximum log size, and the number of history files. Any exception message will be logged, based on the configuration values. Figure 10-1 illustrates the architecture of the Logging Service.

Figure 10-1  Logging Service Architecture

amLogging.xml

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 /etc/opt/SUNWam/config/xml. These values are applied across the Identity Server deployment and inherited by every configured organization. The structure of amLogging.xml is defined by the sms.dtd. Information on this document can be found in "The sms.dtd Structure" of Chapter 6, "Service Management." Specific information on the Logging Service attributes can be found in the Logging Service Attributes chapter in the Sun ONE Identity Server Administration Guide.

Log Files

The log files record a number of events for each of the services it monitors. These files should be checked by the administrator on a regular basis. The default directory for the log files is /var/opt/SUNWam/logs.

Note

The log file directory can be configured in the Logging Service via the Identity Server console.

Recorded Events

The Logging Service logs information passed to the LogRecord class by the client. Out-of-the-box, the contents of the LogRecord that will be logged are:

Time

This record is the date (YYYY-MM-DD) and time (HH:MM:SS) at which the log message was recorded.

Data

This record details the description of the user activity, errors or other useful information which the application wants to log.

ModuleName

This record is the name of the Identity Server service or application being logged. Additional information on the value of this field can be found in "Adding Log Data".

Domain

This field records the Identity Server domain to which the user belongs.

Log Level

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

Login ID

This field is the ID of the user attempting to access the application. The information (the user to whom the log information belongs) is taken from the session token.

IP Address

This field records the IP address from which the operation was performed.

Logged By

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

Host Name

This field is the host name from which the operation was performed.

Additional fields can also be logged. The new field names must first be added to the amLogging.xml service file and the modified service file then reloaded into the Directory Server. The new values for these fields would then be included in the LogRecord Class passed to the Logging Service. More information on how to modify and load an XML service file can be found in "Defining A Custom Service" of Chapter 6, "Service Management."

Note

Only the flat file format can accomodate new logging fields. Other formats might contain steps not documented here. An example would be the database table where a new column must also be added to the table.

Log File Formats

Identity Server can record events in flat text files or a relational database. (The JDK SPI allows extending existing handlers or adding new ones.)

Flat File Format

The default flat file format is the W3C Extended Log Format (ELF). In leveraging this format, the Logging Service records the default logging fields in each log record. Code Example 10-1 illustrates an authentication log record formatted for a flat file. In order, the fields for these values are TIME, DATA, MODULENAME, DOMAIN, LOGLEVEL, LOGINID, IPADDR, LOGGEDBY, and HOSTNAME.

Code Example 10-1  Flat File Record From amAuthentication.access

"08-07-2003 07:58:26" "Login Success service->adminconsoleservice" LDAP dc=example,dc=com INFO uid=amAdmin,ou=People,dc=example,dc=com 129.149.247.58 "cn=dsameuser,ou=DSAME Users,dc=example,dc=com" cache1nwk.SFBay.Sun.COM

Relational Database Format

For Java 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 the data. OracleŽ and MySQL databases are currently supported.

Note

JDBC technology is an API for accessing tabular data source using Java. It provides connectivity to a wide range of SQL databases, and access to other tabular data sources, such as spreadsheets or flat files.

Table 10-1 contains the schema for a relational database.

Table 10-1  Relational Database Log Format 

Column Name

Data Type

Description

TIME

VARCHAR2(30)

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

DATA

VARCHAR2(1024)

The log message itself.

MODULENAME

VARCHAR2(255)

The name of the Identity Server service invoking the log record.

DOMAIN

VARCHAR2(255)

Identity Server domain of the user.

LOGLEVEL

VARCHAR2(255)

JDK 1.4 log level of the log record.

LOGINID

VARCHAR2(255)

Login ID of the user who performed the logged operation.

IPADDR

VARCHAR2(255)

IP Address of the machine from which the logged operation was performed.

LOGGEDBY

VARCHAR2(255)

Login ID of the user who writes the log record.

HOSTNAME

VARCHAR2(255)

Host name of machine from which the logged operation was performed.

Oracle Database

In order to log to an Oracle database, the Log Location attribute in the Identity Server Logging Service and the driver variable in the database itself need to be modified. Using the Identity Server console, change the value of the Log Location attribute to:

jdbc:oracle:thin:@hostname:1521:database_name

In the database itself, change the value for the driver to:

oracle.jdbc.driver.OracleDriver

MySQL Database

In order to log to an MySQL database, the Log Location attribute in the Identity Server Logging Service and the driver variable in the database itself need to be modified.

Note

There is a limitation in the data length for MySQL JDBC logging as MySQL does not support data of more than 255 characters.

Using the Identity Server console, change the value of the Log Location attribute to:

jdbc:mysql://hostname:port/database_name

In the database itself, change the value for the driver to:

com.mysql.jdbc.Driver

Caution

When MySQL is installed on Solaris or other Unix platforms and modifications are made to the Logging Service, logging into the MySQL database shows the warning message Syntax error or access violation.

Java Enterprise System Installation Logs

Events recorded during installation are stored in /var/sadm/install/logs. As Identity Server is installed via Java Enterprise System (JES), the events are recorded by the JES installer. The four installation logs are:

Identity Server Service Logs

There are two different types of service log files: access and error. Access log files record general auditing information concerning the deployment (successful or failed authentications, new federations, etc.). Error log files record errors that occur within the application. 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 would be named amConsole.access while a database column logging the same events would be called AMCONSOLE_ACCESS. The following sections describe the log files recorded by the Logging Sevice.

Session Logs

The Logging Service records the following events for the Session Service:

The session logs are prefixed with amSSO.

Console 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 console logs are prefixed with amConsole.

Authentication Logs

The Authentication component logs user logins and logouts. The authentication logs are prefixed with amAuthentication.

Federation 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 federation logs are prefixed with Federation.

Policy Logs

The Policy component records policy-related events including, but not limited to, policy administration (policy creation, deletion and modification) and policy evaluation. The policy logs are prefixed with amPolicy. Code Example 10-2 is a collection of sample records that might appear in the policy logs.

Code Example 10-2  Sample Policy Log Records 

#Fields: time Data ModuleName Domain LogLevel LoginID

IPAddr LoggedBy HostName

"08-07-2003 11:08:19" "Created policy test successfully in

Organization dc=iplanet,dc=com" amPolicy.access "Not Available"

INFO uid=amAdmin,ou=People,dc=iplanet,dc=com /192.18.120.236

uid=amAdmin,ou=People,dc=iplanet,dc=com 192.18.120.236

"08-07-2003 11:08:55" "Modified policy test successfully in

Organization dc=iplanet,dc=com" amPolicy.access "Not Available"

INFO uid=amAdmin,ou=People,dc=iplanet,dc=com /192.18.120.236

uid=amAdmin,ou=People,dc=iplanet,dc=com 192.18.120.236

"08-07-2003 11:09:05" "Removed policy test successfully in

Organization dc=iplanet,dc=com" amPolicy.access "Not Available"

INFO uid=amAdmin,ou=People,dc=iplanet,dc=com /192.18.120.236

uid=amAdmin,ou=People,dc=iplanet,dc=com 192.18.120.236

"08-07-2003 11:15:43" "Policy Evaluation result of Policy test in

Organization dc=iplanet,dc=com for service iPlanetAMWebAgentService,

resource http://moonshadow.red.iplanet.com:80/*.html and action names

[GET, POST] is GET=[allow]\\n." amPolicy.access "Not Available" INFO

uid=amAdmin,ou=People,dc=iplanet,dc=com /192.18.120.236

uid=amAdmin,ou=People,dc=iplanet,dc=com 192.18.120.236

Agent Logs

The policy agent logs are responsible for logging exceptions regarding log resources that were either allowed or denied to a user. The agent logs are prefixed with amAgent. amAgent logs reside on the agent server only. Agent events are logged on the Identity Server machine in the Authentication Logs. For more information on this function, see the correct documentation for the policy agent inquestion.

SAML Logs

The SAML component records SAML-related events including, but not limited to, assertion and artifact creation or removal, response and request details, and SOAP errors. The session logs are prefixed with amSAML.

amAdmin Logs

The command line logs record event errors that occur during operations using the command line tools. These include, but are not limited to, loading a service schema, creating policy and deleting users. The command line logs are prefixed with amAdmin. More information can be found in "Command Line Logging".

Logging Features

The Logging Service has a number of special features which can be enabled for additional functionality. They include To Enable Secure Logging, Command Line Logging and Remote Logging.

To Enable Secure Logging

This optional feature adds additional security to the logging function. Secure Logging enables detection of unauthorized changes to, or tampering of, the security logs. No special coding is required to leverage this feature. Secure Logging is accomplished by using a pre-registered certificate configured by the system administrator. This Manifest Analysis and Certification (MAC) is generarated and stored for every log record. A special “signature” log record is periodically inserted that represents the signature for the contents of the log written to that point. The combination of the two records ensures that the logs have not been tampered with. Secure Logging can be enabled by performing the following steps:

  1. Create a certificate with the name Logger and install it in the deployment container running Identity Server.

    2. Refer to the documentation that comes with the deployment container for details.

  2. Turn on Secure Logging in the Logging Service configuration using the Identity Server console and save the change.

    3. The administrator can also modify the default values for the other attributes in the Logging Service.

  3. Create a file in the IdentityServer_base/SUNWam/config directory that contains the certificate database password and name it .wtpass.

    4. Note

    The file name and the path to it is configurable in the AMConfig.properties file. For more information see the "Certificate Database" of Appendix A, "AMConfig.properties File."

    Ensure that the deployment container user is the only administrator with read permissions to this file for security reasons.

  4. Restart the server after making these changes.

Command Line Logging

The amadmin command line tool has the ability to create, modify and delete identity objects (organizations, users, and roles, for example) in Directory Server. This tool can also load, create, and register service templates. The Logging Service can record these command line actions by invoking the -t option. If the com.iplanet.am.logstatus property in AMConfig.properties is enabled (ACTIVE) then a log record will be created. (This property is enabled by default.) The command line logs are prefixed with amAdmin. More information can be found in Chapter 8, “The amadmin Command Line Tool” in the Sun ONE Identity Server Administration Guide.

Remote Logging

Identity Server supports remote logging. This allows a client using the Identity Server SDK to create log records on an instance of Identity Server deployed on a remote machine.

Using Remote Logging

Remote logging can be initiated in any of the following scenarios:

Enabling Remote Logging

To enable remote logging, ensure that the following information is regarded.

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. The Identity Server Logging API extend the core logging API in the Java™ 2 Standard Edition Development Kit (JDK) 1.4. Only the Logger and LogRecord classes are enhanced. They are contained in the package com.sun.identity.log.

Tip

An overview of the JDK 1.4 logging function can be found at http://java.sun.com/j2se/1.4.1/docs/guide/util/logging/overview.html The Javadocs for the JDK 1.4 logging API themselves can be found at http://java.sun.com/j2se/1.4.1/docs/api/java/util/logging/package-summary.html.

Setting Environment Variables

The following shared library environment variables need to be set in the executable for an application that is using the Logging Service.

If SSL is enabled for Identity Server, the following parameter also needs to be added:

Logger Class

This Logger class provides the methods for applications to use in creating log files and writing log information to them.

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. The ssoToken is passed to the logRecord constructor and used to populate the log fields discussed in "Recorded Events". The session token passed during the logger.log(logRecord, ssoToken) log request is used to authorize the user. The user can only log with a valid ssoToken.

Adding Log Data

The following sections illustrate ways to use the Logging API for adding log file information.

Adding ModuleName Data

The ModuleName value can be added to a log file using the logRecord.addLogInfo(key, value) API. If a module name is not added, the name of the log will be used to populate this field. For example, authentication information is logged in the amAuthentication.access file using an internal session token ("dsameuser" ssoToken). If user Joe123 attempts to authenticate, the LoginID will be Joe123, and the LoggedBy user will be dsameuser.

Note

The LoggedBy entry is populated from the SSOToken passed during logger.log(logRecord, ssoToken) call.

If the authentication module information (such as LDAP, Membership, etc.) is not added by the APIs, amAuthentication.access will be the value of the ModuleName field.

Adding Log Level Data

A LogLevel is passed in the LogRecord constructor using the following code:

LogRecord(Level level, String msg)

While using the logging APIs, any JDK 1.4 defined log levels can be passed.

Caching Log Records

Identity Server supports log record caching both locally and remotely based on the configurable buffering properties discussed in "Remote Logging". Caching is supported for either type of log file although not when secure logging is enabled.

Flushing Log Records

Identity Server provides Logger.flush() to expunge all the cached log records.

Sample Logging Code

Code Example 10-3 provides sample code to illustrate one way in which the logging API can be used to write Identity Server records.

Code Example 10-3  Logging API Samples

Logger logger = Logger.getLogger("SampleLogFile");

// Creates the file or table in the LogLocation specified in the amLogging.xml and returns the Logger object.

LogRecord lr = new LogRecord(Level.INFO, "SampleData", ssoToken);

// Creates the LogRecord filling details from ssoToken.

logger.log(lr,ssoToken);

// Writes the info into the backend file, db or remote server.

Logging SPI

The Logging SPI are Java packages that can be used to develop plug-ins for customized features. The SPI are organized in the com.sun.identity.log.spi package. More information on the SPI can be found in the Javadocs located at IdentityServer_base/SUNWam/docs.

Log Verifier Plugin

If secure logging is enabled, the log files are verified periodically to detect any attempt of tampering. If tampering is detected, the action taken can be customized by following the steps below.

  1. Implement the com.sun.identity.log.spi.IVerifierOutput interface with the desired functionality.
  2. Add the implementing class in the classpath of Identity Server.
  3. Modify the property iplanet-am-logging-verifier-action-class in the /etc/opt/SUNWam/config/xml/amLogging.xml file with the name of the new class.

Log Authorization Plugin

The Logging Service allows a class to be plugged in that will determine whether a LogRecord is logged or discarded based on the authorization of the owner of the session token performing the event.

Note

The IAuthorizer interface accepts a SSOToken and the logrecord being written.

There are several ways to accomplish this. For example:

  1. Get the applicable role or DN of the user from the SSOToken and check it against a pre-configured (or hardcoded) list of roles/users that are allowed access. The administrator must configure a role and assign all policy agents and entities (for example, applications) that can possibly log to Identity Server to this role.
  2. Instantiate a PolicyEvaluator and call PolicyEvaluator.isAllowed(ssotoken, logname);. This entails defining a policy XML to model log access and registering it with Identity Server.

In general:

  1. Implement the com.sun.identity.log.spi.IAuthorizer interface with the desired functionality.
  2. Add the implementing class in the classpath of Identity Server.
  3. Modify the property iplanet-am-logging-authz-class in the /etc/opt/SUNWam/config/xml/amLogging.xml file with the name of the new class.

    4. Note

    The Identity Server Javadocs can be accessed from any browser by copying the complete IdentityServer_base/SUNWam/docs/ directory into the IdentityServer_base/SUNWam/public_html directory and pointing the browser to http://identity_server_host.domain_name:port/docs/index.html.

Debug Files

The debug files are not a feature of, nor generated by, the Logging Service. They are written using different APIs which are independent of the logging APIs. 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 IdentityServer_base/SUNWam/lib/ directory. For more information on the debug properties, see Appendix A, "AMConfig.properties File."

Debug Levels

There are several levels of information that can be recorded to the debug files. The debug level is set using the com.iplanet.services.debug.level property in AMConfig.properties.

  1. Off—No debug information is recorded.
  2. Error—This level is used for production. During production, there should be no errors in the debug files.
  3. Warning—Currently, using this level is not recommended.
  4. Message—This level alerts to possible issues using code tracing. Most Identity Server modules use this level to send debug messages.

    5. Caution

    Warning and Message levels should not be used in production. They cause severe performance degradation and an abundance of debug messages.

Debug Output Files

A debug file does not get created until a module writes to it. Therefore, in the default error mode no debug files may be generated. The debug files that get created on a basic login with the debug level set to message include:

The most often used files are the amSDK, amProfile and all files pertaining to authentication. The information captured includes the date, time and message type (Error, Warning, Message).

Using Debug Files

The debug level, by default, is set to error. The debug files might be useful to an administrator when they are:

The debug files should go hand in hand with any troubleshooting guide we might have in the future. For example when SSL fails, someone might turn on debug to message and look in the amJSS debug file for any specific cert errors.

Multiple Identity Server Instances And Debug Files

Identity Server contains the ammultiserverinstall script that can be used to configure numerous instances of the server. If the multiple server instances are configured to use different debug directories, each individual instance has to have both read and write permissions to the debug directories. More information on the ammultiserverinstall script can be found in the Sun ONE Identity Server Administration Guide.



Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.