A Troubleshooting

A.1 Log Files

These OracleAS log files record data about single sign-on operations.

• General log file for the single sign-on server:

  ORACLE_HOME/sso/log/ssoServer.log
  
  

  Usage Notes:

  The single sign-on server writes all errors to this file. You can change the default location by editing ORACLE_HOME/sso/conf/policy.properties. You can also use this file to change the logging level.

• Startup error log for single sign-on server:

  ORACLE_HOME/opmn/logs/OC4J~OC4J_SECURITY~default_island~1
  
  

  Usage Notes:

  This OC4J-generated file reports any errors that occur when the single sign-on server is started. Check the file for error messages if the opmnctl command hangs or if it reports errors on the command line when the OC4J_SECURITY instance is started.

• Web application log:

  ORACLE_HOME/j2ee/OC4J_SECURITY/application-deployments/sso/OC4J_SECURITY_default_island_1/application.log
  
  

  Usage Notes:

  This file reports run-time errors for OC4J applications.

• OC4J servlet access log:

  ORACLE_HOME/j2ee/OC4J_SECURITY/log/OC4J_SECURITY_default_island_1/default-web-access.log
  
  

  Usage Notes:

  Another OC4J-generated file. The file contains the servlet access logs for single sign-on. Check the file to determine whether the authentication request was received by the authentication servlet.

• Error log for Oracle HTTP Server:

  ORACLE_HOME/Apache/Apache/logs/error_log
  
  

  Usage Notes:

  If the Oracle HTTP Server is configured to rotate its log files, it appends a timestamp to these files. Use this timestamp to find the latest file.

• Access log for Oracle HTTP Server:

  ORACLE_HOME/Apache/Apache/logs/access_log
  
  

  Usage Notes:

  If the Oracle HTTP Server is configured to rotate its log files, it appends a timestamp to these files. Use this timestamp to find the latest file.

A.2 Error Messages and Other Problems

This section explains how to address error messages and other problems. It devotes sections to the following:

• Basic Error Messages and Problems

• Certificate Authentication

• Password Policies

• Type 41400 Errors

A.3 Increasing the Debug Level

OracleAS Single Sign-On provides four levels of debugging. They are listed here in ascending order of detail provided.

• ERROR—log errors only

• WARN—log both errors and warning messages

• INFO—log informational messages—current date and time, for instance—as well as errors and warnings

• DEBUG—log details about program execution as well as errors, warnings, and informational messages

In the course of debugging, you may have to increase the level of debugging to, say, DEBUG. You do this by modifying the file ORACLE_HOME/sso/conf/policy.properties.

After changing the debug level, restart the OC4J_SECURITY instance:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY

A.4 Enabling the Debug Option in the Single Sign-On Database

Occasionally you may need to debug the mod_plsql code used to access external applications. This task requires that you enable debugging on the single sign-on database and then view detail logs. Note that this procedure does not apply to the debugging of partner applications. Debugging information for these applications is stored only in ORACLE_HOME/sso/log/ssoServer.log.

To turn on mod_plsql debugging, log in to the ORASSO schema and run the ssolsdbg.sql script. See Appendix B to obtain the schema password. Be sure to uncomment the commented lines in the script before running it. A copy of the script is located at ORACLE_HOME/sso/admin/plsql/sso.

Here is the script:

set scan off;
set feedback ON;
set verify ON;
set pages 50000;
set serveroutput ON;

CREATE OR replace PROCEDURE debug_print (str VARCHAR2) AS
BEGIN


   INSERT INTO wwsso_log$ VALUES (wwsso_log_pk_seq.nextval,
      substr(str, 1, 1000),
      sysdate, dbms_session.unique_session_id);

   commit;


END debug_print;
/

show errors;

To query the debug logs, issue this command:

SELECT * FROM WWSSO_LOG$ ORDER BY ID;

To turn off debugging, log in to the ORASSO schema and create the PL/SQL script that follows. Be sure to include this step when you finish debugging. If you skip it, superfluous records are created in the database table. See Appendix B to obtain the schema password.

set scan off;
set feedback ON;
set verify ON;
set pages 50000;
set serveroutput ON;


CREATE OR replace PROCEDURE debug_print (str VARCHAR2) AS
--  PRAGMA autonomous_transaction;
BEGIN

    null;

END debug_print;
/

show errors;

A.5 Enabling LDAP Tracing for UI Operations

The administration pages for single sign-on use the DBMS_LDAP package to perform directory operations. You can obtain details about these operations in the debug logs for the single sign-on database. To pinpoint the error though, you must enable client-side LDAP tracing. In trying, for example, to determine why an administrator cannot see administration links on the single sign-on home page, you can determine the exact point at which an error is being returned by the LDAP client-side APIs. You can then find the trace results in the RDBMS trace files.

Follow these steps to perform client-side tracing:

