ShowTable of Contents
Introduction
Single sign-on (SSO) is a mechanism whereby a single action of user authentication and authorization can permit you to access all computers and systems to which you have access permission, without needing to enter multiple passwords. SSO has the following benefits:
- The ability to enforce uniform enterprise authentication and authorization policies across the enterprise
- IT administrators can save both time and resources by making use of a central Web management service
- Simple to use, SSO no longer requires users to remember numerous passwords for accessing various systems
SSO does have one big drawback, however, and ironically it is the same as its biggest strength: centralized access to password management. To prevent hackers from gaining password control, virtually all SSO solutions also support additional network security mechanisms, such as high encryption levels and use of a smart card, a biometric, or other technologies, as supplemental ways of proving identity.
SSO solutions supported by Lotus Connections
Lotus Connections mainly supports four types of SSO solutions:
- Enable SSO with IBM WebSphere® Application Server (WAS)
- Enable SSO with IBM Tivoli® Access Manager (TAM)
- Enable SSO with SiteMinder
- Enable SSO with Kerberos on Microsoft® Windows® (Windows single sign-on)
For more details on how to configure SSO for Connections 2.5, refer to the InfoCenter topic,
Configuring single sign-on.
For Connections 3.0, refer to the
Configuring single sign-on topic in the wiki Product Documentation.
The SSO validation utility
Configuring SSO for Lotus Connections is time consuming, and it's easy to make mistakes because there are many manual configuration steps.
The main idea of the SSO validation utility is that it sends many requests to Connections with SSO configured, and then checks the returned status code, response headers, and cookies to determine whether the requested resource is protected by form-based authentication, basic authentication, or is unprotected.
Once you install the Connections product and complete the configuration steps per the Product Documentation, you can run the SSO validation utility to verify your configurations quickly.
Functions
The SSO validation utility is designed to provide verification for:
- Standalone Lotus Connections, in which there are only WAS and the IHS server involved in the deployment topology
- Lotus Connections integrated with TAM
- Lotus Connections integrated with SiteMinder
- LotusConnections-config.xml file for all three cases above
The following sections introduce how to use the SSO validation tool to verify your SSO configurations.
Running the SSO validation utility
Follow these steps to run the utility:
1. Extract the installation package to a directory called <WizardHome>.
2. Set up the path to the Java
TM executable if IBM Java 5.0 is not on your path. Modify <WizardHome>\SsoValidation.bat, changing
java -classpath %CLASSPATH% com.ibm.lconn.sso.verificationutility.ui.launcher.WizardLauncher -hostConfig config/host_config.properties
C:\Program Files\IBM\Java50\bin\java -classpath %CLASSPATH% com.ibm.lconn.sso.verificationutility.ui.launcher.WizardLauncher -hostConfig config/host_config.properties
It is recommended to use IBM JRE5/6. If you’re using the SUN JRE, you need to download the xalan.jar file and put that JAR onto your classpath.
You can download the xalan library from
http://www.apache.org/dyn/closer.cgi/xml/xalan-j.
3. Map all host names to IP addresses. Since the wizard must follow redirect addresses from the Lotus Connections server (which usually consists of the host name of that Lotus Connections server), you should use host names instead of IP addresses throughout the wizard. For this to work, you need to map all the host names and IP addresses in your local hosts file:
Windows: C:\WINDOWS\system32\drivers\etc\hosts
Linux: /etc/hosts
4. Specify the input parameters for the wizard in a configuration file. This step is optional but is quite useful. You can choose to start the wizard with pre-configured input values so that you don’t need to type these values repeatedly during your tests, which could be quite useful if you’re testing in the same environment multiple times.
Specifying the input parameters for the wizard
To do this:
1. Modify the input configuration file, <WizardHome>/config/host_config.properties. For example, when validating a standalone Lotus Connections environment, set these three values:
ssoType=lc
validateLcc=no
ihs.host=
NOTE:
- There are three values for ssoType: lc, tam, and sm, where lc specifies a standalone Lotus Connections deployment, tam specifies enable TAM SSO, and sm specifies enable Siteminder SSO.
- There are two values for validateLcc: yes, no, where yes means to validate LotusConnections-config.xml file, and no means not to validate it.
2. Specify which configuration file will be used when starting the wizard. Modify <WizardHome>\SsoValidation.bat, line 25 as follows:
java -classpath %CLASSPATH% com.ibm.lconn.sso.verificationutility.ui.launcher.WizardLauncher -hostConfig config/host_config.properties
3. Specify which feature(s) you want to validate. For standalone Connections validation, modify the file
<WizardHome>\config\LC30_config\pure_lc\lc_url_config.properties:
- features = activities,blogs
NOTE: The features parameter controls which features will be validated. Lotus Connections has 11 features, but if you only want to validate a few of them using validation tool, such as only for activities and blogs, you can set value as above.
For example, if you want to validate URLs for Activities and Blogs, possible values would include: activities,blogs,communities,dogear,profiles,homepage,files, wikis, new search.
Illustrated steps
In this section, we lead you through the wizard steps---and include accompanying figures-–for verifying SSO configurations for standalone Lotus Connections.
1. Start the wizard by double-clicking <WizardHome>\SsoValidation.bat. The Welcome window displays (see figure 1); click Next.
Figure 1. Welcome window
2. Select the SSO environment and choose whether to validate LotusConnections-config.xml (see figure 2):
- Select the SSO environment (Standalone Lotus Connections, TAM SSO, or SiteMinder SSO)
- Choose whether to validate LotusConnections-config.xml or not (useful when validating TAM and SiteMinder SSO)
For standalone URL authentication validation, select the “Standalone Lotus Connections with WAS/IHS” option and check the “Validate LotusConnections-config.xml (Requires WAS host information and WAS information)” checkbox.
Figure 2. Select the SSO environment
3. Specify the IHS host, as shown in figure 3.
Figure 3. Specify the IHS host
4. [Optional] Specify WAS host information and WAS information (if you have selected to validate LotusConnections-config.xml previously), as shown in figure 4.
Figure 4. Specify WAS host information
5. The next window provides an overview of the SSO configuration information (see figure 5).
Figure 5. SSO Settings Review window
6. [Optional] The next window (see figure 6) shows the LotusConnections-config.xml validation result (if you have selected to validate LotusConnections-config.xml previously).
Figure 6. LotusConnections-config.xml Validation Result window
7. Click on the cells in the Validation Result column; the wizard shows the expected values and actual values in the top message area. For example, in figure 7, when you click the “OK” cell on the row, “Is dynamicHosts enabled?”, you’ll see the following in the top message area:
EXPECTED: FALSE; ACTUAL: FALSE
indicating that the expected setting for dynamicHosts.enabled is False, and the actual value resolved by the wizard is also False, so the configuration is correct for “dynamicHosts.enabled”.
Figure 7. Expected and actual values
8. The next window shows the Validation waiting (see figure 8)
Figure 8. Verifying Single Sign-on Settings window
9. The result window shows you the final verification result for each selected Lotus Connections feature (see figure 9).
Figure 9. SSO Verification Result window
10. You can also click on the cells under the “GET/PUT/POST/DELETE” columns, and the wizard will show the expected and actual results in the top message area (see figure 10).
Figure 10. Expected and actual results message
In this example, for the URL “/forums/atom”, when submitting a GET request to it, we expected it to be “Basic Authentication protected URL”, but the actual result resolved by the wizard is “Unprotected URL”. Apparently there are some issues here, and we need to look into the utility’s log file to investigate further.
Troubleshooting
Now let's discuss how to troubleshoot issues found by the SSO validation utility.
Checking the log
If you get a validation error in the panel, you can find detailed validation information in the log files that can help you better diagnose the problem. The SSO validation utility logs all the information in the file named SsoValidation.log, which is located in the
directory. Figure 11 shows a sample SsoValidation.log.
Figure 11. SsoValidation.log example
Let's look at the four parts outlined in red in the above example, in which we are validating the URL, /forums/atom, via PUT:
Part 1: The wizard submits PUT to http://<IHS>/forums/atom and it gets the response: 302, together with the “x-lconn-auth” header.
Part 2: Since the status code is 302, the redirect address might be the log-in form of that feature (which should be followed with GET methods), so we first follow that redirect address with a second GET method, and test to see whether that's a log-in form. With the second GET method, the wizard detects that the redirect address is not a log-in form URL: 404 + x-lconn-auth.
Part 3: Since the redirect URL is not a log-in form, we then follow the original log-in form with a further PUT method, which returns: 401 + x-lconn-auth. So we conclude that the original URL is “basic-auth” protected.
Part 4: A short summary about the validation of that URL with the specific HttpRequest.
Finding issues in configurations
When you find an issue through the GUI or trace log, you first must identify the true problem, and then modify the configuration accordingly. Here are some tips for the different SSO configurations:
TAM SSO
In TAM SSO, you can use the “pdadmin” tool to check the resource and see if it is attached to the expected ACL. For instance:
1. Run the command
object list /WebSEAL/<tamHost>-<instance>
to list Connections junction points:
/WebSEAL/tamsso-default/activities
/WebSEAL/tamsso-default/forums
2. Run the command
object show /WebSEAL/<tamHost>-<instance>/forums/atom
to show properties for the /forum/atom resource:
Name: /WebSEAL/tamsso-default/forums/atom
Description: Object from host tamsso
Type: 16 (Management Object)
Is Policy Attachable: Yes
Extended Attributes:
Attached ACL:
Attached POP:
Attached AuthzRule:
Effective Extended Attributes:
Effective ACL: default-lc-default
Effective POP:
Effective AuthzRule:
3. From this result, we can see that the effective ACL is default-lc-default, and the resource under this ACL should be protected by Form, but actually the /forums/atom should be Basic protected, so we need attach to another ACL : default-lc-exception.
4. Run the command, acl list, to list all ACLs:
default-lc-exception
default-lc-default
5. Run the command, acl attach <object name> <acl name>, to attach a new ACL to the specified resource:
Acl attach /WebSEAL/tamsso-default/forums/atom default-lc-exception
SiteMinder SSO
In a SiteMinder environment, you can log in to the administration console of the SiteMinder policy server, to check the configuration for a specified resource.
By default, all resources are covered under root realm “/”. Root realm is protected by form-based authentication, so if the specified resource is protected by basic authentication or is unprotected, there must be a separate realm to configure it.
Figure 12 shows an example for the /blogs/atom resource, in which we can see that this resource is protected by Basic, as we expected. If you find a different result, you need modify the authentication scheme.
Figure 12. SiteMinder admin console Realm Properties
We also need to check the attached rules on /blogs/atom realm. From figure 13 we can see there are two rules attached to this realm:
getpostputdel rule (meaning we can do get,post,put,delete action on /blogs/atom* resource)
onauth rule
and the actions of the getpostputdel rule are GET, POST, PUT, DELETE, which is the correct configuration. If you find a different result, you need to modify the rule action.
Figure 13. SiteMinder admin console List of Rules and Realms
Conclusion
In this article, we have introduced the functions of the SSO diagnostic tool and how to use it. The tool is designed to quickly verify Connections SSO configurations, but it can't fix SSO configuration issues. When users identify a configuration issue using this tool, they can modify the configuration manually, and then re-verify.
Resources
About the authors
Zheng Jun Song is a Software Engineer based at IBM's facility in Shanghai, China. ZhengJun joined IBM in 2008. Currently he works with the Level 3 Support team for Lotus Connections, using his experience in Web application development. You can reach him at songzj@cn.ibm.com.
Xiao Feng Yu is an Advisory Software Engineer based at IBM's facility in Shanghai, China. Xiaofeng joined IBM in 2005. He has extensive experience in Web application development, working on IBM Web 2.0 products such as Lotus Connections and Lotus Mashups, and currently works on Web 2.0 security. You can reach him at yuxiaof@cn.ibm.com.