25 Enabling Diagnostics

The IdM Diagnostic tool is a standalone diagnostic tool that is intended to accomplish the following:

• Identify problems in Identity Management deployments

• Suggest fixes to resolve application problems

• Run diagnostic tests and collect detailed diagnostic reports

• Assist Oracle Support and development teams conduct analysis and troubleshoot application problems

This chapter provides the details on enabling diagnostics in Oracle Identity Manager for dynamic configuration-related test cases. Dynamic configuration relates to changes made to the configurations at run time and are not easily detected through the static configuration diagnostic tests when there is an issue. In addition, the dynamic issues are encountered while Oracle Identity Manager is running.

Enabling diagnostics in Oracle Identity Manager and test cases related to dynamic configuration are described in the following sections:

• Enabling Diagnostics in Oracle Identity Manager

• Troubleshooting Dynamic Configuration-Related Problems

25.1 Enabling Diagnostics in Oracle Identity Manager

You can enable diagnostics in Oracle Identity Manager at run time. To do so:

1. Log in to Oracle Identity System Administration, and navigate to the Advanced Console.

2. Create a system property with the following details:

   • Property Name: OIM Diagnostic Enabled

   • Keyword: OIM.DiagnosticEnabled

   • Value: True

   You must set the OIM Diagnostic Enabled system property to enable Oracle Identity Manager diagnostics for debugging purpose. To enable diagnostics, set the vale of this property to TRUE. If the value is set to FALSE or the property is missing, then diagnostics is disabled. See "Creating and Managing System Properties" for information about creating system properties.

3. Add a logger for the diagnostic-related logging. To do so:

   1. In the DOMAIN_NAME/config/fmwconfig/servers/SERVER_NAME/logging.xml file for the application server, add a new log handler, as shown:

      Note:

      Here, DOMAIN_NAME and SERVER_NAME are the domain name and server name respectively specified during the installation of Oracle Identity Manager.

      <log_handler name='ldap-diagnostic-handler' class='oracle.core.ojdl.logging.ODLHandlerFactory' level='TRACE:16'>
      <property name='logreader:' value='off'/>
      <property name='path' value='${domain.home}/servers/${weblogic.Name}/logs/ldapsync-diagnostic.log'/>
      <property name='format' value='ODL-Text'/>
      <property name='useThreadName' value='false'/>
      <property name='locale' value='en'/>
      <property name='maxFileSize' value='5242880'/>
      <property name='maxLogSize' value='52428800'/>
      <property name='encoding' value='UTF-8'/>
      </log_handler>
      

      Note:

      • You can change the value of the path property to a different location.

      • See "Log Handler and Logger Configuration" and "Configuring Log Handlers" for detailed information about configuring loggers.

   2. Add a new logger as shown:

      Note:

      Make sure that the value of the handler name attribute is same as in step 3a.

      <logger name='oracle.iam.ldapsync.diagnostic.logger' level='TRACE:16' useParentHandlers='false'>
      <handler name="ldap-diagnostic-handler"/>
      </logger>
      

   3. Save the logging.xml file.

      Note:

      Restarting Oracle Identity Manager is not required for the new logger to take effect.

25.2 Troubleshooting Dynamic Configuration-Related Problems

This section describes the following dynamic configuration-related problems and troubleshooting steps:

• Roles in Oracle Identity Manager and Identity Store in Inconsistent State

• Postenablement of the oamEnabled Flag Causes Issues

• Run-time Evaluation of LDAP Containers Defined in LDAPContainerRules.xml

25.2.1 Roles in Oracle Identity Manager and Identity Store in Inconsistent State

Roles in Oracle Identity Manager database and the identity store, such as Oracle Internet Directory (OID), Microsoft Active Directory (AD), and Oracle Directory Server Enterprise Edition (ODSSE), can be in inconsistent state causing unexpected behavior.

As part of the provisioning process, some data, such as roles, are populated into the backend directory server, such as OID. These roles are reconciled into Oracle Identity Manager via a scheduled job so that Oracle Identity Manager and OID are in sync with respect to the roles. There can be various sets of operations that lead Oracle Identity Manager to be in an inconsistent state, as described in Table 25-1.

Table 25-1 Troubleshooting Inconsistent Roles

