A Troubleshooting OracleAS Single Sign-On

A.1.1 Internal Server Error

When accessing OracleAS Single Sign-On, you may encounter an "Internal Server Error" message if the single sign-on server was started incorrectly or is unable to connect to infrastructure components.

Problem 1

Users see the following error message when contacting the single sign-on server:

Internal Server Error. Please contact administrator.

This error message usually appears when the single sign-on server is started incorrectly.

Solution 1

Use the following sequence to solve the problem:

1. Verify that the single sign-on server was started correctly by checking the startup log file: ORACLE_HOME/opmn/logs/OC4J~OC4J_SECURITY~default_island~1.

2. If the log file reports errors for the database or for Oracle Internet Directory, make sure that both are up and running before starting the single sign-on server. If you see the message SSOLoginServlet.init: SSO server started, the single sign-on server has been started correctly.

3. Next, check the log file for the single sign-on server: ORACLE_HOME/sso/log/ssoServer.log.

4. If the log file contains the error message NumberFormatException or a specific configuration parameter not found, check policy.properties for blank spaces. Remove spaces that occur at the end of the line containing the questionable configuration; then restart the OC4J_SECURITY instance:

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

5. If the file ORACLE_HOME/opmn/logs/OC4J~OC4J_SECURITY~default_island~1 reports the error message Orion Launcher SSO Server initialization failed, do the following:

   • Make sure that the database is available; then 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
     
     

   • If the database is available, the problem may be the directory connection. Check the opmn log. If you see the error message that follows, run ssooconf.sql to ensure that directory access is properly configured in the single sign-on database.

     java.lang.NumberFormatException: null
       at java.lang.Integer.parseInt(Integer.java:442)
       at java.lang.Integer.parseInt(Integer.java:524)
       at oracle.security.sso.server.conf.DatabaseConfigReader.
       setSSOServerConfig(DatabaseConfigReader.java:322)
     
     

6. To learn how to run ssooconf.sql, see "Changing Single Sign-On Server Settings for Directory Access" in Chapter 3.

Problem 2

Users see the following error message when contacting the single sign-on server:

Internal Server Error. Please try the operation later.

This error message appears when either the infrastructure database or Oracle Internet Directory is unavailable or is down.

Solution 2

Check ORACLE_HOME/sso/log/ssoServer.log for a detailed description of the message; then try restarting the database or the directory, depending upon what you find.

A.1.2 Unexpected Error

Users see the following error when contacting the single sign-on server:

Unexpected Error. Please contact administrator.

Problem

This message may indicate a server-side error. The policy.properties file may be misconfigured, or Java classes may not be loaded. Another cause may be that the partner application is registered incorrectly.

Solution

Try the following steps to determine the cause of the problem:

1. Check the following log files for error messages:

   The single sign-on server log: ORACLE_HOME/sso/log/ssoServer.log

   The Oracle HTTP Server error log: ORACLE_HOME/Apache/Apache/logs/error_log

2. Try to log on to the OracleAS Single Sign-On administration pages. Be sure to log in as orcladmin, not as cn=orcladmin.

   http://single_sign-on_host:single_sign-on_port/pls/orasso
   
   

3. If you are able to log in, the problem is not with the single sign-on server, but with the partner application registration or with the application itself.

A.1.3 File Not Found Error

When accessing the single sign-on server, users see the following error message:

File Not Found.

Problem

Check the Oracle HTTP Server error log (ORACLE_HOME/Apache/Apache/logs/error_log).If you find the message file not found, Oracle HTTP Server is not delegating the authentication request to OC4J.

Solution

Perform the following checks:

1. Check mod_oc4j.conf for single sign-on application mappings. The mount configuration Oc4jMount/sso OC4J_SECURITY should be present.

2. Check default-web-access.log to determine whether the authentication request was received by the servlet.

A.1.4 Authentication Failed

Users may see an Authentication Failed error after logging on to OracleAS Single Sign-On.

Problem

The user's password is incorrect, or the server does not have the permissions necessary to authenticate the user.

Solution

