Skip Headers
Oracle® Fusion Middleware Administrator's Guide for Oracle Access Manager with Oracle Security Token Service
11g Release 1 (11.1.1)

Part Number E15478-09
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

23 Logging Component Event Messages

Logging is the mechanism by which components write messages to a file. Administrators can use the logging mechanism to capture critical component events. Oracle Access Manager and Oracle Security Token Service components use the same logging infrastructure and guidelines as any other component in Oracle Fusion Middleware 11g. This is accomplished by using the package java.util.logging, which is standard and available in all Java environments. The logging system writes output to flat files only. Logging to an Oracle Database instance is not supported.

Configuring logging and locating log files are the focus of this chapter. Diagnosing problems using the information in log files is outside the scope of this manual.

Note:

Unless explicitly stated, information in this chapter is the same whether you are using Oracle Access Manager alone or with Oracle Security Token Service.

This chapter includes the following topics:

23.1 Prerequisites

Before you can perform tasks in this chapter ensure that the Oracle Access Manager Console and a managed OAM Server are running.

Oracle recommends that you review the Chapter 6, "Managing Common OAM Server Registration".

23.2 Introduction to Logging Component Event Messages

The logging infrastructure records messages that can be used for problem diagnosis. Oracle Security Token Service is a J2EE Web application, part of the Oracle Access Manager J2EE Application. Both use OJDL for logging purposes. Oracle Security Token Service captures the interactions between itself and Partners with timestamps.The administrator controls the amount of information that is logged in a message by specifying log levels for each component for which a logger is defined.

Note:

Generally, you enable logging to produce files that you send to Oracle Technical Support for problem diagnosis. Documentation for log messages is not available. In some cases, you might be able to diagnose problems on your own by reading log files.

Oracle Access Manager and Oracle Security Token Service use the WebLogic container's logging defaults:

The following events are logged automatically:

By default, the log level for all Oracle Access Manager and Oracle Security Token Service components is the Notification level. Logging at the Error level produces a small amount of output while other log levels can result in voluminous logging output, which can impact performance. In production environments, logging is usually either disabled or the log level is set to a level that results in a small volume of logging output (the error level, for example).

For more information, see:

See Also:

23.2.1 About Component Loggers

This section introduces component loggers for both Oracle Security Token Service and Oracle Access Manager. There are differences.

Oracle Security Token Service has only a single logger: oracle.security.fed. For more information, see "Configuring Logging for Oracle Security Token Service".

Each Oracle Access Manager component is associated with its own logger name, as listed in the following tables:

Table 23-1 Oracle Access Manager Server-Side Components

Component Name OAM Logger Name

Protocol Binding

oracle.oam.binding

SSO Controller

oracle.oam.controller.sso

OAM Proxy

oracle.oam.proxy.oam

OSSO Proxy

oracle.oam.proxy.osso

Credential Collector

oracle.oam.credcollector

Remote Registration of Partners

oracle.oam.engine.remotereg

Oracle Access Manager Console

oracle.oam.admin.console

Admin-Service Config

oracle.oam.admin.service.config

Diagnostics and Monitoring

oracle.oam.diag


Table 23-2 Oracle Access Manager Shared-Service Engine Components

Component Name OAM Logger Name

Authentication Engine

oracle.oam.engine.authn

Policy Service Engine

oracle.oam.engine.policy

Session Management Engine

oracle.oam.engine.session

Token Engine

oracle.oam.engine.token

SSO Engine

oracle.oam.engine.sso

PartnerTrustMetadata Engine

oracle.oam.engine.ptmetadata

Authorization Engine

oracle.oam.engine.authz


Table 23-3 Oracle Access Manager Foundation APIs Components

Component Name OAM Logger Name

Session Access

oracle.oam.session.access

Session Access Implementation

oracle.oam.session.accessimpl

Policy Access

oracle.oam.policy.access


23.2.2 Sample Logger and Log Handler Definition

This topic provides a sample for Oracle Access Manager only. Oracle Security Token Service has only one logger and log handler, as described in "Configuring Logging for Oracle Security Token Service".

Example 23-1 illustrates the configuration of an Oracle Access Manager logger and a log handler in the file logging.xml.

Example 23-1 Configuring Oracle Access Manager Loggers and Log Handlers

<logging_configuration>

  <log_handlers>
    <log_handler name='oam-handler' class='oracle.core.ojdl.logging.
    ODLHandlerFactory'>
      <property name='path' value='oam/diagnostic'/>
      <property name='maxFileSize' value='10485760'/>
      <property name='maxLogSize' value='104857600'/>
    </log_handler>
  </log_handlers>

  <loggers>
    <logger name='oracle.security.am' level='NOTIFICATION:1'>
      <handler name='oam-handler'/> 
      ...
    </logger>
  </loggers>

</logging_configuration>

See Also:

For more information about Java EE application logging, see Appendix I, section I.1.1, in Oracle Fusion Middleware Application Security Guide.

23.2.3 About Logging Levels

This topic applies equally to Oracle Access Manager and Oracle Security Token Service.

The amount of data output by a logger is controlled by its level; the higher the level, the more information is logged. The level of a logger is specified with the element <logger> in the file logging.xml with the following format:

<logger name="loggerName" level="notifLevel"/>

where loggerName is a logger name (see "About Component Loggers"), and notifLevel is either an ODL message level or a Java message level.

Table 23-4 shows the correspondence between ODL message levels and Java message levels, in increasing order:

Table 23-4 Mapping of ODL to Java Levels

ODL Message Level Java Message Level

INCIDENT_ERROR:1

SEVERE.intValue()+100

ERROR:1

SEVERE (logs exceptions)

WARNING:1

WARNING (logs exceptions)

NOTIFICATION:1

INFO (default)

NOTIFICATION:16

CONFIG

NOTIFICATION:32

INFO and CONFIG

TRACE:1

FINE (occasionally recommended in production environments)

TRACE:16

FINER (not recommended in production environments)

TRACE:32

FINEST (not recommended in production environments)


