You are on page 1of 25

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

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).

2

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

and select Security > Global Security.atlanta.ibm. Open a browser to the WebSphere Application Server Admin console (for example. skip to the next section for those details. You should see a message such as. Under Authentication. open Authentication Mechanisms. If you do not remember the password. restart WebSphere Portal and server1. and export the key file to ensure the key file you are exporting is the same one WebSphere Portal will be using going forward. The current password was set when you enabled security. If you clicked Generate keys. Save changes At this point you are ready to import the key file into Lotus Domino. update it here as shown in figure 3. 4. Click the Export keys button. For WebSphere Portal 6. 4 .0. 3. Click OK and click the Save link (see figure 2). 4. “The keys were successfully exported to the file c:\ltpakey.” 5. 2.x 1.com:10039/ibm/console in our environment). This changes the current keys used by WebSphere Portal and will cause problems when trying to get SSO to work. Enter a file name in the Key file name field.same one WebSphere Portal will be using going forward. then come back to this page. Figure 2.file. and click LTPA. https://dpi-portal-1. 5. NOTE: DO NOT click the Generate keys button.

Figure 3. Click Save one more time to confirm the changes 8. At this point you are ready to import the key file into Lotus Domino. You should see a message that the keys were exported successfully. 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. Log out of the Administration console. Figure 4. Security Configuration page showing password Export keys (for 6. Save to master configuration 7. click the Save link to save this to the master configuration (see figure 4).0) 6. as follows: 5 .

nsf 4. Under Configuration – Servers. Copy the LTPA key file (c:\ltpakey.nsf” and click Open (see figure 5) Figure 5. Navigate to All Server Documents 6 . In the Look in field. in the File name field. choose the primary Domino server. enter “names. 2. Open names. Open Domino Administrator and select File > Lotus Notes Application > Open. Figure 6. 3.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.1. make sure to use ASCII mode to transfer the file. select All Server Documents (see figure 6).

” • Expiration (minutes): We recommend setting this to the same value as WebSphere Portal. (This is Disabled by default.2 in “Understanding single sign-on (SSO) between IBM® WebSphere® Portal and IBM Lotus® Domino®.5. or Novell e-Directory.2 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). Click Web – Create Web SSO Configuration (see figure 7). Microsoft Active Directory. 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). For more information refer to Section 2. • DNS Domain: The domain used to access WebSphere Portal and Lotus Quickr™. used only for dual directories.5 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. Figure 7. such as IBM Directory Server. For more information. 7 . • Organization: This should always be left blank. (Refer to section 3.3. Create Web SSO Configuration 6. refer to Section 3.

Enter the location to which you copied the LTPA key file (c:\ltpakey. Select Keys > Import WebSphere LTPA Keys. you must import the LTPA key file.Figure 8.file in our environment). Web SSO Configuration document Now that you have filled out the SSO Configuration doc. as follows: 1. Import WebSphere LTPA Keys 2. Enter Import File Name dialog 8 . Figure 10. from the menu (see figure 9). Figure 9.

1: defaultWIMFileBasedRealm Refer to Section 3. Key file imported into Lotus Domino NOTE: The most important part for SSO here is the LDAP Realm (ldap. Enter the password.3.” This imports the key file into Lotus Domino and adds the WebSphere Information section to the Web SSO Configuration doc (see figure 11). it is most likely correct. and you should leave it. Figure 11. The rule of thumb is: • If the LDAP Realm field is populated with a value. 9 .1 in “Understanding single sign-on (SSO) between IBM® WebSphere® Portal and IBM Lotus® Domino®” for more details. in our example).ibm.com:389. you should see the message: “Successfully imported WebSphere LTPA keys. • If the LDAP Realm is populated with null.atlanta.3. then the realm is one of two values. depending on the version of WebSphere Portal: Version 6.0: WMMRealm Version 6.

5. Now. 2. 2. you need to tell the Domino server to use this document. choose the primary Domino server. Click the Save and Close button at the top of the screen. you are ready to enable multi-server Single Sign-on on the Domino server. Open Domino administrator and select File > Lotus Notes Application > Open. go to the Web > Web Configurations view of the Domino directory. Under Configuration > Servers.nsf” and click Open (recall figure 5). To do this. to save the document. Figure 12. Newly created Web SSO doc Once you save and close the document. In the Look in field. 3.3 Configure the Domino server to support multi-server SSO Now that the Web SSO document has been created.4. you should see the Web SSO document you just created (see figure 12). in the File name field. select All Server Documents (recall figure 6). follow these steps: 1. enter “names. 10 .

for the Session authentication field.) Figure 14. Figure 13. In the HTTP Sessions section (see figure 14).4. choose Multiple Server (SSO). choose LtpaToken (Note that this should be the name of the Web SSO document you created above. select the Internet Protocols tab and then the Domino Web Engine tab (see figure 13). for Web SSO Configuration. Domino Web Engine tab 6. Double-click the server with which you want SSO to work (MAIL/IBM in our example). In the Server document. Click the Edit Server button at the top of the page. HTTP Sessions 11 . 5. 7.

1. 2. Restart the Domino server for the new settings to take effect. Click the Save & Close button to save the document. 2. If not.x) By default. click the Key set groups link and select NodeLTPAKeySetGroup (see figure 15). Key set groups 12 . Under the Key generation section. To avoid this.1. 9.x or later. Figure 15. applications. SSO should now work between WebSphere Portal and Lotus Domino. and the Admin must repeat the three steps above to fix the issue.com:10041/ibm/console in our environment) and select Security > Secure administration. select Authentication Mechanisms. When this key is regenerated. it's strongly recommended you complete the next section. https://dpi-dev. LTPA keys are regenerated on a schedule every 90 days. skip to Section 3 to test SSO in the environment. we recommend you disable the regeneration of the key files: 1. configurable to the day of the week. If you are using Portal version 6. SSO from WebSphere Portal to the Domino servers breaks. Open a browser to the WebSphere Application Server Admin console (for example. Under Authentication.4 Disable token regeneration (version 6. and infrastructure.atlanta.8.ibm. 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. 13 . When WebSphere Portal authenticates with a non-Domino LDAP directory like IBM Directory Server. Domino must somehow be able to determine that uid=duser1.) In this example. Domino authenticates with the Domino Directory. or Novell e-Directory.cn=users. 2. Figure 16.dc=ibm. and log out of the WebSphere Administration Console.5 Synchronize the directories NOTE: This subsection applies only to environments in which WebSphere Portal authenticates with a non-Domino LDAP directory. and the Distinguished Name for the same user in each directory is completely different (see Table 1). WebSphere Portal authenticates with IBM Directory Server.dc=com is the same user as CN=Dom User1.O=ibm. Under Key generation. Click OK. uncheck (deselect) the “Automatically generate keys” option (see figure 16). click Save. The LTPA key file will no longer be regenerated every ninety days. Microsoft Active Directory. you must synchronize the directories for SSO to work correctly.4. (Section 3. For SSO to work correctly between these two directories. 5. the purpose of this article is simply to explain how to synchronize the directories.

Table 1. Open Domino administrator and select File > Lotus Notes Application > Open. If you have no preference as to the directory you synchronize. You can either add: • • the corporate DN to the Domino Person document.O=ibm cn: Dom User1 uid: duser1 mail: duser1@acme. In the Look in field. go with option 2. using option 2 will allow them to always use the same name and password to sign into both servers.dc=com cn: Domino User1 uid: duser1 mail: duser1@acme. add Domino DN to an attribute in corporate LDAP directory. go with option 1. There are two options for this. In the username or shortname field add the corporate LDAP DN.com The way to do this is by synchronizing the two directories. 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. you would also need to ensure that the log-in attribute and password are synchronized between the directories. enter “names. in our example (see figure 17). 5.dc=ibm. then note that there is one advantage with option 2: If users will authenticate with both WebSphere Portal and Lotus Domino at times.com DN: CN=Dom User1. add corporate DN to Domino person document. or the Domino DN to an attribute in the corporate LDAP directory.nsf”. 4.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. 3. If you go with option 1. and click Open (recall figure 5).cn=users. choose the primary Domino server. Make sure to add the name in the Domino format. 2. User attributes WebSphere Portal LDAP directory user Domino Directory DN: uid=duser1. Select People > By Organization. uid=duser1/cn=users/dc=ibm/dc=com. 14 . with a forward slash delimiter instead of a comma.5. In the File name field. • If it's easier for the corporate LDAP Admin to update the person records. 2. and double-click the user with which you want to configure SSO (Dom User1/IBM in our example).

with a forward slash delimiter instead of a comma. Then we add the Domino DN of the user to this field. we extend the user's schema and add an attribute called notesdn. so if you have completed section 2. LDAP DN in User name field 6. Now click the Administration tab.Figure 17. uid=duser1/cn=users/ dc=ibm/dc=com in our example.5. again making sure to add the name in the Domino format. there is no need to update both directories. Add corporate LDAP DN 2.5. In this example. Figure 18. this step is not necessary.1. 7. in the LTPA User Name field add the corporate LDAP DN to the field. Under Client Information (see figure 18).2 Update corporate LDAP directory with Domino DN As discussed earlier. So the updated Person record looks like this: 15 .

enable the “Show advanced templates” option at the bottom of the window.nsf in our example) 2.DN: uid=duser1. Open Domino administrator and select File > Application > New. To do this. you now must tell Lotus Domino how to search this directory and what attribute contains the Domino DN of the user. notice that the LDAP format of the name (comma separated) is used here. 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.cn=users. 16 . create a Directory Assistance database and an LDAP document.dc=com cn: Domino User1 uid: duser1 mail: duser1@acme.dc=ibm. Once the LDAP directory has been updated. following these steps: 1.com notesdn: CN=Dom User1.5) Also. 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.O=ibm Again.

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