1. Enable tracing by loading the debugonldap.sql package into the ORASSO schema:

   SQL> connect orasso/password
   
   

   See Appendix B to obtain the schema password.

2. Run the script:

   SQL> @debugonldap.sql
   
   

   debugonldap.sql looks like this:

   set scan off;
   set feedback ON;
   set verify ON;
   set pages 50000;
   set serveroutput ON;
   
   CREATE OR replace PROCEDURE debug_print (str VARCHAR2) AS
   BEGIN
   
      dbms_ldap.set_trace_level(65535);
   
      INSERT INTO wwsso_log$ VALUES
        (wwsso_log_pk_seq.nextval, substr(str, 1, 1000), sysdate,
        dbms_session.unique_session_id);
   
       commit;
   
   
   END debug_print;
   /
   
   show errors;
   
   

3. Perform a single sign-on operation that raised an error or that requires debugging—logging in to the home page as an administrator, for instance.

4. Examine the LDAP client logs in the RDBMS trace directory. You can determine the location of this directory by connecting as SYS to the identity management infrastructure database and then issuing this command:

   SQL> show parameter user_dump_dest
   
   

   The value returned is the directory where trace files are written. Once in the directory, examine the file timestamps to find the relevant file.

If the client-side trace files fail to reveal the problem, enable server-side tracing, but perform client-side tracing first. To enable server-side tracing, see the chapter about logging, auditing, and monitoring in Oracle Internet Directory Administrator's Guide.

To disable tracing, load and run this package:

set scan OFF;
set feedback ON;
set verify ON;
set pages 50000;
set serveroutput ON;

CREATE OR replace PROCEDURE debug_print (str VARCHAR2) AS BEGIN
null;
END debug_print;
/
show errors;

A.6 Managing Single Sign-On Audit Records

The single sign-on server records authentication failures and successes in the Oracle Identity Management database. In time, the audit table, ORASSO.WWSSO_AUDIT_LOG_TABLE_T, runs out of space. When this happens, this error message appears in database alert logs:

ORA-1654: unable to extend index ORASSO.AUDIT_INDEX1 by 128 in tablespace IAS_META

In addition, further authentication requests fail.

Be sure to monitor ORASSO.WWSSO_AUDIT_LOG_TABLE_T regularly. When it becomes full, either back up the table and free up space or add space. Note that this is an internal, product-specific table. This means that you can use SQL*Plus to clean up the table, but you cannot use this tool or any other tool to build reporting or monitoring scripts based on the table.

A.7 Refreshing the LDAP Connection Cache

For performance reasons, the single sign-on server caches connections to Oracle Internet Directory. If the directory server has a scheduled or unscheduled outage, the single sign-on server is left holding bad directory connections, and users may encounter directory setup errors when they try to access external applications. If the LDAP connection cache is invalid, the Oracle HTTP Server must be restarted:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server

Use the following steps to determine whether the LDAP connection cache must be refreshed:

1. Connect to the single sign-on schema. See Appendix B to obtain the schema password.

2. Issue the following command:

   SELECT * FROM WWSSO_LOG$
   
   

3. Restart the HTTP server if you see the following error in the log:

   'INVALID LDAP CONNECTION CACHE: RESTART ORACLE HTTP SERVER'
   
   

4. Delete the error message from WWSSO_LOG$.

A.8 Restarting OC4J After Modifying Oracle Internet Directory

If you change values in Oracle Internet Directory, you must update the single sign-on server with the changes. If, for example, you change a user, subscriber, or group search base in the directory and fail to "notify" the single sign-on server, users under the modified container are unable to log in. The ssoreoid.sql script updates the single sign-on server with directory changes. To learn how to run the script, see "Updating the Single Sign-On Server with Directory Changes" in Chapter 3.

After running the script, make sure that you restart the single sign-on server:

ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=HTTP_Server
ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_SECURITY

A.9 Troubleshooting Replication

Deploying geographically distributed single sign-on instances requires, among other things, that you replicate the identity management infrastructure database. Each time you replicate the database, you should validate the replication process on each replicated node and correct errors that you find. Use the Replication Environment Management Tool (remtool) to complete both tasks.

remtool is run on the master definition site. You can find the tool at ORACLE_HOME/ldap/bin. It can be executed in two modes as the sections that follow explain.

remtool -asrverify

remtool -asrrectify -v -connect repadmin/repadmin_password@net_service_name

-v

-connect

A.10 A Word About Non-GET Authentication

The first page of a mod_osso-protected application must be a URL that uses the GET authentication method. If the POST method is used, the data that the user provides when logging in is lost during redirection to the single sign-on server. When deciding whether to enable the global user inactivity timeout, note that users are redirected after timing out and logging in again.

A.11 Need More Help?

You can find more solutions on Oracle MetaLink, http://metalink.oracle.com. If you do not find a solution for your problem, log a service request.