test

Sun Identity Manager 8.1 System Administrator's Guide

Troubleshooting Adapters

To troubleshoot an adapter, review the adapter’s log file. Almost all adapters write their resource settings to a log file, and you can use this information to confirm that the adapter started and that all setting changes have been saved.

Note –

You must enable tracing and identify the methods for which tracing is requested before any logging can occur. Also, your custom adapter must include calls that create log entries for new methods.

If necessary, review Tracing the Identity Manager Server for instructions about how to enable tracing.

Most adapter log files are located in the $WSHOME/config directory and they are named WSTrace1.log.

Active Sync-enabled adapters that make log calls to the ActiveSyncUtil instance create a log file or set of log files in a directory specified by the Log File Path resource attribute. Be sure to check these log files for additional Active Sync-related log entries.

The information in this section is organized as follows:

To Debug an Adapter

    Follow these general steps to debug your custom adapter.

  1. Create a test program for your adapter, and be sure this Java file performs the following basic functions:

    1. Create a new resource

    2. Create a user

    3. Get a user

    4. Update a user

    5. Delete a user

    6. Perform create, get, update and delete operations on multiple users

      Note –

      A sample test file (SkeletonResourceTests.java) is provided in the /REF directory on your installation CD.

  2. Set an appropriate logging level for debugging.

    For example, for the first debugging pass, increase the logging level to 4 (maximum debugging output), set the log file path, and specify a maximum file size.

    When you start the adapter, all of the resource settings are written to the log file. You can use this information to validate that the adapter started and that all setting changes were saved.

  3. Compile and test your adapter.

    • To compile the test program, open a command window and enter the javac -d . test/filename.java command. This command creates the class file in the appropriate com/waveset/adapter/test directory.

    • To test your new adapter using this class file, be sure that your compiled adapter is in the com/waveset/adapter directory and use the following command to run the adapter:


      java– D waveset.home=path com.waveset.adapter.test.
MyResourceAdapter

  4. Create an HTML help file for your resource.

    Note –

    • Example help files are supplied in the idm.jar file located in the com/waveset/msgcat/help/resources directory.

    • See Sun Identity Manager Deployment Reference for information about how to include online help with the application.

  5. (For Active Sync-enabled adapters only) To reset synchronization on the last resource, delete the XmlData SYNC_resourceName object.

  6. Read the error log and modify the adapter.

  7. Reset the logging level.

    For example, specifying Level 2 debugging yields information about the adapter settings and any errors, but limits the amount of log detail to a manageable level.

  8. Before starting Identity Manager, you must identify the new adapter in the $WSHOME/config/Waveset.properties file by placing the adapter name under the resource.adapters entry or Identity Manager cannot recognize the adapter.

  9. Install your adapter and its associated help file into Identity Manager.

    Note –

    Before Identity Manager can recognize an instance of a new adapter in the display, you must create a new resource of that type from the List Resource page.

    From this page, select New -> new adapter and use the Resource Wizard to create the new adapter.

  10. Use Identity Manager to create a resource and a user on that resource.

    Tip –

    When troubleshooting an Active Sync-enabled adapter, if you edit the XmlData SYNC_resourceName object to remove the MapEntry for the Active Sync synchronization process from the Debug page, the adapter starts over from the first detected change.

    If you used the IAPI event, you must set the Property() method to store synchronization state for the resource, such as a last change processed value. Setting this method is very useful for troubleshooting adapters. You can set the adapter to run and ignore past changes. Subsequently, you can modify the adapter and see your change results in the adapter log file.

    If your resource is an Active Sync resource, you might see additional information if you enable logging on the resource edit page. Set the logging level (0-4) and the file path where the log file will be written (as resource_name.log).

  11. (For Active Sync-enabled adapters only) Restart synchronization for the last resource.

To Debug LoginConfig Changes

To debug LoginConfig-related changes to your adapter, you must

  1. Enable trace for the selected files and trace the following classes at Method/Class Level 1 trace:

    • com.waveset.security.authn.WSResourceLoginModule

    • com.waveset.session.LocalSession

    • com.waveset.session.SessionFactory

    • com.waveset.ui.LoginHelper

    • com.waveset.ui.web.common.ContinueLoginForm

    • com.waveset.ui.web.common.LoginForm

  2. Test Single Sign-On (SSO) pass-through authentication login through Telnet as follows:

    1. After correctly configuring the SSO login module, telnet directly to the HTTP port and send an HTTP request to login.jsp.

    2. Paste the following request, which contains an SSO login module that looks for the sm_user HTTP header, into your telnet session:


      HEAD /idm/login.jsp HTTP/1.0