so we cannot use IBM here. Basics tab 6. set fields as follows: Domain type: LDAP Domain name: This must be a unique name. Enabled: Yes Attribute to be used as name in an SSO token (map to Notes LTPA_UsrNm): $DN Figure 21. Group Authorization: Can be set to either Yes or No for SSO. Company Name: This need not be unique.5. the Domain name for our Domino directory is IBM. so let's use IBM. set the fields as follows: All OrtUnit's: * Enabled: Yes Trusted for Credentials: Yes **This is the only one you need to change** 18 . On the Naming Contexts (Rules) tab (see figure 22). Search order: The order of the Directory Assistance document you want this searched. On the Basics tab (see figure 21).

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. Figure 23. On the LDAP tab (see figure 23).Figure 22. 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. LDAP tab 19 . Naming Context (Rules) tab 7.

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

Save and close the Server document. 21 . The following steps are the best way to test SSO: NOTE: In the testing and screenshots below. Open the browser to the Portal server and sign in as your test user (duser1 in our example.1.ibm. instead of mail. the fully qualified hostname of the servers is always used in the browser. we must verify that it's working. Server doc showing Directory Assistance database name field 7. see figure 25). and 3. refer to Sections 2. For more information on why that is.Figure 24.2. 2.atlanta.2 of “Understanding single sign-on (SSO) between IBM WebSphere Portal and IBM Lotus Domino.com) were used. 3 Testing SSO between WebSphere Portal and Lotus Domino Now that SSO has been configured. SSO would never work. If the servername (mail.” 1.

1 Welcome screen 2.Figure 25. dom user1 database If instead you get a sign-in screen (see figure 27). Change the URL in the browser to a database in which default and anonymous access are no access. Figure 26. (The upcoming third article in this series will address how to troubleshoot and debug the issue.) You should see the database as shown in figure 26. then SSO did not work.) 22 . and the user has access (a mail file is usually one of the best options. Portal 6.

Change the URL in the browser to the Portal server (http://dpi-dev. and the Portal server will not look for or attempt to use the LTPAToken passed in via the browser. Open a browser to your mail file and sign in (dom user1. NOTE: It is very important to include myportal on the URL. Sign-in screen In addition to testing SSO by signing into WebSphere Portal first.ibm. recall figure 26).atlanta.com/ wps/myportal) as shown in figure 28. Portal server URL 23 . you are accessing the anonymous section of WebSphere Portal.Figure 27. 2. you should also test the reverse: 1. if you just use /portal. Figure 28.

com/ldd/dominowiki.nsf • developerWorks article.html • Knowledge Base document #1158269. you gained a good understanding of how SSO works between WebSphere Portal and Lotus Domino. and resolve the problem.com/developerworks/lotus/products/notesdomino/ • developerWorks WebSphere product page: http://www. “Troubleshooting WebSphere Portal.com/developerworks/lotus/library/connections-sso/ 6 About the author Charlie Price is an Advisory Software Engineer in IBM's Software Group. 24 . 5 Resources • developerWorks white paper. there is still an issue.com/developerworks/websphere • Lotus Notes and Domino wiki: http://www-10. isolate.ibm. specializing in cross-product integration with Lotus.0”: http://www.4 Conclusion After having read the first paper in this series. “How to configure SSO with LTPA for IBM Lotus Connections 2.wss?rs=899&uid=swg21158269 • developerWorks Lotus Notes and Domino product page: http://www. the next paper in this series will walk you through everything you need to do to troubleshoot. and two years in the test organization.com/support/docview. 2.ibm. If.lotus. you also know all the detailed steps to get SSO working between the two. Configure the Domino server for Multi-server SSO. You should have little trouble setting up SSO between your two environments.com/developerworks/websphere/zones/portal/proddoc/dw-w-ssoportal-domino/index. however. Synchronize the directories for non-Domino LDAP customers. He has six years of experience in technical support for IBM Lotus software.ibm. 3. Domino Extended Products.ibm. Understanding single sign-on (SSO) between IBM WebSphere Portal and IBM Lotus Domino: http://www.nsf • WebSphere Portal family wiki: http://www-10. and Domino SSO issues”: http://www. Export the key file from WebSphere Import the key file into the Web SSO document in Domino. and other third-party products. Now. IBM. 4. summed up as follows: 1.ibm.com/ldd/portalwiki.lotus.

and service names may be trademarks or service marks of others. IBM.com. • Other company. a Principal Certified Lotus Professional for Domino system administration.ibm. and WebSphere are trademarks or registered trademarks of IBM Corporation in the United States. or both. • Microsoft and Windows are registered trademarks of Microsoft Corporation in the United States. QuickPlace. • UNIX is a registered trademark of The Open Group in the United States and other countries.Lotus Collaborative Solutions (administering QuickPlace®). product. other countries. 25 . other countries. You can reach him at charles_price@us. He holds a degree in Mathematics Education from the University of Georgia and taught high school mathematics for three years before joining IBM. Domino.He is an IBM Certified Associate System Administrator . Lotus. or both. Notes. Quickr. Trademarks • developerWorks. and an IBM Certified System Administrator for WebSphere Portal.