Any other Java level value not listed above (that is, one outside the interval [SEVERE.intValue()+100 - FINEST] is mapped to the ODL level UNKNOWN.

Note:

if you define a filter to log messages at the finest level for the oracle.security.fed package and sub-package (classes for Oracle Security Token Service), after restarting the server you would see logs for the OAM Server with Oracle Security Token Service. For more information, see "Configuring Logging for Oracle Security Token Service".

23.3 Configuring Logging for Oracle Access Manager

This section describes tasks for only Oracle Access Manager.

There is no graphical user interface available to change logger levels; only WLST commands can be used. This section provides the following topics:

23.3.1 Modifying the Logger Level for Oracle Access Manager

Administrators can use custom WLST commands for Oracle Access Manager to change logger settings as described in the following procedure. Your deployment and choices will be different.

Note:

Use the WLST command help("fmw diagnostics").

To modify the OAM logger level

  1. Confirm that the OAM Server is running.

  2. Acquire the custom WLST script for Oracle Access Manager. For example:

    <ORACLE_HOME>/common/bin/wlst.sh
    
  3. Connect to the WebLogic Server and log in as the WebLogic administrator. For example:

    sh wlst.sh wls:/offline> connect adminID password
    
  4. List available loggers for the OAM Server. For example:

    wls:/base_domain/serverConfig> listLoggers(pattern="oracle.oam.*",target="oam_
    server1")
    

    Here pattern= represents the oam.controller component and target= represents the desired OAM Server as it was specified during registration.

  5. View the list of Oracle Access Manager loggers associated with this OAM Server. For example:

    Logger                                      | Level
    --------------------------------------------+-----------------
    oracle.oam                                  | <Inherited>
    oracle.oam.admin.foundation.configuration   | <Inherited>
    oracle.oam.agent-default                    | <Inherited>
    oracle.oam.audit                            | <Inherited>
    oracle.oam.binding                          | <Inherited>
    oracle.oam.commonutil                       | <Inherited>
    oracle.oam.config                           | <Inherited>
    oracle.oam.controller                       | <Inherited>
    oracle.oam.default                          | <Inherited>
    oracle.oam.diagnostic                       | <Inherited>
    oracle.oam.engine.authn                     | <Inherited>
    oracle.oam.engine.authz                     | <Inherited>
    oracle.oam.engine.policy                    | <Inherited>
    oracle.oam.foundation.access                | <Inherited>
    oracle.oam.idm                              | <Inherited>
    oracle.oam.idm                              | <Inherited>
    oracle.oam.idm                              | <Inherited>
    oracle.oam.user.identity.provider           | <Inherited>
    
  6. Modify the log level based on your requirements. For example, this sequence changes the log level of the oam.controller to TRACE:32 with no persistence:

    wls:/base_domain/serverConfig> domainRuntime()
    wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.oam.controller", 
    level="TRACE:32", persist="0", target="oam_server1")
    
  7. Repeat step 4 to list the loggers again and verify the log level change. For example:

    wls:/base_domain/serverConfig> listLoggers(pattern="oracle.oam.*",target="oam_
    server1")
    
    Logger                                      | Level
    --------------------------------------------+-----------------
    oracle.oam                                  | <Inherited>
    oracle.oam.admin.foundation.configuration   | <Inherited>
    oracle.oam.agent-default                    | <Inherited>
    oracle.oam.audit                            | <Inherited>
    oracle.oam.binding                          | <Inherited>
    oracle.oam.commonutil                       | <Inherited>
    oracle.oam.config                           | <Inherited>
    oracle.oam.controller                       | TRACE:32
    oracle.oam.default                          | <Inherited>
    oracle.oam.diagnostic                       | <Inherited>
    oracle.oam.engine.authn                     | <Inherited>
    oracle.oam.engine.authz                     | <Inherited>
    oracle.oam.engine.policy                    | <Inherited>
    oracle.oam.foundation.access                | <Inherited>
    oracle.oam.idm                              | <Inherited>
    oracle.oam.idm                              | <Inherited>
    oracle.oam.idm                              | <Inherited>
    oracle.oam.user.identity.provider           | <Inherited>
    
  8. Verify the generated log file to confirm the controller is logged at the TRACE:32 level:

    DOMAIN_HOME/server/SERVER_INSTNCE_NAME/logs/
    
  9. Proceed to "Validating Run-time Event Logging Configuration".

23.3.2 Adding an Oracle Access Manager-Specific Logger and Log Handler

Administrators can use the following procedure to specify a log file path and necessary attributes.

In the following procedure, you will identify the target OAM Server, rotation and retention periods, a path to the log file, the handler, and logger. Your deployment and choices will be different.

Note:

Use the WLST command help("fmw diagnostics") to get more information.

Skip steps 1 through 3 if the following items are true:

  • The OAM Server is running

  • You have the WLST script

  • You have connected to the server and logged in

To specify the OAM logger, level, and log handler

  1. Confirm that the OAM Server is running.

  2. Acquire the WLST script. For example:

    <ORACLE_HOME>/common/bin/wlst.sh
    
  3. Connect to the WebLogic Server and log in as the WebLogic Administrator. For example:

    sh wlst.sh wls:/offline> connect
    
  4. Add an Oracle Access Manager logger and level for the OAM Server. For example:

    wls:/base_domain/serverConfig> domainRuntime()
    wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.oam", 
    level="WARNING", persist="0", target="oam_server1")
    
  5. Add a custom log handler and associate it with the Oracle Access Manager logger. For example:

    wls:/base_domain/domainRuntime> configureLogHandler(name="oam-log-handler", 
    target="oam_server1", rotationFrequency="daily", retentionPeriod="week", path="${domain.home}/oamlogs" , maxFileSize ="10485760", maxLogSize = "104857600", addHandler="true", handlerType="oracle.core.ojdl.logging
    .ODLHandlerFactory", addToLogger="oracle.oam")
    
    wls:/base_domain/domainRuntime>configureLogHandler(name="oam-log-handler", 
    addProperty="true", propertyName="supplementalAttributes", propertyValue=
    "OAM.USER, OAM.COMPONENT", target="oam_server1")
    
  6. Verify all the logs in the DOMAIN_HOME/oamlogs directory:

    DOMAIN_HOME/oamlogs/ 
    

23.4 Configuring Logging for Oracle Security Token Service

By default Oracle Security Token Service messages are logged into the OAM Server's log files. You can view and configure logs in Fusion Middleware Control. However, you can also edit logging.xml and direct Oracle Security Token Service information to a separate log file, as described here.

The files that are involved include:

Oracle Security Token Service does not categorize log handlers as Oracle Access Manager does. Instead, there is only one logger that affects the log levels for Oracle Security Token Service. Table 23-5 provides details for this logger that are required in the WLST command.

Table 23-5 Oracle Security Token Service Logger

Component Name Logger Name Log Handler Name Log Class

Oracle Security Token Service

oracle.security.fed

sts-handler

class='oracle.core.ojdl.logging.ODLHandlerFactory'


For details, see:

See Also:

23.4.1 Configuring Logging for Oracle Security Token Service

Administrators can use the following procedure to separate Oracle Security Token Service log messages from OAM Server message logs.

To configure logging for Oracle Security Token Service

  1. Locate and open logging.xml: DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml.

  2. Add the following to create the independent message log for Oracle Security Token Service:

    <log_handler name='sts-handler' class='oracle.core.ojdl.logging.ODLHand
    lerFactory'>
          <property name='path' value='sts/log'/>
          <property name='maxFileSize' value='10485760'/>
          <property name='maxLogSize' value='104857600'/>
        </log_handler>
    
    <logger name='oracle.security.fed' level='TRACE:32'>
          <handler name='sts-handler'/>
        </logger>
    
  3. Save the file.

  4. Proceed with "Defining the Log Level and Log Details for Oracle Security Token Service".

23.4.2 Defining the Log Level and Log Details for Oracle Security Token Service

Administrators can use custom WLST commands for Oracle Access Manager to change logger settings for Oracle Security Token Service as described here. This specifies an independent output file for only Oracle Security Token Service log messages.

This sample procedure for Oracle Security Token Service logging is very similar to the one for Oracle Access Manager. However, there are a few differences. Your deployment choices will be different.

Note:

Use the WLST command help("fmw diagnostics").

Skip steps 1 through 3 if the following items are true:

  • The OAM Server is running

  • You have the WLST script

  • You have connected to the server and logged in

To modify the logger level and log file for Oracle Security Token Service

  1. Confirm that the OAM Server is running.

  2. Acquire the custom WLST script for Oracle Access Manager:

    <ORACLE_HOME>/common/bin/wlst.sh
    
  3. Connect to the WebLogic Server and log in as the WebLogic administrator. For example:

    sh wlst.sh wls:/offline> connect adminID password
    
  4. Modify the log level of oracle.security.fed based on your requirements. For example, this sequence changes the log level to WARNING with no persistence:

    wls:/base_domain/serverConfig> domainRuntime()
    wls:/base_domain/domainRuntime> setLogLevel(logger="oracle.security.fed", 
    level="WARNING", persist="0", target="oam_server1")
    
  5. Specify the target OAM Server, as well as rotation and retention periods, path to the log file, the handler, and logger. For example:

    wls:/base_domain/domainRuntime> configureLogHandler(name="osts-log-handler",  
    target="oam_server1", rotationFrequency="daily", retentionPeriod="week", 
    path="${domain.home}/ostslogs", maxFileSize ="10485760", maxLogSize  
    ="104857600", addHandler="true",handlerType="oracle.core.ojdl.logging.ODL 
    HandlerFactory", addToLogger="oracle.security.fed")
    
  6. Verify the generated log file to confirm the controller is logged at the WARNING level:

    DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log 
    
  7. Proceed to "Validating Run-time Event Logging Configuration".

23.5 Validating Run-time Event Logging Configuration

You can use the following procedure to test your run-time event logging configuration.

Prerequisites

To validate run-time event logging

  1. In a browser, enter the URL to a protected resource and sign in using an invalid credential.

  2. Sign in again using the proper credential.

  3. On the physical server, verify all the logs appear in:

    DOMAIN_HOME/oamlogs/
    DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log
    
  4. Open the log file and look for the last entries to confirm authentication failure and success, respectively.