Appendix C Troubleshooting the Agent Deployment

This appendix explains how you can resolve problems that you may encounter while deploying or using the J2EE Policy Agents.

Be sure to also check the Policy Agents Release Notes at http://docs.sun.com/db/coll/S1_IdServPolicyAgent_21 to see if the problem that you encounter is a known limitation of the agent. If workarounds are available for such problems, they will be provided in the release notes.

Table C-1 Troubleshooting Instructions
	Symptom	Possible Cause	Solution
1.	The agent installation program hangs and does not display the welcome message or any other message.	A previous run of the agent installation program may have failed or was terminated by the user and the lock file generated by it is still present in your system.	Search for the lock file and delete it. The lock file productregistry.access.lock or productregistry.access.tmp can be found in the location where the prodcutregistry file is present. On Solaris, it is under the directory /var/sadm/install. On Windows 2000 systems, it is present under the directory C:\WINNT\system32.
2.	After installing the agent, the Identity Server fails to startup or does not allow any user to login.	The agent has been installed on the application server instance on which Identity Server is installed.	This is not a supported configuration. You can instead install the agent on a different instance of application server on the same machine, if necessary.
3.	The agent installation program cannot proceed due to a previous installation. However, the previous installation was uninstalled before starting the new installation.	The previous uninstallation of the agent failed to remove the necessary entries from the productregistry file and/or left behind the Solaris package due to errors.	You must search and cleanup the productregistry file. See the solution for symptom number 1 for the location of the file. This is a simple XML file that contains information regarding various Sun products and should be carefully edited to remove the references of any of the agent components. The agent components may be identified by the name of the agent that is being installed. If no other Sun product has been installed on your system, you can safely delete this file. If this is observed on a Solaris system, you must also uninstall the Solaris package corresponding to the agent installation. To identify the agent package, you can use a command such as: # pkginfo \|grep Agent
4.	The agent does not require users to login before access is granted to the application.	The application has not been configured to use the agent.	Refer to the section Post-Installation Tasks for steps to enable the agent for a protected application.
		The resources match entries in the Not-enforced List.	Make sure that the resources being accessed do not match the entries in Not-enforced List, and ensure that the list is not empty and inverted.
		The agent filter mode is set to NONE.	Change the agent filter mode to ALL or J2EE_POLICY as necessary.
5.	Agent denies access to all requests.	The agent and Identity Server have been installed on the same machine and the browser may not be setting the HOST header correctly when redirected from Identity Server to the agent.	Enable Port Check functionality. See the section Enabling Port Check Functionality.
5.	Agent denies access to all requests.	The application server is running as a user who does not have write privileges to the audit log directory of the agent.	Refer to the path specified in the AMAgent.properties file for the agent’s local audit file and grant the necessary write permissions for the user of the application server process.
		The agent filter is configured for a mode that enforces URL policies and no applicable URL policies have yet been defined in Identity Server.	Define the appropriate URL policies in Identity Server.
		The agent filter is configured for a mode that enforces URL polices and the system time on the agent machine is not in sync with the system time on the Identity Server machine.	Synchronize the time of the agent machine with the time on the Identity Server machine. See the section Synchronizing the Agent Host and the Sun ONE Identity Server 6.1 Host for details.
		The agent filter is configured for a mode that does not support J2EE Polices and the resources being accessed are protected by declarative security constraints.	Change the agent filter mode to a mode that supports J2EE policy such as ALL or J2EE_POLICY.
		The agent filter is configured for a mode that supports J2EE polices but they are being negatively evaluated by the agent.	Refer to the solution for symptom number 6.
		The agent is unable to validate user’s session token issued by Identity Server.	Make sure that the agent is installed on the same domain that is specified as the cookie domain in Identity Server. If not, enable CDSSO functionality. If that is not the case, try changing the value of the property com.sun.am.policy.amFilter.ssotoken.urldecode
		The agent is configured for CDSSO and the validity time of the authorization response is smaller than the processing time required by the agent.	Set an appropriate value for the property com.sun.am.policy.amFilter.cdsso.clock.skew
		The Login URL specified in the file AMAgent.properties is not reachable by the agent.	Make sure that the Identity Server Login URL is reachable from the machine where the agent is installed.
		The application server uses JDK version below 1.4 and no JCE/JSSE was selected during agent installation for the JDK used by application server.	Reinstall the agent and select the appropriate checkboxes as necessary to install JCE and/or JSSE for the JDK used by the application server.
		The Identity Server is installed with SSL and the agent cannot communicate with it correctly.	Refer to the solution for symptom number 9.
6.	The agent fails to evaluate J2EE declarative security policies or J2EE programmatic security APIs for the protected applications.	The protected application does not have the agent filter installed.	Redeploy the application with the agent filter installed and the login-configuration added as described in the Chapters 2 and 3 of this guide.
		The agent filter is operating in a mode that does not support J2EE policies.	Change the agent filter mode to either ALL or J2EE_POLICY. Change the filter mode to J2EE_POLICY
		The agent realm is not installed for the application server.	Refer to the section Post-Installation Tasks for the agent to ensure that the agent realm is properly configured.
		The agent realm is installed but not correctly configured.	Make sure that the following properties are specified correctly in the AMAgent.properties file: com.sun.am.policy.amRealm.organization.dn com.sun.am.policy.amRealm.peoplecontainer.level com.iplanet.am.directory.host com.iplanet.am.directory.ssl.enabled com.iplanet.am.directory.port Also make sure that the DirDN values for User1(cn=puser) and User2(cn=dsameuser) specified in the serverconfig.xml file present under the directory agent_config_directory/ums have valid values corresponding to the installation organization and root-suffix.
		The agent realm is installed and configured correctly but has been disabled previously.	Enable the agent realm. Refer to the section Disabling the Agent Realm for steps.
		No password was specified for amAdmin user during the agent installation.	Encrypt the original password for amAdmin user as specified during the installation of Identity Server using the agentadmin tool. Enter the encrypted password in the DirPassword elements in serverconfig.xml file found under the directory agent_config_directory/ums. This password must be entered in two distinct places in this file for User1(cn=puser) and User2(cn=dsameuser).
		The password specified for amAdmin user during the agent installation is different from the amAdmin user password specified during the initial installation of Identity Server.	The amAdmin user password required by the agent is the original amAdmin user password that was created when Identity Server was installed. If subsequently the password for amAdmin user was changed, the old password should be used for installing the agent and not the new one. Take the old password and encrypt it using the agentadmin tool. Enter the encrypted password in the DirPassword elements in serverconfig.xml file found under agent_config_directory/ums. This password must be entered in two distinct places in this file for User1(cn=puser) and User2(cn=dsameuser).
		The specified role-to-principal mapping is incorrect.	Make sure that the specified role-to-principal mapping for the protected application is correct and maps to actual users and/or roles as they exist in Identity Server.
		The Identity Server’s Directory Server is not available.	Make sure that the Identity Server’s Directory Server is available and reachable from the machine on which the agent is installed.
7.	Accessing a protected resource results in HTTP 404 not found error.	The agent and Identity Server have been installed on the same machine and the browser being used may not be setting the HOST header correctly when redirected from Identity Server to the agent.	Enable Port Check Functionality. See the section Enabling Port Check Functionality.
7.		The resource is protected by a J2EE declarative security constraint which is not being evaluated correctly and the server is trying to display the form-error-page that does not exist within the application.	Make sure that the resource specified by form-error-page in the web application’s web.xml deployment descriptor actually exists within the application.
		The resource is being accessed by a legacy browser such as Netscape 4.x and during the installation of the agent no valid value was entered for primary application context path field.	Reinstall the agent and specify a valid primary application context path value.
		The agent is operating in the CDSSO mode and no valid value was entered for the primary application context path field during agent installation.	Reinstall the agent and specify a valid primary application context path.
8.	On Solaris 8 platform, the agent for application server that uses JDK 1.4 hangs when Identity Server or Directory Server are configured for SSL.	The agent uses the JSSE shipped with the application server’s JDK (1.4) to communicate with the Identity Server services. This implementation of JSSE requires the use of a secure random device (/dev/random) that is not included in Solaris 8 distribution.	In order to work around this issue you can either comment out the line securerandom.source=file:/dev/random in the $JAVA_HOME/lib/security/java.security file, or install the OS patch 112438-02.
9.	When Identity Server is SSL Enabled, the agent denies access to all resources.	The agent does not have the root CA certificate of the signer of the certificate used by Identity Server.	Install the appropriate root CA certificate in the keystore used by the application server on which the agent is installed.
		In the case of IBM WebSphere 5.0/5.1 agent, the sample URL provider for HTTPS protocol that was installed as part of the samples deployed for WebSphere 5.0/5.1 conflicts with the JSSE implementation used by the agent.	Remove the sample URL provider for HTTPS protocol using the following steps: 1. Logon to the WebSphere Application Server Administration Console. 2. In the left hand panel, click on the Resources node. This will expand the node to revel various resources that can be configured for the Server. 3. Click on the URL Providers resource link. This will load the corresponding properties on the right side content panel. 4. In the right side content panel, make sure that the Scope node is expanded. If not, click on this node to expand it. 5. Select the radio button next to the Server entry under the Scope node and click on the Apply button. 6. In the list of properties displayed in the lower portion of this panel, if you see Samples URL Provider - https entry, then this provider must be removed. Select the check box next to this provider and click on the Delete button. 7. Click on the Save link at the top of the page to save this change to the master configuration. This will bring you to a page that has the Save button. Click on this Save button to commit your changes. 8. Restart the WebSphere Application Server for the changes to take effect.
10.	The agent is unable to fetch the LDAP attributes for the logged on user.	The requested resource that expects to use the attributes is in the not-enforced list of the agent.	Change the not-enforced list so that the requested resource is enforced. The agent does not provide support for LDAP attributes for resources that are not-enforced.
		The agent is not configured to communicate with the Identity Server’s directory server correctly.	Make sure that the following properties are set correctly in the AMAgent.properties file: com.sun.am.policy.amRealm.organization.dn com.sun.am.policy.amRealm.peoplecontainer.level com.iplanet.am.directory.host com.iplanet.am.directory.ssl.enabled com.iplanet.am.directory.port Also make sure that the DirDN values for User1(cn=puser) and User2(cn=dsameuser) specified in the serverconfig.xml file present under the directory agent_config_directory/ums have valid values corresponding to the installation organization and root-suffix.
		No password for amAdmin user was specified during the agent installation.	Encrypt the original password for the amAdmin user as specified during the installation of Identity Server using the agentadmin tool. Enter the encrypted password in the DirPassword elements in serverconfig.xml found under the directory agent_config_directory/ums. This password must be entered in two distinct places in this file for User1(cn=puser) and User2(cn=dsameuser).
		The password specified for amAdmin user during the agent installation is different from the amAdmin user password specified during the initial installation of Identity Server.	The amAdmin user password required by the agent is the original amAdmin user password that was created when Identity Server was installed. If subsequently the password for amAdmin user was changed, the old password should be used for installing the agent and not the new one. Take the old password and encrypt it using the agentadmin tool. Enter the encrypted password in the DirPassword elements in serverconfig.xml file found under the directory agent_config_directory/ums. This password must be entered in two distinct places in this file for User1(cn=puser) and User2(cn=dsameuser).
		The Identity Server’s Directory Server is not available.	Make sure that the Identity Server’s Directory Server is available and reachable from the machine on which the agent is installed.
11.	When some user information is changed in Identity Server, the changes do not reflect in the WebLogic Server protected by the agent, unless it is restarted.	The startup scripts for the agent protected server were modified such that the agent’s classpath appears after the WebLogic Server’s classpath.	Edit the startup scripts of the agent protected server and place the agent’s classpath before the WebLogic server’s classpath.
12.	The Identity Server logs indicate that it is unable to send notifications to the application server protected by the agent.	The agent is installed on a server with preferred listening protocol set to HTTPS and the root CA certificate for the signer of agent’s server certificate is not available in the keystore used by Identity Server.	Add the root CA certificate for the signer of agent’s server certificate to the keystore used by Identity Server.
12.		No valid value was entered for the primary application context path during agent installation.	Reinstall the agent and specify a valid primary application context path.
13.	When accessing a resource protected by the Sun ONE Application Server 7.0 agent, the browser displays a blank page with the URL pointing to j_security_check.	This can happen if the entire web application is protected by declarative security constraints in web.xml deployment descriptor.	Edit the AMAgent.properties file and add a value corresponding to the protected application for the property: com.sun.am.policy.amFilter.login.referer.map The value of this property should be a URI that will be used to send the user once the form-login sequence has completed successfully.
14.	When accessing a servlet/JSP protected by the Sun ONE Application Server 7.0 agent that in turn invokes other servlets/JSPs, the agent is unable to enforce URL policies on subsequent resources.	This is a limitation of the implementation of Servlet Filters in Sun ONE Application Server 7.0	Use J2EE declarative security to protect such resources.
15.	The following warning messages appear on the console window from which the application server is started or in the application server logs: Bad level value for property: com.iplanet.services.debug.level Bad level value for property: com.sun.identity.agents.logging.level Bad level value for property: com.sun.am.policy.amFilter.audit.level	These messages are logged by the JDK 1.4 logging framework in use, which treats the AMAgent.properties file as the logging configuration file.	These messages are harmless and can be safely ignored. If you wish to remove these messages, you should create a new properties file (for example agentlog.properties) and copy the following configuration properties from the file AMAgent.properties into this new file: com.iplanet.am.logstatus=ACTIVE iplanet-am-logging-remote-handler=com.sun.identity.log.handlers.RemoteHandler iplanet-am-logging-remote-formatter=com.sun.identity.log.handlers.RemoteFormatter iplanet-am-logging-remote-buffer- size=1 Once this new file is created, you should set the value of the system property java.util.logging.config.file for the application server to the complete path of this new file. Depending upon the application server for which you have installed the agent, you may have to edit either the startup script of the application server, or the configuration properties/xml file where such system properties can be defined for the application server.