ShowTable of Contents
This article describes the best practices for setting up single sign-on (SSO) between IBM® Lotus® Connections 2.5 and Computer Associates' SiteMinder. We include detailed steps along with troubleshooting tips.
Introduction
Prerequisites
Before attempting to integrate Lotus Connections 2.5 with Computer Associates' (CA) SiteMinder it is important to verify that Lotus Connections is already installed, working, and is accessible over a Web server.
In the scenario shown in figure 1, a Lotus Connections network deployment is protected by CA SiteMinder. The Web Agent (WA) is installed on the HTTP Server machine, and the SiteMinder Application Server Agent (ASA) is installed on the nodes and deployment manager.
Figure 1. Lotus Connections network deployment
The versions of SiteMinder described in this document are:
• SiteMinder Policy Server 6.0 SP5
• SiteMinder ASA 6.0 Agent for IBM WebSphere® Application Server (with CR0006 hotfix)
• SiteMinder Web Agent v6qmr5-cr011
It is assumed that the SiteMinder configuration objects, WA, and ASA are all installed and configured at this point. Instructions on how to do this are included with SiteMinder, including instructions on how to register the ASA with WebSphere Application Server.
Although the developerWorks Lotus white paper, “Integrating CA (formerly Netegrity) SiteMinder 6.0 with IBM Lotus Connections 2.0“, is a guide to installling and configuring SiteMinder to work with Lotus Connections version 2.0, it contains screenshots and installation instructions for creating configuration objects, domains, and WA and ASA, that are independent of the version of Lotus Connections.
Sections 1, 2, and 3 of the white paper relate to SiteMinder directly and should be read before beginning the steps in this article. Sections 4.1 and 5.1 relate to the WA and ASA installations on the Web Server and Application Server machines, respectively, and should be referenced to complete the prerequisites of the scenario in this article.
This article includes the updated realm lists that are required for Lotus Connections 2.5, along with new configuration steps and a troubleshooting section.
You can refer to the Lotus Connections 2.5 Information Center topic, “Enabling single sign-on for SiteMinder,” for further information.
About this process
To achieve SSO between these products, you must create a new domain with realms, rules, and a policy that is related to IBM HTTP Server and WebSphere Application Server.
When a user logs in, the SiteMinder Web Agent creates an “smsession” cookie with the user's authentication details and sends it to the WebSphere Application Server agent. This agent then checks the log-in credentials in the cookie against the LDAP directory. The Lotus Connections features can share the authentication details and thus enable SSO; in other words, the user can browse all the features without needing to log in again.
Configuring Lotus Connections 25 with SiteMinder
Follow the steps below to complete this security configuration.As it is assumed that the SiteMinder server itself is already installed, this guide focuses the steps that are required on the application server side of the configuration. In brief, the steps are:
• Adding unrestricted policy files to application server
• Installing application server agent and web agents
• Adding configuration parameters to the Web agent
• Creating SiteMinder realms for both the Web agent and application server domains
• Configuring the application server agent
• Adding rewrite rules to the HTTP server
• Editing Lotus Connections configuration files to support SiteMinder
Adding unrestricted policy files
The unrestricted policy files are required to register WebSphere Application Server with the SiteMinder server. In WebSphere Application Server version 6.1.0.23, the registration may fail without these files.
1. Download the unrestricted JavaTM Cryptography Extension (JCE) policy files from here:
https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk
You will need to authenticate with your univeral IBM user ID and password.
2. Download the Unrestricted JCE Policy files for SDK for all newer versions package.
3. Once downloaded, extract the files to a temporary folder.
4. It is advisable to make backups of the existing copies (if they exist) of the US_export_policy.jar and local_policy.jar files. These files are located here on the application server machines:
/java/jre/lib/security
5. Once backed up, copy the corresponding JAR files from the extracted directory to the security directory, overwriting any existing files.
6. Restart all Lotus Connections servers, node agents, and deployment managers.
Installing the SiteMinder ASA and WA
The next step is to install the actual application server agent (ASA) and Web agent (WA). Follow the instructions in Sections 4.1 and 5.1 in “Integrating CA (formerly Netegrity) SiteMinder 6.0 with IBM Lotus Connections 2.0", which provides a guide to installing these agents, including screenshots (again, these sections are independent of the Connections version, so they apply here).
Adding configuration parameters to the WA
Next we need to add parameters to the SiteMinder agent configuration object file. There are two options to do this, either by:
• editing the Agent Configuration Object on the SiteMinder Policy Server, or
• editing the LocalConfig.conf file on the HTTP server, if the WA is configured to use this file. If so, note that the LocalConfig.conf will supersede the policy server object.
You must surround the values of SiteMinder configuration parameters with quotation marks (") if you are editing the SiteMinder configuration file directly. for example, BadCSSChars="<,>". If you are changing these parameters from the SiteMinder Policy Server, do not use quotation marks.
SiteMinder should recognize only one Web address as the log-out Web address. Therefore the following parameter should be added to the SiteMinder agent configuration object parameters:
LogOffUri="/homepage/web/ibm_security_logout"
When activated, the LogOffUri parameter clears the SMSESSION cookie and ensures that the user is logged out of all Lotus Connections browser sessions. If you are using forms authentication, you must create a Forms Credential Collector (FCC) file on the form authentication server. This file contains the authentication settings for logging a user into SiteMinder.
In the same configuration file in which the above modifications were made, you should enable the Homepage widgets by adding the following Agent Configuration Object parameter:
CookieDomain=.example.com
The above example presumes that the Web server is accessed via connections.example.com; therefore, the domain is .example.com. Note that the leading period (.) is required.
To enable the Invite Colleagues functionality in Profiles, modify the BadCSSChars parameter as follows:
To support preemptive basic authentication, add the following Agent Configuration Object parameter to the SiteMinder configuration:
Creating SiteMinder Realms on Web agent domain
There are a number of realms that must be created on the SiteMinder policy server under the IBM HTTP Server Web agent domain. Some of these realms require forms-based authentication, others require basic authentication, while some others remain unprotected. The realms are listed in the tables in Appendix A.
There are two options for adding these realms and rules to the SiteMinder server. Either you can do this manually, following the steps in Section 3 in “Integrating CA (formerly Netegrity) SiteMinder 6.0 with IBM Lotus Connections 2.0, and ma king sure to refer to the tables in Appendix 1 for the updated list of realms and rules for Lotus Connections 2.5.
Alternativle, to simplify the process of adding these realms and rules to the SiteMinder server, you can use the perl scripts listed in table 1 (and accompanying this article in the Attachments section). Copy these files into the /CLI/bin directory and from there run the two perl scripts, to create the 102 realms and the 142 rules correctly.
Table 1. perl scripts
Script | What it does |
create25forms.pl | This script creates the forms-based authentication realms. This script requires a text file containing a comma-separated list of realms and realm names (create25forms.txt). It can be run using the following command:
perl create25forms.pl |
create25others.pl | This script will create the basic authetication and unprotected realms.This script requires 2 text files – one containing a list of basic authentication realms and the other containing the list of unprotected realms. Its usage is as follows:
perl create25forms.pl |
Input files |
|
conn25forms.txt
conn25realms.txt
conn25realmsunprotected.txt | These files are lists of the realms from appendix 1, with each realm given a name. There are three text files here – one for each type of realm – forms, basic and unprotected. |
Note that the above scripts assume the default realms configuration as outlined in Appendix A, without any Microsoft Windows SharePoint Services integration. You will need to modify the .txt files above accordingly for other setup types.
Creating SiteMinder Realms on WebSphere Application Server Agent Domain
On the SiteMinder Policy Server create a domain for the WebSphere Application Server agent and add the following realm to this domain:
Set the timeout value of the session by clicking the Session tab from the SiteMinder Policy Server. The maximum timeout and the idle timeout must be longer than the Lightweight Third-Party Authentication (LTPA) token timeout, which is defined on WebSphere Application Server and, by default, is set to 120 minutes.
Configure the ASA for WebSphere Application Server
To do this, follow these steps:
1. Copy the smagent.properties file from the ASA installation \conf folder over to the WebSphere Application Server profile properties folder, for example, C:\IBM\WebSphere\AppServer\AppSvr01\properties.
2. Ensure that your system PATH includes a path the ASA's bin directory (typically, C:\smwasasa\bin).
3. Start the WebSphere Administration Console, if not already running, and do the following:
(a) Select Security > Secure administration, applications, and infrastructure.
(b) Expand Web Security and click Trust Association.
(c) Put a check next to Enable Trust Association and click Apply.
(d) Click Interceptors and delete those you don’t require.
(e) On the Interceptors page, click New, enter the following SiteMinder ASA class name next to Interceptor Classname and click Apply:
com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor
(f) Save the changes to the master configuration by clicking Save on the next two screens, and log out of the Administration Console.
Adding rewrite rules to the HTTP Server
Rewrite rules must be added to the configuration file on the IBM HTTP server, so as to remap Atom API requests that are required by the Blogs portlets and by the Blogs feature of the Lotus Connections plug-in for Microsoft® Office. To do this:
1. Open the httpd.conf file, which is stored in C:\IBM\HTTPServer\conf, and then add the following rules to the file:
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/api/(.*) /blogs/roller-ui/rendering/api/$1/api/$2 [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/tags/atom(.*) /blogs/roller-ui/rendering/feed/ $1/tags/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/entries/atom(.*) /blogs/roller-ui/rendering/ feed/$1/entries/atom/ [R,L]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/comments/atom(.*) /blogs/roller-ui/rendering/feed/$1/comments/atom/ [R,L]
2. Save this file and then add rewrite rules that will redirect URLs when users log out of the product. Add the following rules to the httpd.conf file:
RewriteEngine On
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteCond %{QUERY_STRING} !=logoutExitPage=<your_logout_url>
RewriteRule /(.*)/ibm_security_logout(.*) <LogOffUri>?logoutExitPage=<your_logout_url> [noescape,L,R]
where
is the URL that you uncommented in when adding configuration parameters. The client's browsers will be sent to after logging out of Lotus Connections. This URL could be your corporate home page or the Lotus Connections log-in page.
NOTE:You must add these rules to both the HTTP and HTTPS entries.
Below is an example of what this section would look when the configuration is set up to use the hompage logoffuri and the browser is redirected back to the Lotus Connections homepage:
3. Save the httpd.conf file and restart the IBM HTTP Server.
Editing Lotus Connections configuration files to support SiteMinder
Next, there are a number of Lotus Connections configuration files that must be modified to complete the SiteMinder setup:
1. Update the Lotus Connections AJAX proxy configuration file:
(a) In the wsadmin client, use the following commands to check out the proxy configuration file:
execfile("connectionsConfig.py")
LCConfigService.checkOutProxyConfig("<working_directory>", "<cell_name>")
where
is a temporary directory of your choice. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows® operating system, and
is the name of the cell where the Lotus Connections feature that uses the global proxy file is located. This argument is required even in stand-alone deployments and is also case-sensitive, so type it with care.
(b) To support access to SiteMinder-protected URLs through the AJAX proxy, add the following declarations to the proxy configuration file for each feature:
<proxy:cookies>
<proxy:cookie>JSESSIONID</proxy:cookie>
<proxy:cookie>SMSESSION</proxy:cookie>
</proxy:cookies>
There is a section in proxy-config.tpl for each component; for example, below is the section for Activities and the declarations added are highlighted in bold text (remember that this should be done for each component in this file):
<proxy:policy url="{activities}/*" acf="none">
<proxy:actions>
<proxy:method>GET</proxy:method>
<proxy:method>POST</proxy:method>
<proxy:method>PUT</proxy:method>
<proxy:method>DELETE</proxy:method>
</proxy:actions>
<proxy:headers>
<proxy:header>User-Agent</proxy:header>
<proxy:header>Accept.*</proxy:header>
<proxy:header>Content.*</proxy:header>
<proxy:header>Authorization.*</proxy:header>
<proxy:header>If-.*</proxy:header>
<proxy:header>Pragma</proxy:header>
<proxy:header>Cache-Control</proxy:header>
</proxy:headers>
<proxy:cookies>
<proxy:cookie>JSESSIONID</proxy:cookie>
<proxy:cookie>SMSESSION</proxy:cookie>
</proxy:cookies>
</proxy:policy>
(c) Use the following commands to check in the proxy configuration file:
LCConfigService.checkInProxyConfig("<temp_directory>", "<cell_name>")
2. Add a SiteMinder authenticator property to the Lotus Connections configuration by editing the LotusConnections-config.xml file:
(a) Use the following command to check out the configuration file:
Stand-alone deployment:
execfile("connectionsConfig.py")
LCConfigService.checkOutConfig("<working_directory>","<cell_name>")
Network deployment:
execfile("<WAS_HOME>/profiles/<DMGR>/config/bin_lc_admin/connectionsConfig.py")
Note: If you are prompted to specify which server to connect to, type 1.
Enter the following command into the wsadmin client in the command line, to check in the file again after the user checked it out earlier.
LCConfigService.checkOutConfig("<working_directory>","<cell_name>")
where:
is the temporary working directory to which the configuration XML and XSD files are copied and stored while you make changes to them. Use forward slashes to separate directories in the file path, even if you are using the Microsoft Windows operating system.
is the name of the WebSphere Application Server cell hosting the Lotus Connections feature. This argument is required even in stand-alone deployments and is case sensitive. If you don't know the cell name, use one of the following commands to determine it:
For stand-alone deployment, look at the directory name in the following directory in the file system:
<$WAS_HOME>\profiles\\config\cells\
For network deployment, type the following command while in the wsadmin client:
print AdminControl.getCell()
3. Once checked out, update the custom authenticator values by running the following commands:
(a) Configure the custom authenticator to support server-to-server authentication for SiteMinder:
LCConfigService.updateConfig("customAuthenticator.name", "SiteMinderAuthenticator")
(b) Set the value of the custom.authenticator.cookieTimeout parameter to be equal to or less than the maximum timeout and idle timeout values that you configured previously. Specify the timeout value in minutes:
LCConfigService.updateConfig("customAuthenticator.CookieTimeout","<timeout>")
where is a value in minutes that is less than or equal to the SiteMinder timeout values.
If you are using the Profiles database as the user directory, complete the steps in the Information Center topic, “Enabling Lotus Connections directory service extensions.”
4. Check the LotusConnections-config.xml file back in by running the following command:
LCConfigService.checkInConfig()
5. The final edit is required only when the Communities or Profiles features are installed, which is true in the majority of cases. You must configure the Lotus Connections directory service extensions to point to your Web server (having already enabled the SiteMinder WA on the Web server):
(a) Open the configuration file that is appropriate to your deployment and run the command to change the Web server, using the following example as a guide:
<sloc:serviceReference
communities_directory_service_extension_auth="DSX-Admin"
communities_directory_service_extension_auth_alias="connectionsAdmin"
communities_directory_service_extension_enabled="true"
communities_directory_service_extension_href="http://connections.example.com/communities/dsx/"
profiles_directory_service_extension_auth="DSX-Admin"
profiles_directory_service_extension_auth_alias="connectionsAdmin"
profiles_directory_service_extension_enabled="true"
profiles_directory_service_extension_href="http://connections.example.com/profiles/dsx/"
serviceName="directory"/>
Enabling SiteMinder
Once all the above changes are made, SiteMinder must be enabled to work with Lotus Connections. Some of these steps may already be completed, but check to be sure:
On the Application Server machines:
1. Find the AsaAgent-assertion.conf file, which is is (typically) located in C:\smwasasa\conf, and open it in a text editor (see figure 2). Ensure the EnablewebAgent flag is set to Yes; save this change.
Figure 2. AsaAgent-assertion.conf in Notepad
2. If you made the above change, be sure to restart all application servers, node agents, and the deployment manager.
On the HTTP Server:
1. Find the file WebAgent.conf in C:\IBM\HTTPServer\conf and open it with a text editor (see figure 3).
Figure 3. WebAgent.conf in Notepad
2. Ensure that the EnableWebAgent flag is set to Yes, and restart the HTTP Server.
3. Once enabled, the CA Login screen shown in figure 4 will display instead of the normal Connections log-in screen.
Figure 4. CA log-in window
4. Authenticate with your usual credentials, and you'll be signed into both Lotus Connections and SiteMinder!
Troubleshooting
(1) Web Agent installation fails on Microsoft Windows.
This is an Operation System special case. For Microsoft Windows, edit the Registry as follows, so the SiteMinder Web Agent can get the HTTP Server’s installPath to finish its registration (see figure 5):
Name: installPath (1)
Type: REG_SZ
Data: equal to the Data of variable "installPath"
Figure 5. Registry Editor
See Attachments at bottom of this article:
conn25realms.txt
conn25forms.txt
create25others.pl
create25forms.pl
conn25realmssunprotected.txt