1. Try binding to the directory as the user, making sure that the user DN corresponds to the appropriate realm:

   ORACLE_HOME/bin/ldapbind 
   -h directory_server
   -p directory_ssl_port
   -D user_dn
   -w user_password
   -u 1
   
   

   If the bind fails, the user's password is incorrect. Reset the password. If the bind succeeds, proceed to step 2.

2. Try binding to the directory as the single sign-on server:

   ORACLE_HOME/bin/ldapbind 
   -h directory_server
   -p directory_ssl_port
   -D orclApplicationCommonName=ORASSO_ 
    SSOSERVER,cn=SSO,cn=Products,cn=OracleContext
   -w single_sign-on_server_password
   
   

   If the bind fails, the server password that you are trying to bind with may be incorrect. To set the correct password, run ssooconf.sql as explained in "Changing Single Sign-On Server Settings for Directory Access" in Chapter 3. If the bind succeeds, proceed to step 3.

3. Check whether the single sign-on application is a member of the SecurityAdmins group. If it is not a member of this group, it cannot authenticate the user:

   ORACLE_HOME/bin/ldapcompare 
   -h directory_host
   -p directory_ssl_port
   -D orclApplicationCommonName=ORASSO_
    SSOSERVER,cn=SSO,cn=Products,cn=OracleContext
   -w orasso_password
   -b "cn=user_dn,cn=users,realm_dn"
   -a userpassword
   -v user_password
   
   

   If the application is not a member, add it to the SecurityAdmins group (cn=OracleUserSecurityAdmins,cn=Groups,cn=OracleContext) and have the user reauthenticate. If the application is a member, the problem may be directory based.

A.1.5 The User Name Submitted for Authentication Does Not Match the User Name Present in the Existing Single Sign-On Session

Problem

Users encounter this error only during a forced authentication request. They see the error because they fail to enter the same user ID and, optionally, realm that they entered when they first authenticated.

Solution

The user ID and, optionally, realm entered during forced authentication must match the user ID and realm in the current single sign-on session. Users who want to use different credentials to log in must log out of the current session first.

A.1.6 Forbidden Error When Accessing OracleAS Single Sign-On Administration

When trying to access the OracleAS Single Sign-On Administration page, users see the following error:

Forbidden. You don't have permission to access .../pls/orasso/orasso.home on this server.

Problem

This message may appear when you try to access the single sign-on administration URL. Perhaps the password for the ORASSO schema was changed in the database, but not in the dads.conf file.

Solution

Perform these steps:

1. Update ORACLE_HOME/Apache/modplsql/conf/dads.conf.

2. Restart the Oracle HTTP Server:

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

3. If the schema password is correct to begin with, check the Oracle HTTP Server error log for error messages: ORACLE_HOME/Apache/Apache/logs/error_log.

A.1.7 White Page Displayed When Accessing OracleAS Single Sign-On Administration

When logging on to OracleAS Single Sign-On administration pages the administrator sees a blank white page.

Problem 1

The PUBLIC user entry is missing from Oracle Internet Directory, or the user nickname attribute was changed in the directory, but the new attribute was not added to the PUBLIC entry.

Solution 1

Add the PUBLIC user entry under the user search base in the directory. If, instead, the user nickname attribute was changed, add the attribute to the PUBLIC user entry.

Problem 2

The single sign-on server is configured with the wrong information for the directory.

Solution 2

Run ssooconf.sql to configure the single sign-on server with the correct directory information. To learn how to run the script, see "Changing Single Sign-On Server Settings for Directory Access" in Chapter 3.

Problem 3

There may be installation problems, namely, a missing Enabler entry or faulty SSL registration.

Solution 3

Run ssooconf.sql to update the single sign-on server with the enabler entry or to modify single sign-on URLs for SSL.

Problem 4

The directory DIT has changed and the single sign-on server has not been updated with the changes.

Solution 4

Run ssoreoid.sql to update the single sign-on server with directory DIT changes.

A.1.8 Administrator Cannot See OracleAS Single Sign-On Administration Pages

The administrator does not see the OracleAS Single Sign-On administration pages when logging in to.../pls/orasso.

Problem

The administrator is not a member of the iASAdmins group:

cn=iASAdmin,cn=Groups,cn=OracleContext,realm_dn

Solution

Check the uniquemember attribute of the iASAdmins entry in the directory:

ldapsearch -h directory_host
           -p directory_port
           -D orclApplicationCommonName=ORASSO_
              SSOSERVER,cn=SSO,cn=Products,cn=OracleContext
           -w orasso_password
           -b "cn=iasadmins,cn=groups,cn=oraclecontext,realm_dn"  
              "uniquemember=cn=user,cn=users,realm_dn"

If the user in the command is not a unique member of iASAdmins, follow the instructions in "Granting Administrative Privileges" in Chapter 2.

A.1.9 The "SSO Server Administration" Link is Missing from the OracleAS Single Sign-On Administration Page

Problem

Only administrators see this link. The user who is missing the link is logged in as an end user.

Solution

Make sure that the user is a member of the iASAdmins group:

cn=iASAdmins,cn=Groups,cn=OracleContext,dc=default_identity_management_realm

If you have changed the OracleAS Single Sign-On administration group, make sure that the user is a member of this group.

A.1.10 Audit Log Insertion Exception: ORA-00018: Maximum Number of Sessions Exceeded

This message appears when the load on the single sign-on server is heavy.

Problem

The number of database sessions required has exceeded the number specified in the init.ora file.

Solution

Change the properties of the identity management infrastructure database. Specifically, increase the processes and sessions parameters to match anticipated load. Use a database-specific configuration file such as init.ora to make the change. init.ora is found at ORACLE_HOME/dbs.

A.1.11 Connection Limit Exceeded

Problem

This message is a variation of the message: Audit Log Insertion Exception: ORA-00018: Maximum Number of Sessions Exceeded.

Solution

The end user should retry the operation, or the administrator can increase the connection limit.

A.1.12 Failed Login Message when System has been Idle

Users may see a login failure error when OracleAS Single Sign-On is operating behind a firewall and has been idle for some time.

The following text appears in ssoserver.log:

AJPRequestHandler-ApplicationServerThread-11 DB connection error 
java.sql.SQLException: Closed Connection 
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:189) 
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:231) 
at oracle.jdbc.dbaccess.DBError.throwSqlException(DBError.java:294)

Problem

A firewall protects the OracleAS Single Sign-On and Oracle Internet Directory servers in a typical production environment. The firewall tracks connection activity and drops inactive database or directory connections after a period controlled by the firewall timeout value.

If the single sign-on server has not been notified about a dropped database connection, it may try to perform an operation using the stale connection, resulting in this error.

Solution

Take the following steps to resolve the database connection problem:

1. Determine the firewall timeout value.

2. Locate the sqlnet.ora file which resides in the OracleAS Single Sign-On database ORACLE_HOME:

   $ORACLE_HOME/network/admin/sqlnet.ora

   Edit this file to add the sqlnet expiry time, setting it to a value smaller than the firewall timeout value. For example:

   # Use a value in minutes smaller than the firewall timeout value
   SQLNET.EXPIRE_TIME = 20 
   
   

   In this example, the firewall timeout value is 25 minutes and so we use a smaller value, 20 minutes, for SQLNET.EXPIRE_TIME.

3. Stop and restart the database server and the listener after adding the above parameter into the sqlnet.ora file.

A.1.13 Error due to Idle LDAP Connection Timeouts

OracleAS Single Sign-On server may display an internal server error while logging in, if the system is configured with an LDAP firewall and the firewall drops idle LDAP connections.

Problem

When there is a firewall between Oracle Application Server Single Sign-On and the LDAP server, you may encounter login errors when the firewall drops an inactive LDAP connection.

Solution

