Sun Java System Access Manager 6 2005Q1 Developer's Guide |
Chapter 12
Auditing FeaturesSun Java System Access Manager 6 2005Q1 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 OverviewThe Logging Service enables all Access Manager 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, Access Manager traffic patterns and authorization violations. As with all Access Manager 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.
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 Access Manager. 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 Access Manager SDK loads the configuration data (stored in Directory Server) into the Logging Service when Access Manager 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 12-1 illustrates the architecture of the Logging Service.
Figure 12-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 Access Manager 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 8, "Service Management." Specific information on the Logging Service attributes can be found in the Logging Service Attributes chapter in the Sun Java System Access Manager Administration Guide.
Log FilesThe 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. The log file directory can be configured in the Logging Service by using the Access Manager console.
Table 12-1 describes the files in the logs directory. Note that in database formats, the period (.) separator is converted to an underscore ( _ ). 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.
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 Access Manager 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 Access Manager 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 8, "Service Management."
Log File Formats
Access Manager 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 12-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.
Relational Database Format
For Java applications using a relational database to log messages, the message is stored in a database table. Access Manager 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 12-2 contains the schema for a relational database.
Table 12-2 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 Access Manager service invoking the log record.
DOMAIN
VARCHAR2(255)
Access Manager 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 Access Manager Logging Service and the driver variable in the database itself need to be modified. Using the Access Manager 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 Access Manager 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 Access Manager 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 Access Manager is installed via Java Enterprise System (JES), the events are recorded by the JES installer. The four installation logs are:
Access Manager 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 Service.
Session Logs
The Logging Service records the following events for the Session Service:
The session logs are prefixed with amSSO.
Console Logs
The Access Manager 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 12-2 is a collection of sample records that might appear in the policy logs.
Code Example 12-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 Access Manager machine in the Authentication Logs. For more information on this function, see the correct documentation for the policy agent in question.
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 FeaturesThe 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 generated 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:
- Create a certificate with the name Logger and install it in the deployment container running Access Manager.
Refer to the documentation that comes with the deployment container for details.
- Turn on Secure Logging in the Logging Service configuration using the Access Manager console and save the change.
The administrator can also modify the default values for the other attributes in the Logging Service.
- Create a file in the IdentityServer_base/SUNWam/config directory that contains the certificate database password and name it .wtpass.
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.
- 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 Java System Access Manager Administration Guide.
Remote Logging
Access Manager supports remote logging. This allows a client using the Access Manager SDK to create log records on an instance of Access Manager deployed on a remote machine.
Using Remote Logging
Remote logging can be initiated in any of the following scenarios:
- When the logging URL in the Naming Service of one Access Manager instance points to a remote instance and there is a trust relationship configured between the two, logs will be written to the remote Access Manager instance.
- When the Access Manager SDK is installed against a remote Access Manager instance and a client (or a simple Java class) running on the SDK server uses the logging APIs, the logs will be written to the remote Access Manager machine.
- When logging APIs are used by Access Manager agents.
Enabling Remote Logging
To enable remote logging, ensure that the following information is regarded.
- If using Sun Java System Web Server, the following environment variables need to be set in the server.xml configuration file.
- java.util.logging.manager=com.sun.identity.log.LogManager
- java.util.logging.config.file=/IdentityServer_base/SUNwam/lib/LogConfig.properties
- If the Java 2 Platform, Standard Edition being used is 1.4 or later, this is accomplished by invoking the following at the command line:
java -cp /IdentityServer_base/SUNWam/lib/am_logging.jar:/IdentityServer_base/SUNWam/lib/xercesImpl.jar:/IdentityServer_base/SUNWam/lib/xmlParserAPIs.jar:/IdentityServer_base/SUNWam/lib/jaas.jar:/IdentityServer_base/SUNWam/lib/xmlParserAPIs.jar:/IdentityServer_base/SUNWam/lib/servlet.jar:/IdentityServer_base/SUNWam/locale:/IdentityServer_base/SUNWam/lib/am_services.jar:/IdentityServer_base/SUNWam/lib/am_sdk.jar:/IdentityServer_base/SUNWam/lib/jss311.jar:/IdentityServer_base/SUNWam/lib:.
-Djava.util.logging.manager=com.sun.identity.log.LogManager
-Djava.util.logging.config.file=/IdentityServer_base/SUNwam/lib/LogConfig.properties <logTestClass>
- If the Java 2 Platform, Standard Edition being used is earlier than 1.4, this is accomplished by invoking the following at the command line:
java -Xbootclasspath/a:/IdentityServer_base/SUNWam/lib/jdk_logging.jar -cp /IdentityServer_base/SUNWam/lib/am_logging.jar:/IdentityServer_base/SUNWam/lib/xercesImpl.jar:/IdentityServer_base/SUNWam/lib/xmlParserAPIs.jar:/IdentityServer_base/SUNWam/lib/jaas.jar:/IdentityServer_base/SUNWam/lib/xmlParserAPIs.jar:/IdentityServer_base/SUNWam/lib/servlet.jar:/IdentityServer_base/SUNWam/locale:/IdentityServer_base/SUNWam/lib/am_services.jar:/IdentityServer_base/SUNWam/lib/am_sdk.jar:/IdentityServer_base/SUNWam/lib/jss311.jar:/IdentityServer_base/SUNWam/lib:.
-Djava.util.logging.manager=com.sun.identity.log.LogManager
-Djava.util.logging.config.file=/IdentityServer_base/SUNwam/lib/LogConfig.properties <logTestClass>
- Ensure that the following parameters are configured in LogConfig.properties located in IdentityServer_base/SUNWam/lib.
- iplanet-am-logging-remote-handler=com.sun.identity.log.handlers.RemoteHandler
- iplanet-am-logging-remote-formatter=com.sun.identity.log.handlers.RemoteFormatter
- iplanet-am-logging-remote-buffer-size=1
Remote logging supports buffering on the basis of the number of log records. This value defines the log buffer size by the number of records. Once the buffer is full, all buffered records will be flushed to the server.
- iplanet-am-logging-buffer-time-in-seconds=3600
This value defines the time-out period in which to invoke the log buffer-cleaner thread.
- iplanet-am-logging-time-buffering-status=OFF
This value defines whether log buffering (and the buffer-cleaner thread) is enabled or not. By default this feature is turned off.
Logging APIThe Logging API provides log management tools for all Access Manager services as well as providing a set of Java classes for external applications to create, retrieve, submit, or delete log information. The Access Manager 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 must be set in the executable for an application that is using the Logging Service. You can determine how to set the variables depending upon three things:
If Client Can Execute in the Local Access Manager Server
When the client application can execute in either the local Access Manager server JVM or in a remote server JVM, choose one of the following two configurations:
If Client Executes Only in a Remote Server
When the client application can execute only in a remote server JVM, choose one of the following two configurations:
- If it is acceptable for the native LogManager class to be overridden by the Access Manager LogManager class in the JDK1.4 environment, then follow these steps:
- Set the following variables:
-Djava.util.logging.manager=com.sun.identity.log.LogManager
-Djava.util.logging.config.file=/IdentityServer_base/SUNwam/lib/
LogConfig.properties- In LogConfig.properties, or in the logging.properties file supplied by JDK, set the following properties:
iplanet-am-logging-remote-handler=com.sun.identity.log.handlers.
RemoteHandleriplanet-am-logging-remote-formatter=com.sun.identity.log.
handlers.RemoteFormatteriplanet-am-logging-remote-buffer-size=1
iplanet-am-logging-buffer-time-in-seconds=3600
iplanet-am-logging-time-buffering-status=OFF
- If you are using JDK1.3, add the following:
-Xbootclasspath/a:/IdentityServer_base/SUNWam/lib/
jdk_logging.jar
- If it is not acceptable for the native LogManager class to be overridden by the Access Manager LogManager class in the JDK1.4 environment, then follow these steps:
- Set the following variables:
-DLOG_COMPATMODE=Off
-Ds1is.java.util.logging.config.file=/IdentityServer_base/
SUNwam/lib/LogConfig.properties- In LogConfig.properties, or in the logging.properties file supplied by JDK, set the following properties:
iplanet-am-logging-remote-handler=com.sun.identity.log.handlers.
RemoteHandleriplanet-am-logging-remote-formatter=com.sun.identity.log.
handlers.RemoteFormatteriplanet-am-logging-remote-buffer-size=1
iplanet-am-logging-buffer-time-in-seconds=3600
iplanet-am-logging-time-buffering-status=OFF
- If you are using JDK1.3, add the following:
-Xbootclasspath/a:/IdentityServer_base/SUNWam/lib/
jdk_logging.jarThe Client SDK APIs use this logging configuration by default. In this case, the Logging API will configure a remote handler for all logs. Note that access to the Directory Server is not required in this case.
If SSL is Enabled
If SSL is enable and uses JSS for Access Manager, set the following paramter:
-D"java.protocol.handler.pkgs=com.iplanet.services.comm"
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 record (LogRecord) 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.
- Logger.log(logRecord, String credential) had been added to call the authorization hook. The credential is accepted as a ssoToken string. The default authorization hook checks validitity of the ssoToken. Data is not logged at all if this check fails.
- Logger.log(logRecord) simply calls Logger(logRecord, String cred) with credential value of null. And thus the default authorization check does not allow logging when an application uses this interface.
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
Access Manager 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
Access Manager provides Logger.flush() to expunge all the cached log records.
Sample Logging Code
Code Example 12-3 provides sample code to illustrate one way in which the logging API can be used to write Access Manager records.
Code Example 12-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 SPIThe 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.
- Implement the com.sun.identity.log.spi.IVerifierOutput interface with the desired functionality.
- Add the implementing class in the classpath of Access Manager.
- 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.
There are several ways to accomplish this. For example:
- 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 Access Manager to this role.
- Instantiate a PolicyEvaluator and call PolicyEvaluator.isAllowed(ssotoken, logname);. This entails defining a policy XML to model log access and registering it with Access Manager.
In general:
Debug FilesThe 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.
- Off—No debug information is recorded.
- Error—This level is used for production. During production, there should be no errors in the debug files.
- Warning—Currently, using this level is not recommended.
- Message—This level alerts to possible issues using code tracing. Most Access Manager modules use this level to send 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:
- Writing a custom authentication module.
- Writing a custom application using the Access Manager SDKs. The amProfile and amSDK debug files capture this information.
- Troubleshooting access permissions while using the console or SDK. The amProfile and amSDK debug files also capture this information.
- Troubleshooting SSL.
- Troubleshooting the LDAP authentication module. The amAuthLDAP debug file captures this information.
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 Access Manager Instances And Debug Files
Access Manager 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 Java System Access Manager Administration Guide.