Logging Component Event Messages

7 Logging Component Event Messages

Logging is the mechanism by which components and services write messages to a log file in order to capture critical component events, processes, and state information. Administrators can configure logging to provide information at various levels of granularity using the same logging infrastructure and guidelines as any other component in Oracle Fusion Middleware 14c: java.util.logging (standard and available in all Java environments).

Configuring logging and locating log files are the focus of this chapter which contains the following sections.

7.1 About Oracle Access Management Logging

The logging system writes output to flat files only. Logging to an Oracle Database instance is not supported. Unless explicitly stated, information in this chapter is the same whether using any of the services in Oracle Access Management.

Additionally:

You can use a custom Oracle WebLogic Scripting Tool (WLST) command to change logging levels.
Diagnosing problems using the information in log files is outside the scope of this chapter.
Before you can perform tasks in this chapter ensure that the Oracle Access Management Console and a managed OAM Server are running.

Oracle also recommends that you review Managing Server Registration.

7.2 Logging Component Event Messages

The logging infrastructure records messages that can be used for problem diagnosis. Security Token Service is a J2EE Web application, part of the Access Manager J2EE Application. Both use OJDL for logging purposes. 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.

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 Management makes use of the files in Table 7-1.

Table 7-1 Logging Files

File Type	Description
Logging Configuration File	Provides logging level and other configuration information for logging. This file is stored in the following path: $DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml Note: By default, Security Token Service and Identity Federation messages are logged in the OAM Server's log file. However, for convenience, you can edit logging.xml to direct Security Token Service or Identity Federation information to a separate log file, as described in "Configuring Logging for Identity Federation".
Log File	Logged information is stored in the following location: $DOMAIN_HOME/servers/SERVER-NAME/logs/ SERVER-NAME-diagnostics.log

File Type

Description

Logging Configuration File

Provides logging level and other configuration information for logging. This file is stored in the following path:

$DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml

Note: By default, Security Token Service and Identity Federation messages are logged in the OAM Server's log file. However, for convenience, you can edit logging.xml to direct Security Token Service or Identity Federation information to a separate log file, as described in "Configuring Logging for Identity Federation".

Log File

Logged information is stored in the following location:

$DOMAIN_HOME/servers/SERVER-NAME/logs/ SERVER-NAME-diagnostics.log

Oracle Access Management uses the WebLogic container's logging defaults in Table 7-2.

Table 7-2 Logging Defaults

Log Type	Description
Events	The following events are logged automatically: OAM Server events (managed run-time servers) Administrative events (generated for configuration changes made using the console)
Levels	By default, the log level for all Oracle Access Management 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).

Log Type

Description

Events

The following events are logged automatically:

OAM Server events (managed run-time servers)
Administrative events (generated for configuration changes made using the console)

Levels

By default, the log level for all Oracle Access Management 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:

Monitoring Performance and Logs with Fusion Middleware Control for details about how you can configure and view logs using Fusion Middleware Control
For logging information, see Logging Audit Events Programmatically in the Securing Applications with Oracle Platform Security Services.

7.2.1 Component Loggers for Security Token Service and Access Manager

The component loggers for Security Token Service and Access Manager are different.

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

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

Table 7-3 Oracle Access Management Server-Side Component Loggers

Component Name	OAM Logger Name	Description
Protocol Binding	oracle.oam.binding	Responsible for marshalling/unmarshalling wire protocol request and response to a Java Object representation
SSO Controller	oracle.oam.controller.sso	Responsible for managing the user session lifecycle and orchestrating the SSO and logout flows
OAM Proxy	oracle.oam.proxy.oam	Responsible for interacting with OAM Webgates by marshalling/unmarshalling OAP protocol requests and responses and performing the data/message transformation necessary to help the OAM Server process OAP requests/responses
Credential Collector	oracle.oam.credcollector	Responsible for interacting with the user to acquire the necessary information required by the Authentication Scheme
Remote Registration of Partners	oracle.oam.engine.remotereg	Responsible for registering partners with the OAM Server and managing associated protected policies
Oracle Access Management Console	oracle.oam.admin.console	Console that supports administration and monitoring of the Access Management deployment
Admin-Service Config	oracle.oam.admin.service.config	Module used by the UI Console to manage the configuration
Diagnostics and Monitoring	oracle.oam.diag	Provides instrumentation used by the OAM Server components to enable Diagnostic and Monitoring

Table 7-4 Oracle Access Management Shared-Service Engine Component Loggers

Component Name	OAM Logger Name	Description
Authentication Engine	oracle.oam.engine.authn	Supports establishing the identity of the user by validating the credentials and other data as required by the specified Authentication scheme
Policy Service Engine	oracle.oam.engine.policy	Supports management of Authentication, Authorization and Token Issuance Policies. In addition, it also provide a policy decision service to support runtime processing
Session Management Engine	oracle.oam.engine.session	Supports managing user session and token context information with support for user/administrator-initiated and time-out based events
Token Engine	oracle.oam.engine.token	Supports managing the entire token life cycle from generation to cancellation
SSO Engine	oracle.oam.engine.sso	Supports the single sign-on experience by managing the lifecycle of the user login session(s)
PartnerTrustMetadata Engine	oracle.oam.engine.ptmetadata	Supports management of partner metadata and trust information
Authorization Engine	oracle.oam.engine.authz	Wrapper that provides methods that map directly to OAP runtime request operations

Table 7-5 Oracle Access Management Foundation API Component Loggers

Component Name	OAM Logger Name	Description
Session Access	oracle.oam.session.access	** Not useful unless your are decompiling code
Session Access Implementation	oracle.oam.session.accessimpl	** Not useful unless your are decompiling code
Policy Access	oracle.oam.policy.access	** Not useful unless your are decompiling code