You can set a parameter to control the duration of OracleAS Single Sign-On server's LDAP connections. This is known as the connectionIdleTimeout parameter; you can specify its value, in minutes, in the policy.properties configuration file. The parameter is useful in deployments that utilize a firewall between OracleAS Single Sign-On and the LDAP server. If an LDAP connection is idle for a period longer than this parameter value, then OracleAS Single Sign-On server will remove that connection from the pool and try to use a fresh connection from the pool.

Take the following steps to set the LDAP connection timeout:

1. Edit the ORACLE_HOME/sso/conf/policy.properties file to add or update the parameter value. In the following example, the idle timeout value is set to 120 minutes.

   connectionIdleTimeout = 120
   
   

2. Restart OracleAS Single Sign-On by restarting OC4J.

A.1.14 Login to Portal Fails

When users try to log in to Portal or an application that is protected by OracleAS Single Sign-On, they see one of the following errors:

• Unexpected error encountered in wwsec_app_priv.process_signon (User-Defined Exception) (WWC-41417)

• An entry was not found in the Oracle Internet Directory (error status: -5: The specified user does not exist in the directory

• Details Operation: dbms_ldap_utl.get_group_membership). (WWC-41745)

Problem

This occurs because the single sign-on server caches user entries by default. If a user has been deleted and recreated in Oracle Internet Directory, the user entry's orclGUID attribute has changed, thus causing the cache to be out of synch with the directory data. When the application then tries to access the user entry in Oracle Internet Directory, the orclGUID value that is returned by the single sign-on server does not match the orclGUID of the entry.

This can also happen when adding and deleting users to a realm that has multiple search bases configured (orclcommonusersearchbase attribute in the cn=Common,cn=Products,cn=OracleContext entry). If, for example, a user with the same nickname exists in more than one search base and then the user entry in the first listed search base is deleted, this can cause a mismatch between the cache and the directory data.

Solution

Disable the cache by performing the following steps:

1. Take back up of /sso/conf/policy.properties.

2. Edit the policy.properties file and change cacheSize=1000 to cacheSize=0.

3. Restart the single sign-on server:

   opmnctl restartproc process-type=OC4J_SECURITY

A.2.1 The site2pstoretoken Value Is Missing

Problem

The deployment-specific login page does not accept site2pstoretoken. Users see a WWC-41400 error after presenting their credentials.

Solution

Rewrite the login page to accept the site2pstoretoken and pass it back to the single sign-on server.

A.2.2 The site2pstoretoken Value Is Blank ("")

Problem

The user has accessed the single sign-on login URL directly from the browser.

Solution

The user must first access an application protected by mod_osso or an application integrated with the now-deprecated single sign-on SDK.

A.2.3 Login Parameters Are Lost During Redirection to a Third-Party Server

Problem

The user has used the POST method to access the single sign-on server. During login a third-party URL is invoked. In release 9.0.2, POST parameters are lost during redirection to the third-party server. This problem does not arise in release 9.0.4 and release 10.1.2 because mod_osso uses the GET method.

Solution

Use an extra page that uses GET to pass login parameters to the single sign-on server.

A.2.4 The site2pstoretoken Has an Incorrect Site ID

Problem

The partner application has been deleted from single sign-on configuration tables.

Solution

Reregister the partner application. See "Registering mod_osso" in Chapter 4.

A.2.5 The Site ID Is Obsolete

Problem

The registration that generated the ID may have been removed because it was obsolete.

Solution

Determine whether the correct version of the osso.conf file is referenced in the OssoConfigFile directive of the mod_osso.conf file. This file is found at ORACLE_HOME/Apache/Apache/conf. It may have been overwritten accidently. If you determine that the osso.conf file is incorrect, reregister the partner application. See "Registering mod_osso" in Chapter 4.

A.2.6 A Virtual Host Is Incorrectly Configured

Problem

If the site2pstoretoken has a correct site ID, an error is thrown because an incorrectly configured virtual host is being used to access the single sign-on server. The VirtualHost container of the httpd.conf file—or the ssl.conf file if an HTTPS virtual host is defined—is missing the directives RewriteEngine On and RewriteOptions inherit. Invalid directives may be present as well.

Solution

