Troubleshooting: Debugging an SSO installation
Remedy does not come with a simple mechanism to facilitate the installation of single sign-on (SSO) plugins. Installation problems can often be tricky to resolve. If you are experiencing installation problems then please work through the following instructions to help diagnose the problem.
JSS AREA plugin
To start testing the installation, the JSS AREA plugin should be tested separtely without using the Midtier. This can be achieved by using the Windows User Tool as a test harness.
Check AD login against the Windows User Tool
If you can login to the WUT using your Windows/Active Directory username and password then your AREA plugin is correctly configured to talk to the Active Directory/LDAP. However this does not test all aspects of the plugin.
If you can not login to the WUT then check the configuration in the jss-sso.cfg file. To gain more infromation on what is wrong, set the Plugin-Log-Level to 100 in the ar.conf, restart the AR Server and look at your plugin log file. You will see all the configuration information loaded from the jss-sso.cfg file printed as the plugin starts, and for each login attempt you will see detail of the authentication.
Check Midtier IP addresses
Have you definitely got the Midtier IP addresses stored in the jss-sso.cfg file? You should be able to see them in the plugin log as the AR Server starts the plugin.
JSS Shared Key
Are you certain you set the JSS Shared Key in the jss-sso.cfg file? This is the shared secret known to the JSS SSO Midtier plugin and the JSS AREA plugin. It may have been typed into the JSS Midtier setup but not in the jss-sso.cfg file. This is done using the newAuthPassword configuration directive; after you've entered it in plain text, the plugin will encrypt it and remove the plain text version when it next restarts.
Testing the Shared Key
You can use the Windows User Tool to ensure the JSS AREA plugin has the correct shared key set (the one set by yourself in the jss-sso.cfg file). However, to do this you must add the IP address of the machine running the WUT to the Midtier IPs in the jss-sso.cfg file.
If you run the WUT on the same machine as the Midtier then the correct IP address should already be present in the jss-sso.cfg file. If you modified the jss-sso.cfg file then you must restart the AR Server.
To run this test, open the WUT and enter your Windows username, leave the password blank and enter the JSS shared key in authentication password box. You should now be able to login. If you cannot, check the shared key setting in the jss-sso.cfg file (refer to “JSS Shared Key” test above).
JSS SSO Midtier plugin
Once the AREA tests are completed successfully, proceed to check the Midtier plugin setup.
The Midtier requires a relatively modest amount of reconfiguration, but some of the error messages one can encounter may be misleading, masking the real problem. In general, error messages that appear in the browser are unlikely to be helpful; instead, the Servlet container (Tomcat etc.) log files should be examined for information to aid debugging.
Checking the JSS-SSO.jar has been installed
Did you install the JSS-SSO.jar file in the Midtier WEB-INF/lib directory?
Checking the Midtier has been reconfigured correctly
During the installation process you will have pointed your browser at http://your-host/arsys/jss-sso/index.jsp and configured the JSS SSO Midtier plugin. Go back to this form and reconfigure the plugin.
If an error occurs that mentions ClassNotFound, check to make sure the JSS-SSO.jar file has been placed in the Midtier WEB-INF/lib directory.
If the error mentions an IOException then check to make sure the system account used by the webserver can write to the WEB-INF/classes directory (it will need to for Midtier's configuration to operate correctly).
Assuming you have reconfigured the plugin, check to make sure the jss-sso.config file is present in the WEB-INF/classes directory. Also, open up the WEB-INF/classes/config.properties and ensure the plugin has been enabled by searching for the following line:
arsystem.authenticator=com.javasystemsolutions.mt.sso.JSSAuthenticator
If you do not see this then the JSS SSO Midtier installation has failed. It is very unlikely this should happen—please contact support immediately if you are seeing this behaviour.
Also check to ensure there is no mention of arsystem.authenticator.config
in the config.properties file as this causes the Midtier to fail for various version 7.0 releases.
Checking your NTLM web.xml patch
If you've patched the web.xml file to provide NTLM authentication then ensure the file still contains valid XML by opening it up in Internet Explorer or some other XML viewer. Does Internet Explorer display the file or tell you there is an error? If there's an error then correct the syntax and save.
Check NTLM authentication is correctly configured
NTLM authentication configuration failures usually involve the user being presented with an NT domain login box that will not go away even when the correct username and password is entered. If you have enabled NTLM authentication by patching the web.xml file and configuring it through the setup, then you can temporarily disable this (remove the patch) and restart the Midtier.
You should now find the Midtier sends you to a normal login page. If this is the case then check the NTLM settings in the JSS SSO Midtier setup page.
Checking the Midtier functions without the JSS SSO Midtier plugin enabled
Go to the JSS configuration page (http://your-host/arsys/jss-sso/index.jsp) and click ‘disable the plugin’.
Restart the Midtier and go to http://your-host/arsys/home . If you are sent to the normal Midtier home page and can login then the problem is definitely due to the JSS SSO Midtier plugin configuration, however if the Midtier still fails to work with the JSS authenticator disabled then there is a separate problem. At this point it's best to contact JSS.
What to do if the problem still remains
If you can not resolve the problem then contact JSS support and include the following information:
- the steps you've performed from this document and the outcome of each;
- a copy of the AR Server plugin log file (with the Plugin-Log-Level set to 100) showing a user logging into the WUT and a user attempting to log in to the Midtier;
- the ar.cfg and jss-sso.cfg files from the AR Server, and the jss-sso.config file from the Midtier;
- your Midtier web.xml (in WEB-INF) and jss-sso.config (in WEB-INF/classes) files;
- webserver log files—ServletExec.log on ServletExec or the contents of the Tomcat logs directory;
- details of the AR Server and Midtier version and patch numbers.