Configuring single sign-on (SSO) between IBM

WebSphere Portal and IBM Lotus Domino

Charles Price
IBM Software Group
Advisory Software Engineer, Domino Portal Integration
Atlanta, GA USA
June 2009
Copyright International Business Machines Corporation 2009. All rights reserved.
Editor's Note: This white paper is the second in a three-part series on SSO to be
published over the next month or so. See the previous paper, Understanding single signon (SSO) between IBM WebSphere Portal and IBM Lotus Domino.
Abstract: This paper is designed to help administrators who have a good grasp of how
SSO works and want an in-depth explanation of what steps are necessary to configure
SSO between IBM WebSphere Portal and IBM Lotus Domino. It also explains
how to verify that SSO is working correctly.

Table of Contents
1 Introduction....................................................................................................................... 2
2 Configure SSO between WebSphere Portal and Lotus Domino.......................................2
2.1 Export the LTPA key file from WebSphere Portal................................................... 2
2.2 Import the LTPA key file into Lotus Domino........................................................... 5
2.3 Configure the Domino server to support multi-server SSO.................................... 10
2.4 Disable token regeneration (version 6.1.x)............................................................. 12
2.5 Synchronize the directories..................................................................................... 13
3 Testing SSO between WebSphere Portal and Lotus Domino......................................... 21
4 Conclusion...................................................................................................................... 24
5 Resources........................................................................................................................ 24
6 About the author............................................................................................................. 24

1 Introduction
If you have read the developerWorks white paper, Understanding single sign-on (SSO)
between IBM WebSphere Portal and IBM Lotus Domino, you should have a
good understanding of how SSO works between WebSphere Portal and Lotus Domino.
Now you are ready to configure SSO in your environment. This paper walks you through
the steps to do that and how to test that SSO is working correctly.

2 Configure SSO between WebSphere Portal and Lotus

Domino
Configuring SSO between WebSphere Portal and Lotus Domino is a four-step process,
but before you can begin, security must be enabled on WebSphere Portal. (If it has not
been enabled, do that before continuing here.)
The basic steps are as follows:
1. Export the Lightweight Third-party Authentication (LTPA) key file from
WebSphere Portal.
2. Import the LTPA key file into Lotus Domino.
3. Configure the Domino server to support multi-server SSO.
4. (For version 6.1 only) Disable WebSphere Portal from regenerating the key files
every 90 days.
In the following sections we go into more detail on exactly what happens during these
steps.

2.1 Export the LTPA key file from WebSphere Portal

A common question we get here is, Why do I need to export the key file from
WebSphere Portal? If I already have a number of Domino servers with SSO configured
between them, can't I just use that key file and import it into WebSphere Portal?
The answer is no, there is no way to export an LTPA key file from the Domino server;
you can only import it. So for SSO to work with any WebSphere Application Serverbased product, you must export the key file from WebSphere Portal and import into
Lotus Domino.
To do this, follow these steps:

For WebSphere Portal 6.1.x

