27 Using Enterprise Manager for Managing Oracle Identity Governance
This chapter describes how to configure Oracle Identity Manager using Oracle Enterprise Manager. It contains the following sections:
27.1 Managing Oracle Identity Governance Configuration
Oracle Identity Manager stores the configuration files in MDS. Most of the configurations are exposed as MBeans. Therefore, you can control the configuration values by using Oracle Enterprise Manager. In some instances, you might have to export the complete files to the file system, make the necessary changes, and then import the files back into the repository.
This topic contains the following sections:
27.1.1 Using MBeans for Configuration Changes
The configurations files are stored as MBeans, which you can modify to change configuration settings.
To change configuration settings by using Mbeans:
27.1.2 Exporting and Importing Configuration Files
For making changes to the configuration files, you can export the existing configuration files to an external file system, edit the files to make necessary changes, and import the newly edited files back to the repository.
To export or import configuration files:
-
When the administrative server and at least one Oracle Identity Manager managed server is running, login to Oracle Enterprise Manager Fusion Middleware Control by using the URL in the following format:
http://ADMINSTRATION_SERVER:PORT/em
-
Navigate to Identity and Access, oim. Right-click and navigate to System MBean Browser.
-
Under Application Defined MBeans, navigate to oracle.mds.lcm, Server:oim_server1, Application:OIMMetadata, MDSAppRuntime.
-
To export the configuration files:
-
Click the Operations tab, and then click exportMetaData.
-
In the toLocation field, enter
/tmpor the name of another directory. -
Select createSubDir as false.
-
In the docs field, enter the complete file location as the Element.
-
Also select false for excludeAllCust, excludeBaseDocs, and excludeExtendedMetadata. Then, click Invoke.
This exports the file specified in the docs field to the directory specified in the toLocation field.
-
-
To import the configuration files:
-
Click importMetaData.
-
In the fromLocation field, enter
/tmpor the name of the directory in which you have the configuration files. -
Select createSubDir as false.
-
In the docs field, enter the complete file location as the Element. For example, /db/oim-config.xml.
-
Also select false for excludeAllCust, excludeBaseDocs, and excludeExtendedMetadata. Then, click Invoke.
This imports the file specified in the docs field to MDS in the toLocation field.
-
27.2 Using the OrchestrationEngine MBean
Using the OrchestrationEngine MBean includes accessing the OrchestrationEngine Mbean, operations supported by the MBean, and diagnosis of operation failures.
You can manage the orchestration engine by using the OrchestrationEngine MBean provided by Oracle Enterprise Manager. This section describes the MBean and its various operations and parameters. It contains the following topics:
27.2.1 Accessing the OrchestrationEngine MBean
Login to Oracle Enterprise Manager, open System MBean Browser, and display the MBean information for the OrchestrationEngine MBean under Application Defined MBeans.
To access the OrchestrationEngine MBean:
27.2.2 About the Operations Supported by the MBean
The OrchestrationEngine MBean supports various operations, such as dump, findEventHandlers, findEventsForProcess, and findOperations.
Table 27-1 lists the operations supported by the OrchestrationEngine MBean.
Table 27-1 Operations Supported by OrchestrationEngine
| Operation | Description |
|---|---|
|
dump |
This operation dumps complete orchestrations to the console or to a file. The console cannot print more then three to five orchestrations because of size limitations, and therefore, file system must be used. Paging must be used to dump data in chunks if the number of processes to be dumped is high, as it can put load on the server. If paging is used to dump data to a single file, then set the appendFile parameter to true, so that page dumps are appended in the file. Otherwise, use separate file per page dump. |
|
familyTree |
This operation returns the entire family tree of a process whose ID is provided as a parameter. The family includes children, siblings, and parent up to n-level. Setting the value of the |
|
findEventHandlers |
This operation returns a list of supported event handlers for a particular combination of entity type and operation. The parameters of this operation are case-sensitive. Therefore, when some custom handlers are defined, it helps in debugging if they have the right case as these values are used in case-sensitive manner. All the handlers are returned in the order of execution. |
|
findEventsForProcess |
This operation returns the actual list of events applicable in the context/flow for a process, whose ID and/or name is provided. Handlers are returned in the order of execution. The list of handlers is not the complete handler list of an entity type and operation. |
|
findOperations |
This operation returns a list of all the configured operations for an entity type. If nothing is provided as parameter, then it returns a complete list of operations across entity operations. |
|
findProcess |
This operation returns a list of processes that satisfies the criteria based on the parameters passed. If search is not ID-based, then Setting the If no value is provided as parameter value, then it returns all the processes saved in the database, which can be a large number. |
|
listEntityTypes |
This operation returns a list of Oracle Identity Manager entity types. |
27.2.3 About Diagnosis of Operation Failures Using the Orchestration Engine
Most of the operations done on various entities in Oracle Identity Manager go via the orchestration engine. The list of entity types using orchestration engine as their back bone can be obtained via the listEntityTypes operation on the OrchestrationEngine Mbean.
End to end detailed flow of every operation is logged in the log files. For debugging purposes, finer details can be obtained by setting the logging level of the oracle.iam.platform.kernel logger to INFO or FINE.
Orchestrations only get serialized in the database if they have not achieved completed status, which might occur because of failures or waiting for another thread to resume processing.
To understand the cause of incomplete processing of any orchestration process, which can be because of various reasons, you can either look into the logs or use the orchestration process ID obtained from logs to get the details from the OrchestrationEngine Mbean.
Note:
Orchestration Process ID is a unique combination of two fields, a long type ID and a string type Name. Either of the two can be provided to the Mbean operations to get results. You can provide both for exact record match.
Orchestration process ID can be obtained in the following ways:
-
From the log files
-
From
getOrchestrationIdsoperation of EventDiagnostic Mbean (oracle.iam:Location=oim_server1,name=EventDiagnostic,type=Reconciliation,Application=oim) for reconciliation flows. -
From the
processInfooperation of the RequestDiagnostic MBean (oracle.iam:Location=oim_server1,name=RequestDiagnosticMXBean,type=IAMAppRuntimeMBean,Application=oim), by providing the request ID or from the orchestration_process_id column of the request table for request flows. -
By using the findProcess operation of the OrchestrationEngine MBean, which searches through the database of incomplete orchestrations based on the provided criteria
Note:
If the findProcess operation of the MBean for a particular process ID returns nothing, then it means that either the provided ID is incorrect or the particular process completed successfully and does not exist in the database. Information for such a process ID is available only in the log files.
27.2.4 Diagnosing Operation Failures Using the Orchestration Engine
Diagnosing operation failures using the Orchestration Engine involves enabling internal details of the process, invoking the findEventsForProcess operation followed by the dump operation, and invoking the familyTree operation for parent and child orchestrations.
After the process ID is found, perform the following steps to diagnose operation failures:
-
Invoke the
findProcessoperation of the MBean, pass the process ID and set thedetailedparameter astrue. This provides all the internal details of the process. -
Get the details of the handlers involved in the order of execution by invoking the
findEventsForProcessoperation on the MBean. -
Dump the complete process to the console or a file by invoking the
dumpoperation of the MBean. Pass the process ID and the file name if it is required to be dumped to a file. -
Complex cases involving parent and child orchestrations up to n-level can be completely traced by invoking the
familyTreeoperation on the OrchestrationEngine MBean.
If the process ID is not found, then multiple orchestrations can be dumped to a file by using the dump operation of the MBean, based on the parameters provided to the mbean. This dump file along with the log files help understand the cause of various issues. These files can also be provided to Oracle support as part of service request.
27.3 Configuring Log Services for Oracle Identity Governance
Oracle Identity Manager uses two logging services: Oracle Diagnostic Logging (ODL), which is the logging service used by most Oracle Fusion Middleware applications, and Apache log4j.
Oracle Identity Manager logging is primarily done with ODL. Apache log4j is only used with third-party applications, such as Nexaweb for Deployment Manager and Workflow Designer, and OSCache for caching.
This topic contains the following sections:
27.3.1 Logging in Oracle Identity Governance By Using ODL
Logging by using ODL involves understanding message types and levels, log handler, and logging configuration, configuring loggers and log handlers, and starting and stopping jobs.
This section describes about the logs generated in Oracle Identity Manager using the ODL in the following topics:
27.3.1.1 About Oracle Diagnostic Logging
Oracle Diagnostic Logging (ODL) is the principal logging service used by Oracle Identity Manager. For ODL logging to work, both loggers and log handlers need to be configured. Loggers send messages to handlers, and handlers accept messages and output them to log files.
Logging configuration is controlled by the logging.xml file described in Log Handler and Logger Configuration. This file can either be edited directly or edited through the Enterprise Manager. On the Enterprise Manager, the logging configuration can be accessed by clicking the OIM server link and by selecting the WebLogic Server drop down from the top, and then clicking on Logs - Log Configuration.
To access the logging configuration on the Enterprise Manager:
-
Click the OIM server link.
-
From the WebLogic Server list, select Logs - Log Configuration. All the packages available for logging are displayed on the log configuration screen.
For any additional packages to be logged that are not available in the Enterprise Manager (such as, for connector packages), follow the instructions to manually edit the logging.xml file. The packages specific to Oracle Identity Manager can be accessed under oracle.iam. The different log levels are available for selection under the Oracle Diagnostic Logging Level column. Select a particular log level, and then click Apply for the changes to take effect. In addition, new log handlers can be created and configured by clicking the Log Files tab.
Each Oracle Identity Manager module has its own logger that can be configured independently to send different amounts of information to one or more log handlers. Table 27-3 lists the more than twenty different Oracle Identity Manager loggers that can be configured to send messages to log handlers.
You can output more or less information to a log by adjusting the level attribute for each logger. To select a logging level, choose from one of five message types (INCIDENT_ERROR, ERROR, WARNING, NOTIFICATION, and TRACE). Each message type can also take a numeric value between 1 (highest severity) and 32 (lowest severity) that you can use to further restrict the volume of messages that a logger will output. Table 1 on page 2 lists the message type and level combinations that are used most often.
Log handlers specify the target where log messages should appear. For example, log handlers can write messages to the console, to various log files, and to additional outputs.
27.3.1.2 Message Types and Levels in Oracle Identity Governance
ODL recognizes five message types: INCIDENT_ERROR, ERROR, WARNING, NOTIFICATION, and TRACE. Each message type can also take a numeric value between 1 (highest severity) and 32 (lowest severity) that you can use to further restrict message output.
When you specify a message type, ODL returns all messages of that type, as well as the messages that have a higher severity. For example, if you set the message type to WARNING, ODL also returns messages of type INCIDENT_ERROR and ERROR.
Message types and levels are described in greater detail in Setting the Level of Information Written to Log Files of the Administrator’s Guide. Table 27-2 lists the diagnostic message types that you can use most often with Oracle Identity Manager.
Table 27-2 Oracle Identity Manager Diagnostic Message Types
| Message Type and Numeric Value | Description |
|---|---|
|
INCIDENT_ERROR:1 |
A serious problem that may be caused by a bug in the product and that should be reported to Oracle Support. Examples are errors from which you cannot recover. |
|
ERROR:1 |
A serious problem that requires immediate attention from the administrator and is not caused by a bug in the product. An example is if Oracle Fusion Middleware cannot process a log file, then you can correct the problem by fixing the permissions on the document. |
|
WARNING:1 |
A potential problem that should be reviewed by the administrator. Examples are invalid parameter values or a specified file does not exist. |
|
NOTIFICATION:1 |
A major lifecycle event such as the activation or deactivation of a primary sub-component or feature. This is the default level for NOTIFICATION. |
|
NOTIFICATION:16 |
A finer level of granularity for reporting normal events. |
|
TRACE:1 |
Trace or debug information for events that are meaningful to administrators, such as public API entry or exit points. |
|
TRACE:16 |
Detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem. |
|
TRACE:32 |
Very detailed trace or debug information that can help Oracle Support diagnose problems with a particular subsystem. |
27.3.1.3 Log Handler and Logger Configuration
Both log handlers and loggers can be configured by editing logging.xml, which is located in:
DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/logging.xml
Here, DOMAIN_NAME and SERVER_NAME are the domain name and server name respectively specified during the installation of Oracle Identity Manager.
The logging.xml file has a <log_handlers> configuration section, followed by a <loggers> configuration section. Each log handler is defined within the <log_handlers> section, and each logger is defined within the <loggers> section.
The file has the following basic structure:
<logging configuration>
<log_handlers>
<log_handler name='console-handler' level="NOTIFICATION:16"></log_handler>
<log_handler name='odl-handler'></log_handler>
<!--Additional log_handler elements defined here....-->
</log_handlers>
<loggers>
<logger name="example.logger.one" level="NOTIFICATION:16">
<handler name="console-handler"/>
</logger>
<logger name="example.logger.two" />
<logger name="example.logger.three" />
<!--Additional logger elements defined here....-->
</loggers>
</logging_configuration>
When configuring a logger to write messages to either the console or a file, make configuration changes to both the logger and the handler. Setting the level attribute for the logger configures the amount of detail (and therefore, the volume of messages) that the logger sends to the handler. Similarly, setting the level attribute for the handler configures the amount of detail that the handler accepts from the logger.
Note:
If you are not getting the volume of output that you expect in a log, then verify that the level attribute for both the logger and the log handler are set appropriately. For example, if the logger is set to TRACE and the log handler is set to WARN, then the handler does not generate messages more detailed than WARN.
27.3.1.4 Configuring Log Handlers
Individual log handlers are configured in the <log_handlers> section of the logging.xml file. Configure the level attribute for the handler to set the amount of detail that the handler will accept from loggers.
To configure the log handler-level attribute:
Note:
You must have a basic understanding of XML syntax before you attempt to modify the logging.xml file.
27.3.1.5 Log Handler Configuration Tools
Log handlers that write to a file have additional properties that can be configured. For example, this excerpt from logging.xml configures the odl-handler:
<log_handler name='odl-handler' class='oracle.core.ojdl.logging.ODLHandlerFactory' filter='oracle.dfw.incident.IncidentDetectionLogFilter'>
<property name='path' value='${domain.home}/servers/${weblogic.Name}/logs/${weblogic.Name}-diagnostic.log'/>
<property name='maxFileSize' value='10485760'/>
<property name='maxLogSize' value='104857600'/>
<property name='encoding' value='UTF-8'/>
<property name='useThreadName' value='true'/>
<property name='supplementalAttributes' value='J2EE_APP.name,J2EE_MODULE.name, WEBSERVICE.name,WEBSERVICE_PORT.name,composite_instance_id,component_instance_id, composite_name,component_name'/>
</log_handler>
To make changes to log handler properties, you can use either the Fusion Middleware Control tool or the WLST command-line tool.
See Also:
-
Configuring Settings for Log Files in Administrator’s Guide for information about both the Fusion Middleware Control tool and the WLST command-line tool
-
Logging Custom WLST Commands in WebLogic Scripting Tool Command Reference for information about the WLST command-line tool
27.3.1.6 About Configuring Loggers
Individual loggers are configured in the <loggers> section of the logging.xml file. More than twenty different Oracle Identity Manager loggers that can be configured to send messages to log handlers. Oracle Identity Manager loggers are described in Table 2 on page 7.Setting the level attribute for the logger configures the amount of detail (and, hence, the volume of messages) that the logger sends to its handlers. Nesting one or more <handler> elements inside of <logger> elements assigns handlers to loggers.The following excerpt shows a logger called OIMCP.PSFTCOMMON. The level attribute is set to WARNING:32 and the logger sends messages to three handlers:
<logger name="OIMCP.PSFTCOMMON" level="WARNING:32" useParentHandlers="false"> <handler name="odl-handler"/> <handler name="wls-domain"/> <handler name="console-handler"/> </logger>
A logger can inherit a parent logger's settings, including the parent's level setting and other attributes, as well as the parent logger's handlers. To disable inheritance, set the useParentHandlers attribute to false, as shown in the previous excerpt.
At the top of the logger inheritance tree is the root logger. The root logger is the logger with an empty name attribute, as shown in the following example.
<loggers>
<logger name="" level="WARNING:1">
<handler name="odl-handler"/>
<handler name="wls-domain"/>
<handler name="console-handler"/>
</logger>
<!-- Additional loggers listed here -->
</loggers>
If a logger is configured with only its name attribute, the logger will inherit the rest of its attributes from the root logger, as shown in the following example:
<loggers>
<logger name="oracle.iam.identity.rolemgmt"/>
<!-- Additional loggers listed here -->
</loggers>
27.3.1.8 Sample ODL Log Output
The following ODL log excerpt illustrates the kind of output you can expect.
<Jun 15, 2010 2:01:20 AM IST> <Error> <oracle.iam.platform.authz.impl> <IAM-1010032> <No OES Policy found for the given Action.> <Jun 15, 2010 2:02:02 AM IST> <Warning> <oracle.iam.platform.canonic.agentry> <IAM-0091108> <readme.txt is not a valid connector resource file.> <Jun 15, 2010 2:02:52 AM IST> <Error> <oracle.iam.configservice.impl> <IAM-3020003> <The attribute User Type does not exist!>
For information about managing and interpreting log output, see Managing Log Files and Diagnostic Data in Administrator’s Guide.
27.3.2 Logging in Oracle Identity Governance By Using log4j
Apache log4j is used with third-party applications, such as Nexaweb, and OSCache for caching.
The location of the log4j configuration file is:
OIM_HOME/config/log.properties
Logging in Oracle Identity Manager by using log4j is described in the following sections:
27.3.2.1 Log Levels for log4j
Table 27-4 lists the log levels for log4j:
Table 27-4 Log Levels for log4j
| Log Level | Description |
|---|---|
|
DEBUG |
The DEBUG level designates fine-grained informational events that are useful to debug an application. |
|
INFO |
The INFO level designates informational messages that highlight the progress of the application at coarse-grained level. |
|
WARN |
The WARN level designates potentially harmful situations. |
|
ERROR |
The ERROR level designates error events that might allow the application to continue running. |
|
ALL |
The ALL level has the lowest possible rank and is intended to turn on all logging. |
|
OFF |
The OFF level has the highest possible rank and is intended to turn off logging. |
27.3.2.2 Loggers in Third-Party Applications
The loggers for the third-party applications used are:
-
com.nexaweb.server for Nexaweb
-
com.opensymphony.oscache for OSCache
27.3.3 Setting Warning State
To set the Oracle Identity Manager server warning state, set the re-delivery limit on all OIM JMS queues to 1, purge all bad messages, and restart the server.
To set the Oracle Identity Manager server warning state:
-
Set the re-delivery limit on all OIM JMS queues to 1. To do so:
-
Login to the WebLogic Administration Console as the administrative user.
-
Click JMS Modules on the Home page.
-
Click OIMJMSModule.
-
Click Lock & Edit.
-
For each of the queues, click the queue, and then click the Delivery Failure tab. Change the Redelivery Limit value from -1 to 1, and then click Save.
-
Make sure you have performed steps 1.d and 1.e for all the queues under OIMJMSModule.
-
Release the configuration and restart Oracle Identity Manager.
This re-delivery is not applicable for existing messages. When the server is restarted, wait for all the good messages to be processed. After that, all the bad messages must be purged.
-
-
To purge all bad messages:
-
Login to the WebLogic Administration Console as the administrative user.
-
Click JMS Servers on the home page.
-
Navigate to OIMJMSServer, Monitoring, Active Destinations.
-
Select the queues that contain messages. Click Consumption, Pause.
-
Delete the messages, as described in the following URL:
-
After messages are deleted, resume the consumption that has been paused in step 2.d.
-
-
Restart Oracle Identity Manager.
27.3.4 Switching Down the Log Level
You can switch down the logging level to avoid high volume of log file entries.
By default, the logging level for oracle.* packages is defined as NOTIFICATION/INFO. This results in high volume of log file entries. To avoid this, it is recommended that you switch down the logging level. To do so: