ShowTable of Contents
Introduction
This document explains how to set up integration between Lotus Connections 3.0 and Computer Associates SiteMinder. This article looks at this integration almost entirely from the Lotus Connections perspective. For a fuller understanding of SiteMinder integration and what actions need to be taken on the SiteMinder policy server, refer to the Lotus Connections 3.0 product documentation topic entitled [Enabling single sign-on for SiteMinder: lc3].
To view the content of this article as a PDF, download the
http://www-10.lotus.com/ldd/lcwiki.nsf/xsp/.ibmmodres/domino/OpenAttachment/ldd/lcwiki.nsf/BAB680AA7724F59585257811006FAEDC/attach/SSO_S3.pdf|SSO_S3.pdf attachment">SSO_S3.pdf">http://www-10.lotus.com/ldd/lcwiki.nsf/xsp/.ibmmodres/domino/OpenAttachment/ldd/lcwiki.nsf/BAB680AA7724F59585257811006FAEDC/attach/SSO_S3.pdf|SSO_S3.pdf attachment.
Prerequisites
Before beginning SiteMinder enablement with Lotus Connections 3.0 ensure that the following items are complete:
*Lotus Connections 3.0 is setup and working with the IBM HTTP Server without issue.
*The J2C Authentication Alias "connectionsAdmin" is a user who exists on the LDAP and has administrative rights on the WebSphere Administration Console.
What is SiteMinder
Computer Associates is a Web access control product providing web single sign-on (SSO), centralized policy management for authentication, authorization, auditing and user entitlement.
A SiteMinder Web Agent is a software component that controls access to any resource that can be identified by a URL. The Web Agent resides on a web server and intercepts requests for a resource to determine whether or not the resource is protected by SiteMinder. The Web Agent then interacts with the Policy Server to authenticate and authorize users who request access to the protected web server resources.
When a user requests a page that is protected by SiteMinder, the Web Agent on the HTTP server intercepts the request and prompts the user for authentication. If the user provides valid credentials, the user is authenticated and an SMSESSION cookie is added to the request which is then passed on to the WebSphere Application Server. The SiteMinder Trust Association Interceptor (TAI) -also known as Application Server Agent - on the WebSphere Application Server verifies the information in the cookie and sets the User Principal(the User UID) that Lotus Connections requires to identify the user.
Enterprise Network Deployment with SiteMinder Security Diagram
This configuration diagram shows the Lotus Connections architecture with the addition of Computer Associates SiteMinder to protect the entire configuration. In this scenario SiteMinder is connected to the LDAP and has agents installed on the nodes and web server. When a user tries to access Lotus Connections via the webserver SiteMinder intercepts and presents the SiteMinder login page. Once they authenticate SiteMinder adds its SMSESSION cookie to the request and the user is logged onto Lotus Connections via single-sign on.
Complex Enterprise Network Deployment Architecture Including Integration
How SiteMinder Integration Works
The following diagram explains how SiteMinder Integration works when used with WebSphere TAI and a Web Agent on the IBM HTTP Server.
The following step numbers correspond to each of the above communications:
- User access protected resource.
- Siteminder Web Agent on HTTP Server intercepts the request and prompts for Authentication.
- User enters Username and password.
- Siteminder Web Agent Passes username and password to Siteminder Policy Server.
- Siteminder Policy Server attempts to Authenticates the user against the LDAP.
- Policy Server uses the User Directory Object Details specified in the Siteminder Administration Console.
- After successful authentication, the Policy Server Authorizes the user.
- Siteminder checks the users and Groups assigned access in the Policy.
- Siteminder checks the Rules for the Requested methods and urls.
- Siteminder adds SMSESSION cookie to the request.
- Request is returned to the HTTP Server.
- Siteminder Web Agent on the IBM HTTP Server checks for valid SMSESSION cookie.
- Request is sent to the WebSphere Server.
- Siteminder ASA Agent on the WebSphere Server checks for valid SMSESSION cookie.
- ASA Agent asserts user details to the WebSphere Server.
- WebSphere performs it's own internal authorization.
- Allows access to the requested resource.
- Response is returned to the Http Server.
- Response sent to user with the requested resource.
Enabling Single Sign-On with Computer Associate's SiteMinder
The following section is quite complex, it is therefore recommended to refer to the Lotus Connections 3.0 infocenter along with this guide to get the fullest understanding of how SiteMinder integration with Lotus Connections 3.0. This discussion focuses mainly on the Lotus Connections perspective of SiteMinder enablement with Lotus Connections 3.0. For the purposes of this guide the following table represent the values of the various SiteMinder objects required for this configuration.
SiteMinder Objects | HTTP Server
connections.example.com | WebSphere Application Server Node 1
node1.example.com | WebSphere Application Server Node 2
node2.example.com |
Agent Object | connections_wa | node_TAI | node_TAI |
Agent Config Object | connections_wa_conf | node_TAI_conf | node_TAI_conf |
Host Config Object | host_connections | host_node1_TAI | host_node2_TAI |
Trusted Hostname | connections | node1_TAI | node2_TAI |
Important Notes
The connectionsAdmin J2C Authentication Alias that you specified during installation must correspond to a valid account that can authenticate with SiteMinder. It may map to a back-end administrative user account. This account must be capable of authenticating for single sign-on against SiteMinder. If you need to update the user ID or credentials for this alias, see the
Changing references to administrative credentials topic in the Lotus Connections 3.0 InfoCenter.
For more information about the SiteMinder Policy Server and Web Agent configuration, go to the
SiteMinder BookShelf.
For more information about the SiteMinder Agent for WebSphere, see the
SiteMinder Agent for WebSphere Agent Guide (PDF) and CA
SiteMinder Agent for WebSphere Agent Release Notes® (PDF).
You need to create SiteMinder Agent and Domain objects with realms, rules, and a policy that is related to IBM HTTP Server and WebSphere Application Server. When a user requests a page that is protected by SiteMinder, the Web Agent on the HTTP server intercepts the request and prompts the user for authentication. If the user provides valid credentials, the user is authenticated and an SMSESSION cookie is added to the request which is then passed on to the WebSphere Application Server. The SiteMinder Trust Association Interceptor (TAI) on the server verifies the information in the cookie and sets the User Principal that Lotus Connections requires to identify the user.
This task describes a configuration that uses SiteMinder Policy Server 6.0 SP5, SiteMinder ASA 6.0 Agent for WebSphere Application Server (with CR00010 hotfix), and SiteMinder Web Agent v6qmr5-cr035.
To set up SSO using SiteMinder, complete the following steps:
Preparing WebSphere Application Server for SiteMinder
Setup Single Sign-On Domain if not already done so. On the deployment manager navigate to Security -> Global Security -> Web and SIP Security -> Sign Sign-On (SSO). Ensure the following is set:
Next copy the unrestricted JCE policy files to the Application Server and Deployment Manager machines. The unrestricted JCE files can be downloaded from the following web page, note that you will have to login with your universal IBM user ID and password to download these files,
https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?source=jcesdk . Once the files are downloaded extract them from the package. The files in question are called :
* US_export_policy.jar
* local_policy.jar.
On the two nodes and deployment manager machine go to the following location and take a backup of the existing files and then copy in the new unrestricted versions to this location. All servers, node agents and deployment manager's must be restarted in order for this change to take effect.
Install the Web Agent on IBM HTTP Server
Download the above version of the Web Agent from the
CA website.
Install the Web Agent. For instructions, go to the
SiteMinder BookShelf.
When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created
earlier.
Launch the webagent installation wizard, select Next at the below panel:
Accept the licence agreement and click next:
Click next at the information panel below:
Select a path to install the webagent to and click next to continue
Select if you wish a new group to be created in your start menu:
Click Install to begin the Web Agent installation.
Select Yes to configure the web agent now.
Select Yes to do host registration now :
Input the username and password of the SiteMinder administrator and click next:
Input the Trusted Host Name and Host Configuration Object, remember these values are taken from the table at the start of this section and are assumed to already exist before completing this task.
Add the IP address of the SiteMinder server:
Properties for the SmHost.conf, select next to continue:
Register the IBM HTTP Server with SiteMinder, click next. See troubleshooting steps for SiteMinder if no options appear on this screen.
Input the agent configuration object name :
Select the advanced authentication to use depending on your requirements click Next.
At the following panel click No, I don't want to configure Self Registration and click next.
Review the web agent configuration options and click Install.
Review any errors which occur, in this case they are benign but it is important to check SiteMinder logs when completing this step. Click Done to end the wizard.
In this case the installation log at C:\Program Files\netegrity\webagent\install_config_info\CA_SiteMinder_Web_Agent_v6QMR5_InstallLog.log reports the following, there are no fatal errors so we are safe to proceed:
Installation: Successful with errors.
273 Successes
0 Warnings
11 NonFatalErrors
0 FatalErrors
After configuring the webagent as above. Find the WebAgent.conf in the HTTPServer/conf directory. Open this file and edit it so EnableWebAgent=YES. Now restart your HTTP Server. When attempting to access the HTTP Server root you should now see the SiteMinder login screen and be able to login to get the IBM HTTP Server Splash Screen. This indicates that SiteMinder is set up correctly with the WebAgent.
Install the Application Server Agent
Install the Application Server Agent on your both nodes - node1.example.com and node2.example.com
- Download the above version of the Application Server Agent from the CA website.
- Install the Application Server Agent on each node in your Lotus Connections deployment. For instructions, see the SiteMinder Agent for WebSphere Agent Guide.
- When you are prompted for the Agent Configuration details, specify the Agent Configuration Object that you created earlier.
Launch the installer for the application server agent click next to continue:
Accept the licence agreement, click next to continue:
Choose a installation location and click next to continue
Select Yes, Continue :
Specify where WebSphere is installed:
Select Yes, create a trusted host:
Enter the information of the SiteMinder server, click Next to continue:
Allow the wizard time to register the host :
Enter the agent configuration object name and click next :
Review any errors messages in the installation log. In this case there are benign errors. Click Done to exit the wizard.
In this case the installation log at C:\smwasasa\log\CA_eTrust_SiteMinder_Agent_v6.0_for_WebSphere_InstallLog.log reports the following, again there are no fatal errors so we are safe to proceed :
Summary
-------
Installation: Successfulwith errors.
96 Successes
0 Warnings
1 NonFatalErrors
0 FatalErrors
Actions on WebSphere Application Server post Agent Installation
When the Application Server Agent is configured ensure to copy smagent.properties from the agent installation directory - smwasasa\conf to AppServer\profiles\AppSrv01\properties
Configure Trust Association Interceptor on WebSphere Application Server. From the deployment manager administrative console for WebSphere Application Server, click Security > Global security -> Web and SIP security, click Trust association. Click Enable Trust Association and then click Save.
Next Click Interceptors, Click the new button and add an interceptor with the following name (com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor). Click OK and save the change.
It is OK to delete any unused interceptors - in this case the interceptor we added is the only one required for SiteMinder enablement. Leaving these other interceptors inplace will not cause any issues but will results in error messages in the logs during startup so it makes sense to delete these interceptors. Click Delete and save this change.
Actions on HTTP Server post Agent Installation
Create rewrite rules to remap Atom API requests and to redirect URLs when users log out of Lotus Connections. Open the IBM HTTP Server httpd.conf configuration file. The file is stored in the C:\IBM\HTTPServer\conf directory on the web server machine (connections.example.com). The extracted section of the httpd.conf below shows these rules implemented in both the HTTP and HTTPS sections of this file. The rules added are shown in bold, your httpd.conf should reflect the below when this step is completed. In this extract the logout rules will redirect users to the homepage logout screen and when they are logged out they will be redirected back to the page at home.example.com, which may be a corporate homepage for example. When this change is made save and close the httpd.conf file. Restart the IBM HTTP Server.
RewriteEngine on
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteCond %{QUERY_STRING} !=logoutExitPage=http://home.example.com
RewriteRule /(.*)/ibm_security_logout(.*) /homepage/web/ibm_security_logout?logoutExitPage=http://home.example.com [noescape,L,R]
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]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L]
#Connections Config for SSL
LoadModule ibm_ssl_module modules/mod_ibm_ssl.so
<IfModule mod_ibm_ssl.c>
Listen 0.0.0.0:443
<VirtualHost *:443>
ServerName connections.example.com
SSLEnable
RewriteEngine on
RewriteCond %{REQUEST_URI} /(.*)/ibm_security_logout(.*)
RewriteCond %{QUERY_STRING} !=logoutExitPage=http://home.example.com
RewriteRule /(.*)/ibm_security_logout(.*) /homepage/web/ibm_security_logout?logoutExitPage=http://home.example.com [noescape,L,R]
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]
RewriteCond %{REQUEST_URI} !^/blogs/roller-ui/rendering/(.*)
RewriteRule ^/blogs/(.*)/feed/blogs/atom(.*) /blogs/roller-ui/rendering/feed/$1/blogs/atom/ [R,L]
</VirtualHost>
</IfModule>
SSLDisable
Configure Lotus Connections Custom Authenticator for SiteMinder
The customAuthenticator element in the LotusConnections-config.xml file defines some key parameters of your single sign-on (SSO) solution. The configuration settings that you can specify in this XML element only affect back-end inter-service communication in an SSO environment. The attributes for the customAuthenticator element can differ, depending on the SSO solution that you have implemented. Most attributes are optional, but some might be mandatory in the context of your SSO solution. For more information, see the relevant topics for your authentication solution and the InfoCenter topic dedicated to this topic.
Add a SiteMinder authenticator property to the Lotus Connections configuration by editing the LotusConnections-config.xml file. Start the wsadmin client and check out the Lotus Connections configuration file.
Update the custom authenticator values by running the following commands:
Configure the custom authenticator to support server-to-server authentication for SiteMinder:
Set the value of the custom.authenticator.cookieTimeout parameter to be equal to or less than the maximum timeout and idle timeout values already configured. To do this you must open the LotusConnections-config.xml from the C:\temp directory and manually make the change. As the key CookieTimeout is not yet part of this file. Specify the timeout value in minutes. In this case 60 minutes is the specified timeout value.
Note:when your production environment is ready, set the AllowSelfSignedCerts property to false. In a similar fashion to adding CookieTimout this must be done manually on the checked out LotusConnections-config.xml before checking it back in.
The below is a snippet of the content of the XML as it should look when updated with the aforementioned values:
<customAuthenticator name="SiteMinderAuthenticator" >
<attribute key="AllowSelfSignedCerts" value="true" />
<attribute key="CookieTimeout" value="60" />
</customAuthenticator>
Check the LotusConnections-config.xml file back in by running the following command:
Update the reauthenticate property in the files-config.xml file. When this property is set to false, and when a Lotus Connections application detects a session timeout, users must log in again through the SSO authentication mechanism. To update the reauthenticate property, complete the following steps:
- Login to the wsadmin client.
- Execute the following command to load files administration - execfile("filesAdmin.py")
- Execute the following command to check out the files configuration file - FilesConfigService.checkOutConfig("C:/temp","dmCell01")
- Update the reauthenticate property by running the following command - FilesConfigService.updateConfig("security.reauthenticateAndSaveSupported", "false")
- Check the files-config.xml file in by running the following command - FilesConfigService.checkInConfig()
Enabling and Disabling SiteMinder on the Configuration
If there is need to enable or disable SiteMinder at any point do the following :
- Edit the WebAgent.conf on the HTTP Server machine (HTTPServer/conf/WebAgent.conf) and set "EnableWebAgent=NO". Restart the IBM HTTP Server.
- Change the custom authenticator back to the default authenticator in the LotusConnections-config.xml.
- Edit smwasasa/conf/AsaAgent-assertion.conf on both nodes and set "EnableWebAgent=NO".
- Resynchronise nodes and restart Lotus Connections 3.0.
Repeat this process to enable SiteMinder and instead set EnableWebAgent=YES where we set it to NO before. You must also re-enable the custom authenticator in the LotusConnections-config.xml and restart the deployment.
When SiteMinder is enabled the following message should appear in the SystemOut.log for all Lotus Connections application servers to indicate SiteMinder has loaded correctly with the config:
[10/11/10 12:45:23:225 EDT] 00000000 TrustAssociat A SECJ0121I: Trust Association Init class com.netegrity.siteminder.websphere.auth.SmTrustAssociationInterceptor loaded successfully
Troubleshooting SiteMinder Issues
The following section outlines how to gather trace and log information from the servers for troubleshooting purposes. There is also a common issue outlined with a solution and a brief overview of the key SiteMinder configuration files created on the Lotus Connections machines when installing and registering the SiteMinder agents.
Enabling Trace
Most errors encountered in this environment are typically interservice issues - communication errors between the back-end servers often due to authorization issues caused by the introduction of SiteMinder to the configuration. The following trace is appropriate in this circumstance to help diagnose issues:
com.ibm.connections.httpClient.*=all
|
Log Files to Help Diagnose Issues
To get complete overview of any issues on the system with SiteMinder enabled the following log files should be consulted:
Lotus Connections Server Log Files
SystemOut.log
trace.log (if applicable)
SiteMinder Log Files (On Nodes...)
smwasasa/log/smasa.log
smwasasa/log/sm_tai.log
SiteMinder Log Files (On web server...)
nnetegrity/webagent/log/wa.log
netegrity/webagent/log/wa_trace.log
SiteMinder Server Log Files
Consult the SiteMinder documentation to uncover what traces and logs can be enabled / referenced on the SiteMinder server side.
Common Issue - HTTP Server does not Start with SiteMinder Enabled
The following error message occurs when attempting to start the HTTP Server.
Open the httpd.conf on the webserver and comment out the line containing mod_sm20.dll below.
#LoadModule sm_module "C:/Program Files (x86)/netegrity/webagent/bin/mod_sm20.dll"
Now add the below line ending with sm22.dll in its place to load the correct module for SiteMinder Web Agent to work as expected.
LoadModule sm_module "C:/Program Files (x86)/netegrity/webagent/bin/mod_sm22.dll"
SiteMinder Configuration Files created by Web Agent and TAI/ASA
Here is a sample of the key configuration files on the nodes which are correctly configured. Note the relationship between all of the files below. Changes to these files require a restart to the web server in case of web agent and application server in case of ASA/TAI.
WebAgent.conf
WebAgent.conf is found in
/conf/WebAgent.conf and refers to the AgentConfigObject and SmHost.conf (which contains the policy server connection details). Also note the EnableWebAgent parameter.
# WebAgent.conf - configuration file for SiteMinder Web Agent
# Web Agent Version = 6QMR5, Build = 852, Update = 0
#agentname="<AgentName>, <IPAddress>"
HostConfigFile="/opt/netegrity/webagent/config/SmHost.conf"
AgentConfigObject="connections_wa_conf"
EnableWebAgent="YES"
ServerPath="/opt/IBM/HTTPServer/conf"
localconfigfile="/opt/IBM/HTTPServer7/conf/LocalConfig.conf"
LoadPlugin="/opt/netegrity/webagent/bin/libHttpPlugin.so"
#LoadPlugin="/opt/netegrity/webagent/bin/libAffiliate10Plugin.so"
#LoadPlugin="/opt/netegrity/webagent/bin/libSAMLAffiliatePlugin.so"
#LoadPlugin="/opt/netegrity/webagent/bin/libeTSSOPlugin.so"
#LoadPlugin="/opt/netegrity/webagent/bin/libIntroscopePlugin.so"
LogFile="YES"
LogFileName="/opt/netegrity/webagent/log/wa56.log"
LogAppend="NO"
TraceFile="YES"
TraceFileName="/opt/netegrity/webagent/log/wa56_trace.log"
TraceAppend="NO"
TraceConfigFile="/opt/netegrity/webagent/config/webagenttrace.conf"
SmHost.conf
SmHost.conf is found at /bin/SmHost.conf, refers to the policy server by IP address. It also contains the hostname and hostconfigobject reference.
# Host Registration File - SmHost.conf
#
# This file contains bootstrap information required by
# the SiteMinder Agent API to connect to Policy Servers
# at startup. Be sure the IP addresses and ports below
# identify valid listening Policy Servers. Please do not
# hand edit the encrypted SharedSecret entry.
hostname="node1.example.com"
hostconfigobject="host_node_TAI"
policyserver="9.162.138.40,44441,44442,44443"
requesttimeout="60"
sharedsecret="{RC2}jEJuWUWx0sCpKF6D4mUIkWxLBjAHFvKW0ArU/khAqlmTRFziYgglFlRRppcPGaQJhJzjRTzC1VdS70um1Le/+mzTeGEpFOtTwurkmSJy2DCECGD0BAGDGTvsezeisbRmlPIoCkSyRqQIgR/zajgBPbICZiGlughngk/cfZPJzKTOS4ZpgfvMsRLdDlrhUYZf"
sharedsecrettime="1277806946"
AsaAgent-assertion.conf
AsaAgent-assertion.conf, found at /conf/AsaAgent-assertion.conf, contains an EnableWebAgent flag as well as references SmHost.conf and holding the value of the agent configuration object
#####################################################
## SiteMinder IBM WebSphere Application Server Agent
#####################################################
EnableWebAgent="YES"
HostConfigFile="/opt/smwasasa/bin/SmHost.conf"
AgentConfigObject="node_TAI_conf"
smagent.properties
SmAgent.properties, found at /conf/smagent.properties, is created when the ASA is registered. It contains the location of the AsaAgent-assertion.conf and is copied to /profiles/AppSrv01/properties on both nodes during the SiteMinder configuration.
##############################################################
# SiteMinder Generic Application Server Agent Properties File
##############################################################
logfilename="/opt/smwasasa/log/smasa.log"
loglevel="4"
logappend="NO"
logfile="YES"
logconsole="NO"
smazconf="/opt/smwasasa/conf/AsaAgent-az.conf"
smauthconf="/opt/smwasasa/conf/AsaAgent-auth.conf"
smassertionconf="/opt/smwasasa/conf/AsaAgent-assertion.conf"
About the Author
Colm O'Brien is a member of the Lotus Connections System Verification Test (SVT) team and works in the area of product deployment and reliability testing. Colm has worked extensively in the area of SiteMinder Single Sign-On with Lotus Connections.