Accept: text/plain,text/html,*/*
Accept-Language: en-us
Accept-Encoding: gzip, deflate
User-Agent: Mozilla/4.0
Host: LOCALHOST
sm_user: Configurator

      A trace displays to indicate that your user has logged in correctly. For example:


      2003.07.08 14:14:16.837 Thread-7 
WSResourceLoginModule#checkForAuthenticatedResourceInfo()
Found authenticated resource accountId, ’Configurator@Netegrity 
SiteMinder’on Identity Manager user ’Configurator’. 
null null 2003.07.08 14:14:16.837 
Thread-7 WSResourceLoginModule#checkForAuthenticatedResourceInfo()
Exit null null 2003.07.08 14:14:16.837 Thread-7 WSResourceLoginModule#login()
Exit, return code = true null null 2003.07.08 14:14:16.847
Thread-7 LocalSession#login() Login succeeded via Netegrity SiteMinder 
null null 2003.07.08 14:14:16.847 Thread-7 LocalSession#login() 
Overall authentication succeeded null null 2003.07.08 14:14:16.897 Thread-7 
LocalSession#checkIfUserDisabled() 
Entry null null 2003.07.08 14:14:16.897 Thread-7 
LocalSession#checkIfUserDisabled() Exit 
null null 2003.07.08 14:14:16.927 Thread-7 LocalSession#login() 
Exit null null

To Debug Adapter Connection Problems

This section describes methods for debugging some common adapter connection problems.

The topics in this section are organized as follows:

Note –

Generally, you can identify adapter connection issues by tracing the adapter class com.waveset.adapter.adapter_classname. For example:

com.waveset.adapter.ADSIResourceAdapter

If necessary, review instructions for enabling trace in Tracing the Identity Manager Server.

Adapter Authentication Problems

Some common authentication problems include

Active Sync Adapter Problems

The most common problems with custom Active Sync adapters are form-related. These errors generally occur because you have not provided necessary information, such as password or email information, in a required field.

Identity Manager prints form validation errors to the adapter log after the final XML of the view. For example:


20030414 17:23:57.469: result from submit (blank means no errors):
 20030414 17:23:57.509: Validation error: missing required field password

Identity Manager also prints all messages to the adapter log. These messages include account creation and update times, adapter errors, and a summary of the schema map data.

Active Sync resource adapters store information about the last change processed in the SYNC.resourceName XMLData object.

Domino Gateway Adapter Problems

Following are some common Domino gateway and adapter configuration errors and instructions for fixing these problems:

Mainframe Host Adapter Problems

When RACF, ACF2, or TopSecret host adapters fail to reuse or cache connections, users are forced to log in frequently, which negatively impacts performance. Generally, the cache timeout setting causes this problem.

    To check the cache timeout setting, trace Identity Manager’s adapter connection pool as follows:

  1. From Identity Manager’s Edit Configuration Object page, trace the com.waveset.adapter.HostConnPool#reapConnections method at level 4.

    If necessary, review instructions for enabling trace in Tracing the Identity Manager Server.

  2. Capture trace for a sufficiently long period of time (at least 30-60 minutes), while the adapter performs operations.

  3. Review the trace output in the application server stdout or trace file and look for Info reaping connection entries.

    If this entry occurs more than once every 30 minutes, you have a good indication that connections are being timed out unnecessarily.

    To resolve this problem, increase the Idle Timeout resource attribute value to prevent connections from being reaped too frequently. The Idle Timeout attribute controls how long a connection remains idle before the connection is logged out. The default value is 90 seconds, which causes new logins to occur frequently.

    Ideally, specify a value that is greater than the average idle time for your deployment environment. For example, adjust the Idle Timeout attribute to 30 minutes (1800000 milliseconds) or more.

PeopleSoft Adapter Problems

This section describes methods for troubleshooting the following PeopleSoft adapter problems:

SAP Adapter Problems

If an error results when you try to test the connection from an SAP or SAP HR Active Sync adapter to the SAP system, open a command window and run this command from your installation directory WEB-INF/lib:

java -jar sapjco.jar

The sapjco.jar command shows which version of the SAP Java Connector (JCO) is installed and whether the adapter is installed correctly. The command also returns the JavaTM Native Interface (JNITM) platform-dependent and the RFC libraries that communicate with the SAP system.

If these platform-dependent libraries are not found, consult the SAP documentation to find out how to correctly install the SAP Java Connector.

UNIX Adapter Problems

This section contains information about debugging some common problems with UNIX adapters.