Skip Headers

Oracle® Application Server Single Sign-On Administrator's Guide
10g (9.0.4)
Part Number B10851-01
Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index

Go to previous page Go to next page

A
Troubleshooting

This appendix contains the following topics:

Log Files

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

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

Internal Server Error. Please contact administrator.

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

Action: Use the following sequence to solve the problem:

  1. Verify that the single sign server was started correctly. To do this, examine the startup log file for errors.

  2. If the 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 server has been started correctly.

  3. Next, check ssoServer.log, the log file for the single sign-on server.

  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 single sign-on server.

  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.

    • 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.

Internal Server Error. Please try the operation later.

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

Action: Check ssoServer.log for a detailed description of the message; then try restarting the database or the directory.

Unexpected Error. Please Contact Administrator.

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

Action: In the first case, check ssoServer.log for the actual error message. If this file does not contain the message, check the Oracle HTTP Server error log. In the second case, try to log in to the administration pages:

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

Be sure to log in as orcladmin, not as cn=orcladmin. If you are able to log in, the problem is not with the server, but with the partner application registration or with the application itself. To verify that the application has been registered correctly, write a Perl script that prints registration parameters: 

printenv cgi script (REMOTE_USER, HTTP_OSSO_USER_DN, HTTP_OSSO_USER_GUID, 
HTTP_OSSO_SUBSCRIBER, HTTP_OSSO_SUBSCRIBER_DN, HTTP_OSSO_SUBSCRIBER_GUID)

Protect the script with mod_osso. To learn how, see "Protecting Applications with mod_osso: Two Methods" in Oracle Application Server Single Sign-On Application Developer's Guide. If the parameters are correct, the application is registered correctly. The problem lies in the application.

After identifying and correcting the problem, restart the single sign-on server. See "Stopping and Starting the Single Sign-On Middle Tier" in Chapter 2.

File not found.

Cause: This message may appear when you try to access the single sign-on server.

Action: Perform two checks:

  1. Check the Oracle HTTP Server error log.

    If you find the message file not found, Apache is not delegating the authentication request to OC4J.

    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.

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

Cause: 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.

Action: Perform these steps:

  1. Update the dads.conf file in $ORACLE_HOME/Apache/modplsql/conf.

  2. Restart the Oracle HTTP Server. See "Stopping and Starting the Oracle HTTP Server" in Chapter 2.

  3. If the schema password is correct to begin with, check the Oracle HTTP Server error log for error messages.

Audit log insertion exception: ORA-00018: maximum number of sessions exceeded.

Cause: This message appears when the load on the single sign-on server is heavy. The number of database sessions required has exceeded the number specified in the init.ora file.

Action: 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 in $ORACLE_HOME/dbs.

Connection limit exceeded.

Cause: This is a variation of the message immediately preceding.

Action: Retry the operation.

Single Sign-On Administration UI is not working. The administrator sees a white page when clicking Login

Cause: This problem has three possible explanations:

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

  • Case 2: The single sign-on server is configured with the wrong information for the directory.

  • Case 3: There might be installation problems, namely, a missing Enabler entry or faulty SSL reregistration.

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

Action:

  • Case 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.

  • Case 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.

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

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

Authentication Failed.

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

Action:

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

    ldapbind -h directory_server -p directory_port -D user_dn -w user_
password

    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: 

    ldapbind -h directory_server -p directory_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: 

    ldapcompare -h directory_host -p directory_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 might be directory based.

Administrator does not see administration pages when logging in to /pls/orasso.

Cause: The administrator is not a member of the iASAdmins group:

cn=iASAdmin,cn=Groups,cn=OracleContext,realm_DN

Action: 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.

Windows Native Authentication

Internal Server error. Please contact your administrator.

Cause: Windows native authentication is misconfigured on the middle tier computer.

Action: Do the following:

  1. Check the opmn log file for errors.

  2. Check ssoServer.log for errors.

  3. Make sure that the keytab file is in the right place. Check, too, that the principal name configured in jazn-data.xml is correct.

  4. Make sure that the single sign-on middle tier computer is properly configured to access the Key Distribution Center. See "Set Up a Kerberos Service Account for the Single Sign-On Server" in Chapter 8.

The windows login dialog box (with username, password, and domain fields in it) comes up when accessing the partner application.

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

Action: Add the user entry to the directory.

Could not authenticate to KDC.

Cause: This error message might be invoked if the realm name in krb5.conf is incorrectly configured.

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

Single sign-on server fails to start. Log file contains an exception bearing the message "Credential not found."

Cause: The parameter kerberos-servicename may not be configured correctly.

Action:

  1. Make sure that kerberos-servicename is configured correctly in the files orion-application.xml and jazn-data.xml. In the first file, the format for this parameter is HTTP@sso.ACME.COM. In the second file, the format is HTTP/sso.ACME.COM.

  2. Check ssoServer.log for errors.

  3. Make sure that the keytab file is at the correct location. Check, too, that the principal name configured in jazn-data.xml is correct.

  4. Make sure that the single sign-on middle tier computer is configured to access the Kerberos domain controller. See "Set Up a Kerberos Service Account for the Single Sign-On Server" in Chapter 8.

Your browser does not support the Windows Kerberos authentication or is not configured properly

Cause: The user browser is not supported or is misconfigured.