Add the missing directives to httpd.conf or ssl.conf. Check for invalid directives. Both files are found at ORACLE_HOME/Apache/Apache/conf.

A.3.1 Network Error: Connection Refused

Problem

This message appears when the user tries to access a partner application over SSL. The parameter SSLEngine on may be missing from httpd.conf or may not have been entered correctly.

Solution

Add the missing parameter as specified in "Setting SSL Parameters" in Chapter 8. If the parameter is present and is entered correctly, the Oracle HTTP Server log file may identify the problem.

A.3.2 The Single Sign-On Server Fails to Prompt the User for a Certificate

Problem

The optional parameter SSLVerifyClient is missing from httpd.conf or has not been entered correctly.

Solution

Add the missing parameter as specified in "Setting SSL Parameters" in Chapter 8. If the parameter is present and is entered correctly, the Oracle HTTP Server log file may identify the problem.

A.3.3 Certificate Authentication Fails - User Is Presented with the Login Page

Problem

The user's certificate is missing from the directory or has been entered incorrectly. Check ssoServer.log for details.

Solution

Reenter the user's certificate in the directory. See the instructions in "Oracle Internet Directory" in Chapter 8.

A.3.4 User's Browser Certificate Not Found

Problem 1

The user's certificate is not in the browser.

Solution 1

Install a valid certificate in the user's browser.

Problem 2

The SSL wallet on the Oracle HTTP Server may not contain the trusted certificate of the CA that issued the client certificate.

Solution 2

Use Oracle Wallet Manager to determine whether the SSL wallet contains the trusted certificate. To learn how to use the tool, see the chapter about managing wallets and certificates in Oracle Application Server Administrator's Guide.

A.3.5 Mapping Module Class Name Not Found

Problem

The class name for the mapping module is missing from x509CertAuth.properties or is incorrect.

Solution

Make sure that a value is assigned to the parameter CertificateMappingModule. If it is assigned, check that this value is correct.

A.3.6 Mapping Module Instance Creation Failed

Problem

The customized mapping module has been incorrectly implemented.

Solution

Ensure that the custom module has a default constructor.

A.3.7 Cannot Create the Mapping Module Object

Problem

The customized mapping module has been incorrectly implemented.

Solution

Ensure that the customized module implements the interface prescribed in "Customize the User Name Mapping Module (Optional)" in Chapter 8.

A.3.8 Exception in Creating Mapping Module

Problem

The customized mapping module has been incorrectly implemented.

Solution

Ensure that the customized module implements the interface prescribed in "Customize the User Name Mapping Module (Optional)" in Chapter 8.

A.3.9 Certificate Match Failed

Problem

The user's certificate is missing from the directory or has been entered incorrectly. Check ssoServer.log for details.

Solution

Reenter the user's certificate in the directory. See the instructions in "Oracle Internet Directory" in Chapter 8.

A.4.1 A User Cannot Access a URL After Authenticating in Windows

A user who is able to authenticate in their Windows environment with Microsoft Active Directory cannot access a URL through OracleAS Single Sign-On. The user may see one of the following error messages:

Access Forbidden

HTTP error code 403

Windows Native Authentication Failed. Please contact your administrator.

Problem

This can be caused by one of the following problems:

• The required user entry cannot be found in Oracle Internet Directory preventing the user from accessing the URL via OracleAS Single Sign-On.

• If a user is only logged in to the local domain, for example if the user logged in as administrator on their local machine, the enterprise identity of that user is not known to OracleAS Single Sign-On.

Solution

Try the following to make sure the user identity is recognized in both Microsoft Active Directory and Oracle Internet Directory:

1. Log in to the Windows desktop environment as a user identity that is known in Microsoft Active Directory. Make sure you log in as an actual user and log in to an Microsoft Active Directory domain (not just the local machine).

2. Once you are sure that the user identity is valid in the Microsoft Active Directory domain, verify that the user identity exists in Oracle Internet Directory. If the user does not exist, use the oditest utility to troubleshoot any problems with your Microsoft Active Directory synchronization profile.

   See the Troubleshooting appendix in the Oracle Identity Management Integration Guide for more information about the oditest utility.

