Abstract
The objective of this document is to detail the experiences of the IBM System Verification Test (SVT) team when enabling Lotus Domino Quickr 8.5 services with IBM Tivoli Access Manager WebSEAL. The goal of our testing was to ensure that Quickr Domino performed as expected when integrated with TAM. Hints and tips are provided at the end of the document to assist administrators in setting up the more intricate aspects of a Quickr Domino deployment
Overview
The components required to install and configure in this scenario are Lotus Domino-Quickr server, IBM Tivoli Access Manager WebSEAL, Lotus Sametime server and Lotus Connection Server. All components are configured to share the same LDAP, and MSSO is implemented using a common LTPA token. The operating system used this environment is SuSE Linux Server 11 Operating System which is based on a single server scenario.
The environment included the following components:
•Lotus Domino 8.5.1(Fixpack 3) server
•Lotus Quickr services for Lotus Domino 8.5
•IBM Tivoli Access Manager 6.1
•LDAP server: IBM Lotus Domino 8.5.1
•Lotus Quickr Services for Lotus Connections 2.5.0.2
Infrastructure Diagram
Specification
The following tables list the specifications for the computers used in the infrastructure.
TAM integration deployment
|
|
|
|
|
|
|
|
|
4 CPUs @3.2 GHz - 3.5 Gig Ram
|
|
|
|
Lotus Domino 8.5.1 +FP3 Lotus Quickr 8.5
|
1 Xeon @3.67 GHz - 3.5 Gig Ram
|
|
|
|
IBM Tivoli Access Manager 6.1
|
1 xeon @2.80 GHz - 1 Gig Ram
|
| Network Dispatcher | Win2003 Server | IBM Websphere Edge Components Load balancer 7.0 | 1 xeon @2.80 GHz - 1 Gig Ram |
Assumptions
The LTPA token is assumed to be generated in advance. It is required to implement MSSO between all the servers.
Although Domino has the ability to implement MSSO between Domino servers, a shared LTPA token is required to implement MSSO between Quickr, the other Lotus products and TAM
Tip: Generate an LTPA token in the WebSphere application server associated with Connections and save it on Domino server, then import the LTPA token to create MSSO between all servers.
Configuring the Quickr Server with TAM
1. Install and configure Tivoli Access Manager WebSEAL. For steps, refer to the
Tivoli Access Manager Information Center.
Make the following changes to the WebSeal configuration, save the file and restart the WebSEAL from services.msc to take effect:
If you installed WebSEAL in its default folder, the configuration file is located in : C:\Program Files\Tivoli\PDWeb\etc\webseald-default.conf
- Enable script filtering by setting 'script-filter' to 'yes'
- Add filter for BUTTON = ONCLICK event under [filter-events]
- Enable absolute URLs by setting 'rewrite-absolute-with-absolute' to 'yes'
- If dynurl is enabled on your WebSEAL, set 'dynurl-allow-large-posts' to 'yes'
- Add the following content types to [filter-content-types] stanza
type = application/xhtml+xml
type = application/atomsvc+xml
type = text/xml
type = application/rss+xml
type = application/xml
type = application/atom+xml
type = text/javascript
- enable both basic and form based authentication:
ba-auth = both
forms-auth = both
- Make sure that local cache is cleared after logging out from TAM
logout-remove-cookie = Yes
2. Install and setup Lotus Quickr services for Lotus Domino, and configure it so that’s it uses the the same LDAP as Tivoli Access Manager.
3. Configure Domino Multiple SSO with the same LTPA token that will be employed to create the junction on the TAM server. See the Hints and Tips section
4. Create junction from TAM server for Domino Quickr:
pdadmin> server task default-webseald-[servername] create -t tcp -h [Load balancer host] -p 80 -i -b ignore -j -A-J trailer
-F [path to LTPA key] -Z [LTPA key password]/junction
pdadmin> server task default-webseald-qrdsvt15.cn.ibm.com create -t tcp -h clusternd.cn.ibm.com -p 80 -i -b ignore-j -A -J trailer
-F c:\sso -Z password /new
in this example,"qrdsvt15.cnibm.com" is the TAM server host name, and "new" is the junction name, "clusternd.cn.ibm.com" is the host name of load balancer server
c. Import users who want to access Domino Quickr through TAM from LDAP server to TAM server, command like:
pdadmin> user import [-gsouser]
eg.
user import Aamir_301_000 "CN=Aamir Aamir_301_000,OU=Users,OU=Dom85,OU=Lotus,OU=Software Group,o=ibm"
d. Validate users on TAM server, command like:
pdadmin> user modify account-valid {yes|no}
pdadmin> user modify password-valid {yes|no}
eg.
user modify Aamir_301_000 account-valid yes
e. Create ACL for Lotus Connectors:
To make connector works properly, please pay attention to the following 2 points:
1) use this option when creating junction: "-b ignore" , "-j" are must when you create junctions for quickr, for example:
server task default-webseald-TAM.cn.ibm.com create -t tcp -h clusternd.cn.ibm.com -p 80 -i -b ignore -j -J trailer -f -A -F c:\sso.key -Z passw0rd /junction
2) ACL
Create an ACL to unauthenticate access. The following example names the ACL "open":
acl create open
acl modify open set any-other Trx
acl modify open set unauthenticated Trx
Attach the ACL to the Connector URL. In the following example, /WebSEAL/default-webseald-TAM.cn.ibm.com/ is the WebSeal namespace:
acl attach /WebSEAL/TAM.cn.ibm.com-default/junction/dm open
3) Add a place to your connector: remember to involve the junction name to the end of the URL, for example:
in this example, "new" is the junction name for Lotus Quickr, "qrdsvt15.cn.ibm.com" is the TAM server host
5.Disable "Create Local User "
- Login to Quickr as the Quickr admin,
- Go to "Site Administration"/"User Directory",
- Click "Change Directory" button,
- In the last section "New Users", check "Disallow new users-Require managers to select existing users from the available directory",
- Click "Next" to save your changes.
6. Verify WebSEAL junction by URL, like:
http://TAM.cn.ibm.com/junction/LotusQuickr
Creating or editing a Web SSO Configuration document and Enabling the Domino servlet engine:
The Web SSO configuration document is a domain-wide configuration document stored in the IBM Lotus Domino Directory. This document, which should be replicated to all servers participating in the single sign-on domain, is encrypted for participating servers and administrators, and contains a shared secret key used by servers for authenticating user credentials.
To set up multi-server single sign-on for a IBM Lotus Quickr server, first create a Web SSO Configuration document, if there is not one already. If there is already a Web SSO Configuration document, edit the document by adding the Lotus Domino server names of the Lotus Quickr servers to it.
Creating a Web SSO Configuration document:
Create a Web SSO Configuration document if there is not one already.
1. Open the Domino Directory (names.nsf) of an IBM Lotus Quickr server in the domain.
2. Click the
Configuration →
Servers →
All Server Documents view.
3. Click
Web and then cllick
Create Web SSO Configuration.
4. Click
Keys at the top of the Web SSO Configuration document.
5. To Initialize the Web SSO Configuration with a Domino shared secret key, click
Create Domino SSO Key. Or, to import an IBM WebSphere LTPA key, perform the following steps:
a. Click
Import WebSphere LTPA Keys.
b. Enter the path to the WebSphere LTPA export file (see WebSphere documentation for details about generating ltpatoken keys).
c. Enter the password (specified when generating the keys in WebSphere). The document is updated to reflect the information in the export file.
6. Complete the rest of the document as follows:
Field Action Configuration Name Type
LtpaToken. This value is required. Organization Leave this field blank so the document appears in the Web Configurations view. DNS Domain (Required) Type the DNS domain (for example, acme.com) for which the tokens will be generated. The servers enabled for single sign-on must all belong to the same DNS domain. Domino Server Names Type the names of the IBM Lotus Domino servers to participate in single sign-on; for example, server1/acme, server2/acme. This document is encrypted so that only you, the members of the Owners and Administrators fields, and the servers specified have access to it.
Note: Type only Lotus Domino server names in this field; group names, wild cards, and WebSphere server names are not allowed. Expiration (minutes) Specify the time period, in minutes, after which the token will expire. The default is 30 minutes
Field Action Idle Session Timeout Click
Enabled and specify a Minimum Timeout value, in minutes, to indicate the number of minutes of inactivity after which the token will expire
7.Click
Save & Close to save the Web SSO Configuration document in the Web - Web Configurations view. A message on the status bar indicates the number of servers or people for whom the document is encrypted. If you receive messages on the client indicating that a particular key was not found for encrypting the document, you might have to change your client’s location document to point to a different mail or directory server that has all the public keys included in Server and Person documents.
Editing an existing Web SSO Configuration document:
A Web SSO Configuration document may already exist for the domain. This might be the case, for example, if a IBM Lotus Sametime server is also installed in the domain. In this case, add the Lotus Domino names of the IBM Lotus Quickr servers to the existing Web SSO Configuration document.
1. Open the Domino Directory (names.nsf) of an IBM Lotus Quickr server in the domain.
2. Click the
Web →
Web Server Configurations view.
3. Open the Web SSO Configuration document in edit mode.
4. In the
Domino Server Names field, add the hierarchical Domino server name of each Lotus Quickr server in the domain that will participate in single sign-on; for example, server1/acme, server2/acme.
5. Close and save the document.
Completing single sign-on setup:
After you have created or edited the Web SSO Configuration document for the domain, complete single sign-on setup. Perform the following steps:
1. Add the following setting to the notes.ini file of each IBM Lotus Quickr server that you will enable for single sign-on. This step prevents anonymous access to files in the html directory: NoWebFileSystemACLs=1
2. Enable multi-server session-based authentication in the Server document for each Lotus Quickr server that you want to enable for single-sign on:
a. Open the Domino Directory (names.nsf) on the server.
b. Click the view
Configuration →
Servers →
All Server Documents.
c. Click the Server document for the server and click
Edit Server.
d. Click
Ports →
Internet Ports →
Web, and enable Name-and-password authentication for the Web (HTTP or HTTPS) port.
e. Click the
Internet Protocols - Domino Web Engine tab.
f. Next to
Session authentication, select
Multiple Servers (SSO).
g. Next to
Web SSO Configuration, select
LtpaToken.
h. Click
Save & Close.
3. Create the Domino Web Server Configuration database (domcfg.nsf) if it does not exist:
a. From an IBM Lotus Notes client, choose
File →
Database →
New.
b. Next to
Server at the top of the dialog box, select the server that runs Lotus Quickr.
c. Next to
Title, type a descriptive title, for example, Web Server Configuration.
d. Next to
File name, type domcfg.nsf. You must use this file name
e. Next to
Server in the middle of the dialog box, select any server.
f. Click
Show advanced templates.
g. Next to
Template, select
Domino Web Server Configuration (domcfg5.ntf).
h. Click
OK.
4. Create a mapping form in the Domino Web Server Configuration database to enable single-sign on to work with Lotus Quickr:
a. Open the Web Server Configuration database (domcfg.nsf).
b. Click
Add Mapping.
c. Next to
Applies To, select
All Web Sites/Entire Server (default) or
Specific Web Site/Virtual Server. If you select
Specific Web Site/Virtual Server, a new field displays in which you specify the IP addresses of the Web Site documents or Virtual Servers.
d. Next to
Target Database, type
LotusQuickr/resources.nsf, replacing the default entry. The path is case-sensitive on UNIX. If you upgraded from an earlier release and did not change the root directory name, type
QuickPlace/resources.nsf.
e. Next to
Target Form, type
QuickPlaceLoginForm.
f. Click
Save & Close.
g. Replicate the database to all the Lotus Quickr servers that will use single sign-on.
5. After the Domino Web Server Configuration database has replicated, at the server console of each server, enter the following command to stop and restart the server: restart server The message ″Successfully loaded Web SSO Configuration″ confirms single sign-on setup.
Enabling the Domino Servlet Engine:
After you have installed or upgraded to IBM Lotus Quickr, enable the Domino Servlet Engine. This step enables place managers to use place administration actions, such as
qptool lock and
unlock from
My Places →
Show Usage Statistics.
Note: To use this feature you must configure the server to use single sign-on authentication.
Perform the following steps:
1. From IBM Lotus Notes or the Domino Administrator, open the Domino Directory (names.nsf) on the server.
2. Open the Server document.
3. Click
Internet Protocols →
Domino Web Engine.
4. Below
Java Servlets, select
Domino Servlet Manager in the
Java servlet support field.
5. Save and close the document
To enable and configure TAM logout Button and to return to TAM login screen,edit the following script in qpconfig.xml file
<authentication>
<sign_out enabled="true">
<clear_browser_cache enabled="true" />
<url>http://TAM.cn.ibm.com/pkmslogout</url>
</sign_out>
<sign_in enabled="true" />
</authentication>
To enable to open places in Same window enable the following xml file in qpconfig.xml
<my_places>
<place_ui enabled="true">
<url />
</place_ui>
<place_links open_new_window="false" />
<include_anonymous enabled="true" />
<placetypes>
<entry_placetype>
<anonymous enabled="true" />
</entry_placetype>
</placetypes>
</my_places>
Make the following change to get the places to redirect to the TAM Server address from the Place Catalog.
<cluster>
<master virtual="true" ssl="false">
<port>80</port>
<hostname>TAMserverhost.domain</hostname>
<path_prefix>new</path_prefix>
</master>
</cluster>
Issues/Troubleshooting.
1.Failed to add members
http://www.ibm.com/support/docview.wss?rs=4089&uid=swg21298380:When the same TAM server is configured for use with Quickr Domino 8.5 and Quickr J2EE, it is not possible to add users to places.This configuration is unsupported.
2.When a user x creates a place for other user y, user x cannot navigate to user y’s place. After the place is created, when user x attempts to navigate to the newly created place, they are brought to the Quickr Domino SSO page, not the TAM logon.
This is a known product limitation when integrated with TAM
3. Failed to start WebSEAL Service in Windows if the OS was restarted abnormally:
Use this command to get more details about WebSEAL:
If you get information like the following, it means the problem comes from webseald-default.db
2009-12-09-21:10:10.937+08:00I
0x38CF0156 webseald WARNING wwa server s:\am web610\src\pdweb\webseald\init\globals\config.cpp 1828 0x000009cc
DPWWA0342W The configuration data for this WebSEAL instance has been logged in
'C:/Program Files/Tivoli/PDWeb/log/config_data__default-webseald-qrdsvt15.cn.ibm.com.log'
2009-12-09-21:10:19.953+08:00I
0x1327925A webseald ERROR idb database e:\am610\src\db\pddbapi.cpp 687 0x000009cc
HPDDB0602E Could not create backing database (C:/Program Files/Tivoli/PDWeb/db/webseald-default.db, 0x00000016).
2009-12-09-21:10:19.953+08:00I
0x1460100C webseald ERROR lib database e:\am610\src\db\pddbapi.cpp 689 0x000009cc
HPDDL0012E Database open failure.
this problem can be resolved after deleting C:/Program Files/Tivoli/PDWeb/db/webseald-default.db and restarting WebSEAL in services.
4. if you visit Quickr behind TAM with Firefox the first time, you might get a favicon.ico problem, you can refer to the following link for solution,
5. Users get password expires in TAM:
if you get the following page after logging to TAM, it means the password of this user has expired, the simplest way to resolve it is to use the same old password as new password, which means you can input the old password in the following 3 fields and click "Change Password"
the other way is to use user import command to import this user again.
Useful commands for TAM
Here are some commands commonly used for TAM WebSEAL administration, you can get more command from the following link: http://publib.boulder.ibm.com/tividd/td/ITAME/SC32-1354-00/en_US/HTML/am51_cmdref128.htm
server list
you will get all the servers in use
server task default-webseald-qrdsvt15.cn.ibm.com show /junction name
show all the task in this server, you can get all the details about this junction
object list
Lists any objects grouped under the specified protected object. Also lists all the extended attributes associated with the specified protected object.
object show
Shows all values associated with a protected object.
acl list
list all the acls you defined
acl find
Further Reading
Install TAM server http://www.lotus.com/ldd/lqwiki.nsf/dx/5.-enable-ibm-tivoli-access-manager-scenario-3
Information Centers http://www.ibm.com/developerworks/lotus/documentation/quickr
Lotus Quickr Technotes http://www.ibm.com/support/search.wss?rs=4089&tc=SS64R8&rank=8
IBM Tivoli Access Manager WebSEAL overview
http://publib.boulder.ibm.com/tividd/td/ITAME/SC32-1134-01/en_US/HTML/amweb41_admin04.htm
IBM Tivoli Access Manager - Administration Guide
http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic=/com.ibm.itame.doc_6.0/rev/am60 webseal_admin.htm
http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?topic=%2Fcom.ibm.itame.doc%2Fwelcome.htm