test

Sun OpenSSO Enterprise 8.0 Administration Guide

Chapter 14 Logging Service

OpenSSO Enterprise provides a Logging Service to record information such as user activity, traffic patterns, and authorization violations. In addition, the debug files allow administrators to troubleshoot their installation.

Log Files

The log files record a number of events for each of the 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, such that 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 Enterprise console or ssoadm command-line utility. An absolute path may also be configured as the log file directory.

See Chapter 15, Recording Events with the Logging Service, in Sun OpenSSO Enterprise 8.0 Technical Overview for a detailed list of the default log file types, the information that is recorded, and log file formats.

For attribute definitions for the Logging Service, see the online help by clicking the Help button in the OpenSSO Enterprise Console or Logging in Sun OpenSSO Enterprise 8.0 Administration Reference.

OpenSSO Enterprise Logs

There are two different types of service log files: access and error. Access log files may contain records of action attempts and successful results. Error log files record errors that occur within the OpenSSO Enterprise services. 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. 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 OpenSSO Enterprise console logs record the creation, deletion, and modification of identity-related entities, policies, and services including, among others, realms, users, policies, and groups. It also records modifications of user attributes including passwords and the addition of users to or removal from groups. Additionally, the console logs record delegation and data store activities. The console logs are prefixed with amConsole.

Authentication Logs

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 a circle of trust and the creation of a Hosted Provider. The federation logs are prefixed with amFederation.

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.

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 OpenSSO Enterprise server in the Authentication Logs. For more information on this function, see the 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.

ssoadm Logs

The ssoadm logs record events that occur during operations using the ssoadm command line tool. These include operations that have OpenSSO administration console equivalents. The ssoadm command line logs are located in the logging directory specified when running the setup script for the administration tools unzipped from ssoAdminTools.zip. The main logs are prefixed with ssoadm; other task-related log files are also have access and error suffixes.

Logging Features

The Logging Service has a number of special features which can be enabled for additional functionality.

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 preregistered certificate configured by the system administrator. A 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. 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.

Note –

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

ProcedureTo Enable Secure Logging through a JSS Provider

  1. 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 Enterprise configuration time is ConfigurationDirectory/uri/Logger.jks/, 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, such that each deployed OpenSSO instance has its own key store. It is particularly useful when there are multiple OpenSSO instances per system. Information on getting certificates can be found in Obtaining Secure Socket Layer Certificates in Deployment Example: Single Sign-On, Load Balancing and Failover Using Sun OpenSSO Enterprise 8.0.

  2. Turn on Secure Logging in the Logging Service configuration using the OpenSSO Enterprise administration console and save the change. 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 Enterprise'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.

  3. 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.

  4. 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.

    To change to the JSS provider, use the ssoadm command-line utility:

    ./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

    To 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

Logging Level Attributes and Properties

There are attributes in the Logging Service configuration that affect 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.

Additionally, an individual log file's logging level can be specified in the Configuration > Servers and Sites > server-name > Advanced page. For a given log file, for exampleamSAML.access, add a property name, iplanet-am-logging.amSAML.access.level with Property Value FINER (or any of the java.util.logging.Levelvalues). The logging level specified here for the log file will take precedence over the Logging Service's Logging Level setting.

Database Logging

This feature provides logging to Oracle or MySQL databases. No special coding is required to enable this feature. In the Logging Service configuration (Configuration > System > Logging), set the Logging Type to DB, set the Database User Name, Database User Password, and Database Driver Name. oracle.jdbc.driver.OracleDriver is the default driver name set for Oracle. For MySQL, it is typically com.mysql.jdbc.Driver. Be sure to put the JDBC driver's .zip or .jar file in the OpenSSO Enterprise web application's classpath (for example, WEB-INF/lib or jre/lib/ext).

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.

Note –

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>.

Remote Logging

OpenSSO Enterprise supports remote logging. This allows a remote client application using the OpenSSO client SDK, or another OpenSSO Enterprise server (in the same Site) to use an OpenSSO Enterprise server's Logging Services.

Remote Client Logging

A remote client using the OpenSSO Enterprise client SDK may log to an OpenSSO Enterprise server. For example, the OpenSSO Enterprise client sdk samples refer to the samples/sdk/resources/AMConfig.properties set up by the samples/sdk/scripts/setup.sh script. In particular, the com.iplanet.am.naming.url property's value points to the target OpenSSO Enterprise server's Naming service, which provides the location of the Logging Service. In order for the remote client to successfully log to the target OpenSSO Enterprise server, the entity making the logging request must have Log Writing permission on the target OpenSSO Enterprise server.

Remote OpenSSO Enterprise Server Logging

Another OpenSSO Enterprise server may use an OpenSSO Enterprise server's Logging Services if both are in the same Site. The remote OpenSSO Enterprise server sets its Logging Service URL in the administration console (Configuration > System > Naming) to the target OpenSSO Enterprise server's Logging Service, by changing the attribute's protocol, host, port, and uri values accordingly. Logginservice does not usually need to be changed.

Debug Files

The debug files are not a feature of the Logging Service. They are written using different APIs which are independent of the logging APIs. Debug files are stored in ConfigurationDirectory/uri/debug. This location, along with the level of the debug information, is configurable through the OpenSSO Enterprise Console. Go to Configuration > Sites and Servers >server-name > General and edit the Debug Directory attribute.

Debug Levels

There are several levels of information that can be recorded to the debug files. The debug level is set using the Debug Level attribute located at Configuration > Sites and Servers >server-name > General.

  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: This level allows Error and Warning debug messages to be written.

  4. Message: This level allows detailed code tracing.

    Note –

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

Debug Output Files

By default there are separate debug files, corresponding to the major service components of OpenSSO Enterprise:

Debug output can be combined into one file through the administration console (Configuration > Sites and Servers > server-name > General. Turn the Merge Debug Files attribute to ON.