|
Oracle® Application Server Single Sign-On Administrator's Guide
10g (9.0.4) Part No. B13791-01 |
|
|
|
|
Oracle® Application Server Single Sign-On Administrator's Guide
10g (9.0.4) Part No. B13791-01 |
|
|
|
|
This appendix contains the following topics:
These OracleAS log files record data about single sign-on operations.
Single sign-on log:
$ORACLE_HOME/sso/log/ssoServer.log
Usage Notes:
This is the file that you use the most. The single sign-on server writes all errors to this file.
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/OC$J_SECURITY_default_island_1/application.log
Usage Notes:
This OC4J-generated file reports run-time application errors.
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_logg
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.
This section explains how to address error messages and other problems. It devotes sections to the following:
Verify that the single sign server was started correctly. To do this, examine the startup log file for errors.
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.
Next, check ssoServer.log, the log file for the single sign-on server.
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.
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)
To learn how to run ssooconf.sql, see "Changing Single Sign-On Server Settings for Directory Access" in Chapter 3.
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.
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.
Check default-web-access.log to determine whether the authentication request was received by the servlet.
Update the dads.conf file in $ORACLE_HOME/Apache/modplsql/conf.
Restart the Oracle HTTP Server. See "Stopping and Starting the Oracle HTTP Server" in Chapter 2.
If the schema password is correct to begin with, check the Oracle HTTP Server error log for error messages.
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.
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 may 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.
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.
Try binding to the directory as the user, making sure that the user DN corresponds to the appropriate realm:
ldapbind -h directory_server -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.
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.
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 may be directory based.
cn=iASAdmin,cn=Groups,cn=OracleContext,realm_dn
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.
Check the opmn log file for errors.
Check ssoServer.log for errors.
Make sure that the keytab file is in the right place. Check, too, that the principal name configured in jazn-data.xml is correct.
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.
default_realm and domain_realm in /etc/krb5/krb5.conf. Note that the realm name is case sensitive.
kerberos-servicename may not be configured correctly.
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.
Check ssoServer.log for errors.
Make sure that the keytab file is at the correct location. Check, too, that the principal name configured in jazn-data.xml is correct.
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.
This section explains how to debug certificate authentication; then it explains how to interpret error messages.
Set the debug level in policy.properties to DEBUG; then restart the single sign-on middle tier.
To view browser certificate information while debugging, extract the file certinfo.jsp file from $ORACLE_HOME/sso/lib/ipassample.jar.
Place the file into $ORACLE_HOME/j2ee/applications/sso/web/jsp.
View the file at this URL:
https://host:port/sso/.jsp/certinfo.jsp
SSLVerifyClient is missing from httpd.conf or has not been entered correctly.
CertificateMappingModule. If it is assigned, check that this value is correct.
orclIsEnabled attribute in Oracle Internet Directory, but the user can still log in.
orclIsEnabled attribute is incorrect.
orclIsEnabled attribute in Oracle Internet Directory, but the user receives an "authentication failed error" instead of an "account disabled" error.
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.
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 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.
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;
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 must 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:
Load debugonldap.sql into the ORASSO schema:
SQL> connect orasso/password
See Appendix B to obtain the schema password.
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;
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. Direct access through SQL*PLUS is not supported.
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:
Connect to the single sign-on schema. See Appendix B to obtain the schema password.
Issue the following command:
SELECT * FROM WWSSO_LOG$
Restart the HTTP server if you see the following error in the log:
'INVALID LDAP CONNECTION CACHE: RESTART ORACLE HTTP SERVER'
Delete the error message from WWSSO_LOG$.
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.
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.
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.
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
For an in-depth look at the Replication Environment Management Tool, see Oracle Internet Directory Administrator's Guide.