Action: Follow the instructions in "Configure the End User Browser" in Chapter 8.

"Access forbidden" or "HTTP error code 403" or "Windows Native Authentication Failed. Please contact your administrator."

Cause: These error messages have the same cause: the user entry cannot be found in Oracle Internet Directory. A local administrator working at a Windows desktop may be trying to access a single sign-on partner application whose entry may not have been synchronized with Oracle Internet Directory.

Action: Determine whether the user entry exists in the directory. Determine whether Kerberos principal attributes for the user are properly synchronized from Microsoft Active Directory.

Certificate Authentication

This section explains how to debug certificate authentication; then it explains how to interpret error messages.

Debugging certificate sign-on

  1. Set the debug level in policy.properties to DEBUG; then restart the single sign-on middle tier.

  2. To view browser certificate information while debugging, extract the file certinfo.jsp file from $ORACLE_HOME/sso/lib/ipassample.jar.

  3. Place the file into $ORACLE_HOME/j2ee/applications/sso/web/jsp.

  4. View the file at this URL: 

    https://host:port/sso/.jsp/certinfo.jsp

Error Messages

Network Error: Connection Refused.

Cause: 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.

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

The single sign-on server fails to prompt the user for a certificate.

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

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

Certificate authentication fails to work, and the user is presented with the login page.

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

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

User's browser certificate not found.

Cause: The user's certificate is not in the browser.

Action: Install a valid certificate.

Mapping Module class name not found.

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

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

Mapping module instance creation failed.

Cause: The customized mapping module has been incorrectly implemented.

Action: Ensure that the custom module has a default constructor.

Cannot create the mapping module object.

Cause: The customized mapping module has been incorrectly implemented.

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

Exception in creating mapping module.

Cause: The customized mapping module has been incorrectly implemented.

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

Certificate match failed.

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

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

Password Policies

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

Cause: The orclIsEnabled attribute is incorrect.

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

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.

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

Action: None.

The user's password has expired. He cannot log in and wants to reset the password.

Action: The administrator has to reset the password. She can enable password expiry warnings in the directory. These warnings prompt the user to change his password before it expires.

The user logs in to single sign-on 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.

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

When the administrator enables the force change password feature in Oracle Internet Directory (by setting the pwdMustChange attribute in the password policy entry), the user is prompted to change her password. After changing the password, she is taken to the login page. But when she logs in again with her new password, she is shown the change password page again.

Cause: OracleAS Single Sign-on does not support the force change password feature.

Action: Do not enable this feature in Oracle Internet Directory.

Increasing the Debug Level

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

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

After changing the debug level, restart the OC4J_SECURITY instance. For instructions, see "Stopping and Starting the OC4J_SECURITY Instance" in Chapter 2.

Enabling the Debug Option on 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 ssoServer.log, located in $ORACLE_HOME/sso/log.

To turn on mod_plsql debugging, log in to the ORASSO schema and execute the ssolsdbg.sql script. See Appendix B to obtain the schema password. Be sure to uncomment the commented lines in the script before executing 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;

-- NOTE: make sure to place slash after each definition to avoid
-- strange looking compiler errors, such as
-- PLS-00103: Encountered the symbol "CREATE"

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

   /* should probably have session ID and username too being logged */

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

   commit;

    null;

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;

-- NOTE: make sure to place slash after each definition to avoid
-- strange looking compiler errors, such as
-- PLS-00103: Encountered the symbol "CREATE"

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

    null;

END debug_print;
/

show errors;

Enabling LDAP Tracing for UI Operations

The administration home page for single sign-on uses 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 can enable client-side LDAP tracing. In trying, for example, to determine why a purported administrator cannot log in as an administrator, 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 directories.

Follow these steps to enable tracing:

  1. Load debugonldap.sql 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;

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. See "Stopping and Starting the Oracle HTTP Server" in Chapter 2.

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$.

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. For instructions, see "Stopping and Starting the Single Sign-On Middle Tier" in Chapter 2.

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 executed 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.

Verifying Oracle9i Advanced Replication Configuration

To verify that the directory replication group has been successfully configured, issue the following command: 

remtool -asrverify

The command option -asverify instructs the tool to report on the verification as it progresses, but not to rectify problems.

Verifying and Rectifying Oracle9i Advanced Replication Configuration

To verify that a directory replication group has been successfully configured and to rectify problems, execute the following command: 

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

The command option -asrectify instructs the tool to report on the verification as it progresses and to rectify problems. Table A-1 defines the two other command parameters.

Table A-1 Parameters for the Replication Environment Management Tool
Parameter Description

-v

Verbose mode. Specifying this option not only shows the progress of remtool, but also logs all actions of the tool in remtool.log. This file is found in $ORACLE/ HOME/ldap/log.

-connect

Connect string of the RMS database. As the command syntax shows, this string has three components:

  • repadmin--Name of the replication administrator

  • repadmin_password--Password of the replication administrator

  • net_service_name--Network service name of the RMS database.

For an in-depth look at the Replication Environment Management Tool, see Oracle Internet Directory Administrator's Guide.

Go to previous page Go to next page
Oracle
Copyright © 1996, 2003 Oracle Corporation.
All Rights Reserved.
Go To Documentation Library
Home		 Go To Product List
Solution Area		 Go To Table Of Contents
Contents		 Go To Index
Index