1. Open a browser to the WebSphere Application Server Admin console (for example,
https://dpi-dev.atlanta.ibm.com:10041/ibm/console in our environment), and select
Security > Secure administration, applications, and infrastructure.
2. Under Authentication, select Authentication Mechanisms, and scroll down to the
bottom of the page to the section, Cross-cell single sign-on (see figure 1).

Figure 1. Security Configuration page showing Export keys (for 6.1)

3. Enter a password and file path on the Portal server where the key file will be saved,
and then click the Export keys button.
NOTE: DO NOT click the Generate keys button near the top of the page. This
changes the current keys used by WebSphere Portal and will cause problems when
trying to get SSO to work.
If you clicked Generate keys, restart WebSphere Portal and server1, then come back
to this page and export the key file to ensure the key file you are exporting is the

same one WebSphere Portal will be using going forward.

4. You should see a message such as, The keys were successfully exported to the file
c:\ltpakey.file.
5. Click OK and click the Save link (see figure 2).
Figure 2. Save changes

At this point you are ready to import the key file into Lotus Domino; skip to the next
section for those details.

For WebSphere Portal 6.0.x

1. Open a browser to the WebSphere Application Server Admin console (for example,
https://dpi-portal-1.atlanta.ibm.com:10039/ibm/console in our environment), and
select Security > Global Security.
2. Under Authentication, open Authentication Mechanisms, and click LTPA.
3. Enter a file name in the Key file name field.
4. The current password was set when you enabled security. If you do not remember
the password, update it here as shown in figure 3.
5. Click the Export keys button.
NOTE: DO NOT click the Generate keys button. This changes the current keys used
by WebSphere Portal and will cause problems when trying to get SSO to work. If you
clicked Generate keys, restart WebSphere Portal and server1, then come back to
this page, and export the key file to ensure the key file you are exporting is the same
one WebSphere Portal will be using going forward.

Figure 3. Security Configuration page showing password Export keys (for 6.0)

6. You should see a message that the keys were exported successfully; click the Save
link to save this to the master configuration (see figure 4).
Figure 4. Save to master configuration

7. Click Save one more time to confirm the changes

8. Log out of the Administration console.
At this point you are ready to import the key file into Lotus Domino.

2.2 Import the LTPA key file into Lotus Domino

In this step we take the key file we just exported from WebSphere Portal and import it
into the Domino server, as follows:

1. Copy the LTPA key file (c:\ltpakey.file) from the Portal server to the Lotus Notes
Administration client machine.
NOTE: If you're moving the file from a UNIX to a Microsoft Windows machine
via ftp, make sure to use ASCII mode to transfer the file.
2. Open Domino Administrator and select File > Lotus Notes Application > Open.

3. In the Look in field, choose the primary Domino server; in the File name field, enter
names.nsf and click Open (see figure 5)
Figure 5. Open names.nsf

4. Under Configuration Servers, select All Server Documents (see figure 6).
Figure 6. Navigate to All Server Documents

5. Click Web Create Web SSO Configuration (see figure 7).

Figure 7. Create Web SSO Configuration

6. Fill in the fields in the Web SSO document for your environment (see figure 8):

Configuration Name: The name you want to call the document (LtpaToken is the
default).

Organization: This should always be left blank.

DNS Domain: The domain used to access WebSphere Portal and Lotus Quickr.
For more information refer to Section 2.2 in Understanding single sign-on (SSO)
between IBM WebSphere Portal and IBM Lotus Domino.

Expiration (minutes): We recommend setting this to the same value as

WebSphere Portal. (Refer to section 3.3.2 in Understanding single sign-on (SSO)
between IBM WebSphere Portal and IBM Lotus Domino.)

Map names in LTPA tokens: Set this to Enabled, if WebSphere Portal

authenticates with a non-Domino LDAP directory, such as IBM Directory Server,
Microsoft Active Directory, or Novell e-Directory.
(This is Disabled by default; used only for dual directories. For more information,
refer to Section 3.5 in Understanding single sign-on (SSO) between IBM
WebSphere Portal and IBM Lotus Domino.)

Domino Server Names: Set this to the server you want SSO to work with
WebSphere Portal (MAIL/IBM in our example).

Figure 8. Web SSO Configuration document

Now that you have filled out the SSO Configuration doc, you must import the LTPA key
file, as follows:
1. Select Keys > Import WebSphere LTPA Keys, from the menu (see figure 9).
Figure 9. Import WebSphere LTPA Keys

2. Enter the location to which you copied the LTPA key file (c:\ltpakey.file in our
environment).
Figure 10. Enter Import File Name dialog

3. Enter the password; you should see the message: Successfully imported
WebSphere LTPA keys. This imports the key file into Lotus Domino and adds the
WebSphere Information section to the Web SSO Configuration doc (see figure 11).
Figure 11. Key file imported into Lotus Domino

NOTE: The most important part for SSO here is the LDAP Realm
(ldap.atlanta.ibm.com:389, in our example). The rule of thumb is:

If the LDAP Realm field is populated with a value, it is most likely correct, and you
should leave it.

If the LDAP Realm is populated with null, then the realm is one of two values,
depending on the version of WebSphere Portal:
Version 6.0: WMMRealm
Version 6.1: defaultWIMFileBasedRealm
Refer to Section 3.3.1 in Understanding single sign-on (SSO) between IBM
WebSphere Portal and IBM Lotus Domino for more details.

4. Click the Save and Close button at the top of the screen, to save the document.
5. Now, go to the Web > Web Configurations view of the Domino directory; you should
see the Web SSO document you just created (see figure 12).
Figure 12. Newly created Web SSO doc

Once you save and close the document, you are ready to enable multi-server Single
Sign-on on the Domino server.

2.3 Configure the Domino server to support multi-server SSO

Now that the Web SSO document has been created, you need to tell the Domino server
to use this document. To do this, follow these steps:
1. Open Domino administrator and select File > Lotus Notes Application > Open.
2. In the Look in field, choose the primary Domino server; in the File name field, enter
names.nsf and click Open (recall figure 5).
3. Under Configuration > Servers, select All Server Documents (recall figure 6).

10

4. Double-click the server with which you want SSO to work (MAIL/IBM in our example).
5. In the Server document, select the Internet Protocols tab and then the Domino Web
Engine tab (see figure 13).
Figure 13. Domino Web Engine tab

6. Click the Edit Server button at the top of the page.

7. In the HTTP Sessions section (see figure 14), for the Session authentication field,
choose Multiple Server (SSO); for Web SSO Configuration, choose LtpaToken (Note
that this should be the name of the Web SSO document you created above.)
Figure 14. HTTP Sessions

11

8. Click the Save & Close button to save the document.

9. Restart the Domino server for the new settings to take effect.
SSO should now work between WebSphere Portal and Lotus Domino. If you are using
Portal version 6.1.x or later, it's strongly recommended you complete the next section. If
not, skip to Section 3 to test SSO in the environment.

2.4 Disable token regeneration (version 6.1.x)

By default, LTPA keys are regenerated on a schedule every 90 days, configurable to the
day of the week. When this key is regenerated, SSO from WebSphere Portal to the
Domino servers breaks, and the Admin must repeat the three steps above to fix the
issue. To avoid this, we recommend you disable the regeneration of the key files:
1. Open a browser to the WebSphere Application Server Admin console (for example,
https://dpi-dev.atlanta.ibm.com:10041/ibm/console in our environment) and select
Security > Secure administration, applications, and infrastructure.
2. Under Authentication, select Authentication Mechanisms.
3. Under the Key generation section, click the Key set groups link and select
NodeLTPAKeySetGroup (see figure 15).
Figure 15. Key set groups

12

4. Under Key generation, uncheck (deselect) the Automatically generate keys option
(see figure 16).
Figure 16.

5. Click OK, click Save, and log out of the WebSphere Administration Console.
The LTPA key file will no longer be regenerated every ninety days.

2.5 Synchronize the directories

NOTE: This subsection applies only to environments in which WebSphere Portal
authenticates with a non-Domino LDAP directory.
When WebSphere Portal authenticates with a non-Domino LDAP directory like IBM
Directory Server, Microsoft Active Directory, or Novell e-Directory, you must synchronize
the directories for SSO to work correctly. (Section 3.5 in Understanding single sign-on
(SSO) between IBM WebSphere Portal and IBM Lotus Domino explains in details
why this is necessary and how it works; the purpose of this article is simply to explain
how to synchronize the directories.)
In this example, WebSphere Portal authenticates with IBM Directory Server, Domino
authenticates with the Domino Directory, and the Distinguished Name for the same user
in each directory is completely different (see Table 1).
For SSO to work correctly between these two directories, Domino must somehow be
able to determine that uid=duser1,cn=users,dc=ibm,dc=com is the same user as
CN=Dom User1,O=ibm.

13

Table 1. User attributes

WebSphere Portal LDAP directory user

Domino Directory

DN: uid=duser1,cn=users,dc=ibm,dc=com
cn: Domino User1
uid: duser1
mail: duser1@acme.com

DN: CN=Dom User1,O=ibm

cn: Dom User1
uid: duser1
mail: duser1@acme.com

The way to do this is by synchronizing the two directories. There are two options for this.
You can either add:

the corporate DN to the Domino Person document, or

the Domino DN to an attribute in the corporate LDAP directory.

The decision as to which is the better choice comes down to which administrator you
want to be synching these directories:

If it's easier for the Domino Admin to update the Person documents, go with option 1,
add corporate DN to Domino person document.

If it's easier for the corporate LDAP Admin to update the person records, go with
option 2, add Domino DN to an attribute in corporate LDAP directory.

If you have no preference as to the directory you synchronize, then note that there is
one advantage with option 2: If users will authenticate with both WebSphere Portal and
Lotus Domino at times, using option 2 will allow them to always use the same name and
password to sign into both servers.
If you go with option 1, you would also need to ensure that the log-in attribute and
password are synchronized between the directories.

2.5.1 Update Domino Directory with corporate LDAP DN

With this option we will add the corporate LDAP DN to the User name field in the Person
document:
1. Open Domino administrator and select File > Lotus Notes Application > Open.
2. In the Look in field, choose the primary Domino server.
3. In the File name field, enter names.nsf, and click Open (recall figure 5).
4. Select People > By Organization, and double-click the user with which you want to
configure SSO (Dom User1/IBM in our example).
5. In the username or shortname field add the corporate LDAP DN. Make sure to add
the name in the Domino format, with a forward slash delimiter instead of a comma,
uid=duser1/cn=users/dc=ibm/dc=com, in our example (see figure 17).

14

Figure 17. LDAP DN in User name field

6. Now click the Administration tab.

7. Under Client Information (see figure 18), in the LTPA User Name field add the
corporate LDAP DN to the field, again making sure to add the name in the Domino
format, with a forward slash delimiter instead of a comma, uid=duser1/cn=users/
dc=ibm/dc=com in our example.
Figure 18. Add corporate LDAP DN

2.5.2 Update corporate LDAP directory with Domino DN

As discussed earlier, there is no need to update both directories, so if you have
completed section 2.5.1, this step is not necessary.
In this example, we extend the user's schema and add an attribute called notesdn. Then
we add the Domino DN of the user to this field. So the updated Person record looks like
this:

15

DN: uid=duser1,cn=users,dc=ibm,dc=com
cn: Domino User1
uid: duser1
mail: duser1@acme.com
notesdn: CN=Dom User1,O=ibm
Again, notice that the LDAP format of the name (comma separated) is used here.
Once the LDAP directory has been updated, you now must tell Lotus Domino how to
search this directory and what attribute contains the Domino DN of the user. To do this,
create a Directory Assistance database and an LDAP document, following these steps:
1. Open Domino administrator and select File > Application > New, and fill in the fields
as follows (see figure 19):
Server: Select the server you want to enable SSO with (MAIL/IBM in our example)
Title: The title you want for the database (Directory Assistance in our example)
File name: The file name you want to use on the server (da.nsf in our example)
2. Under the Specify Template for New Application section:
Server: Select the server you want to enable SSO with (MAIL/IBM in our example)
Template: Select Directory Assistance (8.5)
Also, enable the Show advanced templates option at the bottom of the window.

16

Figure 19. New Application dialog box

3. Click OK. The new database opens, and the information to connect to the corporate
LDAP directory is created.
4. In the Directory Assistance database, click the Add Directory Assistance button (see
figure 20).
Figure 20. Add Directory Assistance button

17

5. On the Basics tab (see figure 21), set fields as follows:

Domain type: LDAP
Domain name: This must be a unique name; the Domain name for our Domino
directory is IBM, so we cannot use IBM here.
Company Name: This need not be unique, so let's use IBM.
Search order: The order of the Directory Assistance document you want this
searched.
Group Authorization: Can be set to either Yes or No for SSO.
Enabled: Yes
Attribute to be used as name in an SSO token (map to Notes LTPA_UsrNm): $DN
Figure 21. Basics tab

6. On the Naming Contexts (Rules) tab (see figure 22), set the fields as follows:
All OrtUnit's: *
Enabled: Yes
Trusted for Credentials: Yes **This is the only one you need to change**

18

Figure 22. Naming Context (Rules) tab

7. On the LDAP tab (see figure 23), set fields as follows:

Hostname: Hostname of the corporate LDAP directory
Option Authentication Credential:
Username: The user to bind to the directory who can query and have returned
the attribute populated with the Domino DN.
Password: The password of bind user
Attribute to be used as Notes Distinguished Name: This is where you tell the Domino
directory where to find the Domino DN in the corporate LDAP (notesdn in our
example)
Type of search filter to use: Click the down arrow and chose your corporate LDAP
directory.
Figure 23. LDAP tab

19

8. Save and close the document

9. Close the Directory Assistance database
Now that the directory assistance database has been created, update the Server
document to tell it to use this database:
1. Open Domino administrator and select File > Lotus Notes Application > Open.
2. In the Look in field, choose the primary Domino server.
3. In the File name field, enter names.nsf, and click Open.
4. Under Configuration > Servers, select All Server Documents (recall figure 6).
5. Double-click on the server with which you want SSO to work (MAIL/IBM in our
example); click the Edit Server server button.
6. On the Basics tab, under Directory Information (see figure 24), set the Directory
assistance database name field to the file name you created earlier (da.nsf in our
example).

20

Figure 24. Server doc showing Directory Assistance database name field

7. Save and close the Server document.

3 Testing SSO between WebSphere Portal and Lotus

Domino
Now that SSO has been configured, we must verify that it's working. The following steps
are the best way to test SSO:
NOTE: In the testing and screenshots below, the fully qualified hostname of the servers
is always used in the browser. If the servername (mail, instead of mail.atlanta.ibm.com)
were used, SSO would never work. For more information on why that is, refer to
Sections 2.1, 2.2, and 3.2 of Understanding single sign-on (SSO) between IBM
WebSphere Portal and IBM Lotus Domino.
1. Open the browser to the Portal server and sign in as your test user (duser1 in our
example; see figure 25).

21

Figure 25. Portal 6.1 Welcome screen

2. Change the URL in the browser to a database in which default and anonymous
access are no access, and the user has access (a mail file is usually one of the best
options.) You should see the database as shown in figure 26.
Figure 26. dom user1 database

If instead you get a sign-in screen (see figure 27), then SSO did not work. (The
upcoming third article in this series will address how to troubleshoot and debug the
issue.)

22

Figure 27. Sign-in screen

In addition to testing SSO by signing into WebSphere Portal first, you should also test
the reverse:
1. Open a browser to your mail file and sign in (dom user1; recall figure 26).

2. Change the URL in the browser to the Portal server (http://dpi-dev.atlanta.ibm.com/

wps/myportal) as shown in figure 28.
NOTE: It is very important to include myportal on the URL; if you just use /portal,
you are accessing the anonymous section of WebSphere Portal, and the Portal
server will not look for or attempt to use the LTPAToken passed in via the browser.
Figure 28. Portal server URL

23

4 Conclusion
After having read the first paper in this series, you gained a good understanding of how
SSO works between WebSphere Portal and Lotus Domino. Now, you also know all the
detailed steps to get SSO working between the two, summed up as follows:
1.
2.
3.
4.

Export the key file from WebSphere

Import the key file into the Web SSO document in Domino.
Configure the Domino server for Multi-server SSO.
Synchronize the directories for non-Domino LDAP customers.

You should have little trouble setting up SSO between your two environments. If,
however, there is still an issue, the next paper in this series will walk you through
everything you need to do to troubleshoot, isolate, and resolve the problem.

5 Resources

developerWorks white paper, Understanding single sign-on (SSO) between IBM

WebSphere Portal and IBM Lotus Domino:

http://www.ibm.com/developerworks/websphere/zones/portal/proddoc/dw-w-ssoportal-domino/index.html

Knowledge Base document #1158269, Troubleshooting WebSphere Portal, Domino

Extended Products, and Domino SSO issues:
http://www.ibm.com/support/docview.wss?rs=899&uid=swg21158269

developerWorks Lotus Notes and Domino product page:

http://www.ibm.com/developerworks/lotus/products/notesdomino/

developerWorks WebSphere product page:

http://www.ibm.com/developerworks/websphere

Lotus Notes and Domino wiki:

http://www-10.lotus.com/ldd/dominowiki.nsf

WebSphere Portal family wiki:

http://www-10.lotus.com/ldd/portalwiki.nsf

developerWorks article, How to configure SSO with LTPA for IBM Lotus
Connections 2.0:
http://www.ibm.com/developerworks/lotus/library/connections-sso/

6 About the author

Charlie Price is an Advisory Software Engineer in IBM's Software Group. He has six
years of experience in technical support for IBM Lotus software, and two years in the
test organization, specializing in cross-product integration with Lotus, IBM, and other
third-party products.

24

He is an IBM Certified Associate System Administrator - Lotus Collaborative Solutions

(administering QuickPlace), a Principal Certified Lotus Professional for Domino system
administration, and an IBM Certified System Administrator for WebSphere Portal. He
holds a degree in Mathematics Education from the University of Georgia and taught high
school mathematics for three years before joining IBM. You can reach him at
charles_price@us.ibm.com.

Trademarks
developerWorks, Domino, IBM, Lotus, Notes, QuickPlace, Quickr, and WebSphere
are trademarks or registered trademarks of IBM Corporation in the United States, other
countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other
countries.

Microsoft and Windows are registered trademarks of Microsoft Corporation in the

United States, other countries, or both.

Other company, product, and service names may be trademarks or service marks of
others.

25