7.2.2 Sample Logger and Log Handler Definition

Here is a sample logger and a log handler for Access Manager only.

Security Token Service has only one logger and log handler, as described in "Configuring Logging for Identity Federation".

Following example illustrates the configuration of an Access Manager logger and a log handler in the file logging.xml.

<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 Java EE application logging information, see Naming and Logging Audit Files in the Securing Applications with Oracle Platform Security Services.

7.2.3 About Logging Levels

InOracle Access Management, 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 "Component Loggers for Security Token Service and Access Manager"), and notifLevel is either an ODL message level or a Java message level.

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

Table 7-6 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 Security Token Service), after restarting the server you would see logs for the OAM Server. For more information, see "Configuring Logging for Identity Federation".

7.3 Configuring Logging for Access Manager

Graphical user interface is not available to change logger levels, only WLST commands can be used.

This section describes tasks only for Access Manager.

This section provides the following topics:

7.3.1 Modifying the Logger Level for Access Manager

Administrators can use custom WLST commands for Access Manager to change logger settings.

Your deployment and choices will be different.

Note:

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

Follow this procedure to modify the OAM logger level.

Confirm that the OAM Server is running.
Acquire the custom WLST script for Access Manager. For example:
```
$ORACLE_HOME/common/bin/wlst.sh
```
Connect to the WebLogic Server and log in as the WebLogic Administrator. For example:
```
connect([username, password])
```
List available loggers for the OAM Server. For example:
```
wls:/base_domain/serverConfig> listLoggers(pattern="oracle.oam.*",
  target="oam_server1")

wls:/WLS_IDM/serverConfig> listLoggers(pattern="oracle.oam.*",
  target="oam_policy_mgr1")
```
Here pattern= represents the oam.controller component and target= represents the desired OAM Server as it was specified during registration.

View the list of 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>

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")

wls:/WLS_IDM/domainRuntime> setLogLevel(logger="oracle.oam", level="TRACE:32", persist="0", target="oam_policy_mgr1")

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>

Verify the generated log file to confirm the controller is logged at the TRACE:32 level:
```
$DOMAIN_HOME/server/SERVER_INSTNCE_NAME/logs/
```
Proceed to "Validating Run-time Event Logging Configuration".

7.3.2 Adding an 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

See Also:

Customization Commandsin WLST Command Reference for WebLogic Server

Follow this procedure to specify the OAM logger. level and log handler.

Confirm that the OAM Server is running.
Acquire the WLST script. For example:
```
$ORACLE_HOME/common/bin/wlst.sh
```
Connect to the WebLogic Server and log in as the WebLogic Administrator. For example:
```
sh wlst.sh wls:/offline> connect
```

Add an 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")

Add a custom log handler and associate it with the 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")

Verify all the logs in the $DOMAIN_HOME/oamlogs directory:
```
$DOMAIN_HOME/oamlogs/ 
```

7.4 Configuring Logging for Identity Federation

By default Identity Federation messages are logged into the OAM Server's log files.

You can view and configure these logs in Fusion Middleware Control. However, you can also edit logging.xml and direct Identity Federation information to a separate log file, as described in this section. The files involved in this procedure are:

Logging Configuration File: Provides logger names and other configuration information for logging. This file is stored in: $DOMAIN_HOME/config/fmwconfig/servers/SERVER-NAME/logging.xml.
Log File: $DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log, for example.

Security Token Service and Identity Federation do not categorize log handlers as Access Manager does. Instead, there is only one logger that affects the log levels for Identity Federation. Table 7-7 provides details for this logger, which are required in the WLST command.

Table 7-7 Oracle Identity Federation Loggers

Component Name	Logger Name	Log Handler Name	Log Class
Identity Federation	oracle.security.fed	stsfed-handler	class=oracle.core.ojdl.logging.ODLHandlerFactory

For details, see:

See Also:

Monitoring Performance and Logs with Fusion Middleware Control for details about how you can configure and view logs using Fusion Middleware Control
Logging information in the Logging Audit Events Programmatically in the Securing Applications with Oracle Platform Security Services

7.4.1 Configuring Logging for Identity Federation

Administrators can separate Identity Federation log messages from OAM Server message logs.

To configure:

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

Add the following to create the independent message log for Identity Federation:

<log_handler name='stsfed-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='stsfed-handler'/>
    </logger>

Save the file.
Proceed with "Defining Log Level and Log Details for Security Token Service or Identity Federation".

7.4.2 Defining Log Level and Log Details for Security Token Service or Identity Federation

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

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

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

Confirm that the OAM Server is running.
Acquire the custom WLST script for Oracle Access Management:
```
$ORACLE_HOME/common/bin/wlst.sh
```
Connect to the WebLogic Server and log in as the WebLogic Administrator. For example:
```
sh wlst.sh wls:/offline> connect adminID password
```

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")

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")

Verify the generated log file to confirm the controller is logged at the WARNING level:

 $DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log 
 $DOMAIN_HOME/oiflogs/SERVER-NAME-diagnostics.log

Proceed to "Validating Run-time Event Logging Configuration".

7.5 Validating Run-time Event Logging Configuration

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

Before you begin:

Configure logging using WLST commands
Ensure the Agents and Servers are running.
Configure an Application Domain to protect the resource as described in Managing Policies to Protect Resources and Enable SSO.

To validate run-time event logging configuration:

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

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

$DOMAIN_HOME/oamlogs/
$DOMAIN_HOME/ostslogs/SERVER-NAME-diagnostics.log
$DOMAIN_HOME/oiflogs/SERVER-NAME-diagnostics.log

Open the log file and look for the last entries to confirm authentication failure and success, respectively.