3. If the user does exist in Oracle Internet Directory, determine whether the Kerberos principal attributes for the user have been properly synchronized from Microsoft Active Directory into Oracle Internet Directory. You can use the oditest and diptester utilities to troubleshoot any problems with your Microsoft Active Directory synchronization profile.

   See the Troubleshooting appendix in the Oracle Identity Management Integration Guide for more information about the oditest and diptester utilities.

A.4.2 A User Who Is Already Authenticated in Windows Cannot Authenticate in the Browser

The user's browser does not authenticate a user who has already authenticated in their Windows environment with Microsoft Active Directory.

Problem

The user's browser does not support Windows Kerberos authentication or is not configured properly.

Solution

See the Oracle Identity Management Integration Guide for instructions on configuring the browser to use Windows native authentication.

A.4.3 single sign-on server Fails to Start with a Credential Not Found Error

The single sign-on server fails to start and its startup log file, ORACLE_HOME/opmn/logs/OC4J~OC4J_SECURITY~default_island~1, contains the following error message:

Credential not found.

Problem

The parameter kerberos-servicename may not be configured correctly.

Solution

A.4.4 Single Sign-On Server Displays Internal Server Error

The single sign-on server displays the following error message when using Windows native authentication:

Internal Server error. Please contact your administrator.

Problem

Windows native authentication is not configured correctly on the OracleAS Single Sign-On middle tier.

Solution

A.4.5 Single Sign-On Users Unable to Authenticate to KDC

Users who are using Windows native authentication see the following error:

Could not authenticate to KDC.

Problem

The realm name in the Kerberos configuration file, krb5.conf, is not configured correctly.

Solution

Check the values default_realm and domain_realm in /etc/krb5/krb5.conf. Note that the realm name is case sensitive.

A.4.6 Windows Login Dialog Appears When Accessing a Partner Application

A user who has already authenticated in the Windows environment with Microsoft Active Directory is prompted with the Windows login dialog (username, password, and domain prompt) when trying to access an OracleAS Single Sign-On partner application.

Problem

The single sign-on server is not able to authenticate the Kerberos token because the corresponding user entry cannot be found in Oracle Internet Directory.

Solution

Add the user entry to Oracle Internet Directory, preferably by synchronizing user entries from Microsoft Active Directory into Oracle Internet Directory. You can use the oditest and diptester utilities to troubleshoot any problems with your Microsoft Active Directory synchronization profile.

See the Troubleshooting appendix in the Oracle Identity Management Integration Guide for more information about the oditest and diptester utilities.

A.5.1 A Disabled User Can Still Log In

The administrator disabled a user using the orclIsEnabled attribute in Oracle Internet Directory, but the user can still log in.

Problem

The orclIsEnabled attribute is incorrect.

Solution

Execute ldapbind from the command line as the user. If this act invokes an "account disabled error," reenter the attribute value.

A.5.2 A Disabled User Sees "Authentication Failed" Instead of "Account Disabled" Message

Problem

The administrator disabled a user using the orclIsEnabled attribute in Oracle Internet Directory, but the user receives an "authentication failed error" instead of an "account disabled" error.

Solution

None. This is the expected behavior. If the user's account is disabled, she receives an "authentication failed error."

A.5.3 The User Receives a Password Expiration Message at Login

Problem

The user's password has expired.

Solution

The administrator has to reset the password. The administrator can enable password expiration warnings in the directory. These warnings prompt users to change their passwords before they expire.

A.5.4 Password Expiration Message Does Not Appear on Command-Line Tools

Problem

The user logs in to the single sign-on server and is told that her password is about to expire and is prompted to change it. When, however, she does a command-line bind, the message does not appear, and the bind succeeds.

Solution

None. Certain extended directory messages are not visible through the command-line tools. These messages are visible only through the LDAP client-side APIs.

A.6.1 Viewing the 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.6.2 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.6.3 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.6.4 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.7.1 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.2 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.7.3 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