Problem	Solution
The following operations are performed: Roles are seeded into backend identity store as part of running provisioning, bulk load utility, or LDAP Data Interchange Format (LDIF) files. The scheduled task is run and the roles are reconciled into Oracle Identity Manager based on the changelog entries. The roles in Oracle Identity Manager and backend identity store are in sync. In Oracle Identity Manager, some of the roles are assigned to some users. This creates a referential integrity between users and the roles. The seeded roles are deleted from the backend tdentity store either manually via Oracle Directory Services Manager (ODSM), LDAP browser, or LDIF file. At the next run of the scheduled task, the delete reconciliation event is triggered and the corresponding roles must be deleted from Oracle Identity Manager. The delete reconciliation event fails in Oracle Identity Manager because the roles have dependency, and therefore, are not deleted from Oracle Identity Manager. New roles are seeded in the backend. The new roles are created under a different container. Therefore, the roles have a different DN and GUID. Assuming that the rules specified in the LDAPContainerRules are in place, the new roles with different DNs and GUIDs are reconciled into Oracle Identity Manager under different namespace. As a result, there are two roles with same display names, but under different namespace and different GUIDs. Therefore, Oracle Identity Manager and backend identity store are in inconsistent state. When an attempt is made to assign a role that is not present in the backend identity store to a user, an error occurs stating that the role does not exist in the backend identity store.	To fix the issue, perform the following steps: Identify the root cause of the error, which might involve running some subtests. Analyze the data in the diagnostic logs. Perform any suggested action in the diagnostic logs. Identify the inconsistent data for the current operation and all the related inconsistent data if there are more roles that are not in sync.
The following operations are performed: Roles are seeded into backend identity store as part of running provisioning, bulk load utility, or LDIF files. The scheduled task is run and the roles are reconciled into Oracle Identity Manager based on the changelog entries. The roles in Oracle Identity Manager and backend identity store are in sync. The backend identity store administrator changes the remote base in the Oracle Virtual Directory (OVD) configuration to a different container. Because of the change in the OVD configuration, there is a possibility that another role with same name but a different DN and GUID exists under the new container. LDAPContainerRules is also modified to add a new namespace for the new role DNs. After reconciliation, roles with the same name but different DNs or GUIDs are brought into Oracle Identity Manager. This leads to an inconsistent state in Oracle Identity Manager because the original roles cannot be mapped back into the identity store due to remote base change.	To fix the issue, perform the following steps: Identify the root cause of the error, which might involve running some subtests. Analyze the data in the diagnostic logs. Perform any suggested action in the diagnostic logs. Identify the inconsistent data for the current operation and all the related inconsistent data if there are more roles that are not in sync.

25.2.2 Postenablement of the oamEnabled Flag Causes Issues

When the oamEnabled flag in OVD configuration is set after user provisioning is done, the provisioned users do not get the reset password page.

After Oracle Identity Manager and Oracle Access Manager (OAM) is configured, the OVD adapters must be configured with the oamEnabled flag to true. The OVD adapters rely on this flag to set the appropriate Oblix attributes. Failure to do so causes the Password Reset page not being displayed as expected for the first time. This occurs because of the missing ObPasswordChangeFlag attribute in the provisioned user entry. This situation arises when the following steps are performed:

1. Users are provisioned to Oracle Identity Manager and also created in the backend identity store, such as OID, via LDAP synchronization.

2. A user tries to access a protected resource for the first time with the temporary password assigned.

   The user is to be redirected to Oracle Identity Manager Reset Password page by OAM based on the oamEnabled flag. Because the flag is not set, the user is instead allowed access to the protected resource.

3. OVD administator sets the oamEnabled flag for the OVD adapter to true.

4. A user tries to reset the password via the self service page. An error similar to the following is displayed:

   LDAP: error code 65 - Failed to find orclpwdexpirationdate in mandatory or optional attribute list.
   

To troubleshoot this issue, perform the following steps:

1. Make sure that all the Oblix-related classes are loaded in the backend identity store.

2. Add the required objectclasses and attributes to the existing user entries.

25.2.3 Run-time Evaluation of LDAP Containers Defined in LDAPContainerRules.xml

When LDAP synchronization is enabled in Oracle Identity Manager, the LDAP container in which the entries (user and role) are created is determined based on the rules defined in LDAPContainerRules.xml. The following types of container evaluations are defined in LDAPContainerRules.xml:

See Also:

"Configuring LDAP Container Rules" in Oracle Fusion Middleware Developer's Guide for Oracle Identity Manager for information about LDAP container rules

• Static: Static containers are predetermined and do not go through parameter substitution, such as:

  "<container>cn=Groups,dc=us,dc=oracle,dc=com</container>"
  

• Dynamic: Dynamic containers cannot be predetermined and are evaluated at runtime after the parameter substitution, such as:

  <container>cn=FusionGroups,cn=$Role
  Description$,dc=us,dc=oracle,dc=com</container>
  

For dynamic containers, when the value of "$Role Description" is substituted determines the container for entry creation. In addition, there can be one or more such rule elements defined with each having a different expression or container element. If the parameter passed satisfies the expression for a given rule, then the corresponding container is evaluated at runtime after parameter value substitution. Therefore, it is not possible to determine a priority for the container DN. This often leads to difficulty in analyzing the issue when an entity creation (user/role) fails because of nonexistence of evaluated container value. The diagnostics when enabled, provides run-time container evaluation, and additionally lists the possible container values based on RDN for a given rule. For instance, consider the following rule defined in LDAPContainerRules.xml:

<rule>
<expression>Role Description=*</expression>
<container>cn=FusionGroups,cn=$Role Description$,dc=us,dc=oracle,dc=com</container>
<description>$Role Description$</description>
</rule>

Because the <expression> element contains "Role Description=*", the value of "cn=$Role Description$" in the <container> element is evaluated to a parameter passed as Role Description during role creation.

If a role being created has the Role Description as Temporary Admin, then it matches the "Role Description=*" expression, and the value of the container is "cn=FusionGroups,cn=Temporary Admin,dc=us,dc=oracle,dc=com".

If the "cn=FusionGroups,cn=Temporary Admin,dc=us,dc=oracle,dc=com" container does not exist in the backend directory server, for example OID, then the diagnostics logs this information in the configured log file. In addition, the diagnostics performs a search on RDN, which is "cn=FusionGroups", for all the possible LDAP containers in the configured backend directory server and logs it. This assists in inspecting the possible containers.