Skip to main content

Support & downloads  >  

Guide to configuring Single Sign-on (SSO)
 Technote (FAQ)
 
 
Question
How do you configure single sign-on (SSO) for a Lotus® Domino® server?
 
Answer
This document contains step-by-step instructions about how to configure Single Sign-on (SSO) for a Lotus Domino server. You can use it as a supplement to the product documentation.

How to configure Single Sign-on

Contents:

Overview of Authentication Options
  • Basic name-and-password authentication for Internet/intranet clients
  • Single server session-based name-and password authentication
  • Multi-server session-based name-and password authentication (Single Sign-on)

Checklist for Single Sign-on

Using Internet Sites to set up Single Sign-on
    Verify that your Location document is correct
    Enable the use of Internet Site documents
    Create Internet Site documents
    Create a Web SSO Configuration document
      1. Domino only
      2. Domino and WebSphere
    Enable SSO in the Internet Site document

Using the Web Server Configurations view to set up Single Sign-on
    Verify that your Location document is correct
    Create the Web SSO Configuration document
      1. Domino only
      2. Domino and WebSphere
    Enable SSO in the Server document

Verify the SSO configuration

Common problems in SSO configuration


Overview of Authentication Options

You can configuration authentication for Web clients in a number of ways. Below are the various ways you can set up name-and-password authentication, of which Single Sign-on (SSO) is one option.

Basic name-and-password authentication for Internet/intranet clients

Basic name-and password authentication uses a basic challenge/response protocol to authenticate users. Basic authentication is the default option. To use this option, you create a Person document for each user allowed to access a Web resource on a Domino server. When set up for this, Domino asks for a name and password only when an Internet/intranet client tries to access a protected resource on the server (namely, when an Anonymous user is not allowed access in the Access Control List of a resource).

When a user accesses the Web site, the user provides a name and password that is compared against the password stored in the Person document. In this scenario, the name and password of the user are sent in un-encrypted format to the server with each request. For more information about setting up this authentication option, refer to the Domino Administrator Help.

Single server session-based name-and-password authentication

Single server session-based authentication offers additional functionality and a more secure way to authenticate than the basic password authentication. In this scenario, a Web user provides a user name and password at login, and the server generates a browser cookie used for all subsequent authentication to that one server. This method allows you to customize the log-in screen, by using the Domino Web Server Configuration database (domcfg.nsf), and allows users to log out of a session without closing the browser. As the name implies, this authentication method applies to a single server only. Web users must log in again when switching to a different Web server.

Multi-server session-based name-and-password authentication (Single Sign-on)

Multi-server session-based authentication, also known as Single Sign-on (SSO), is an extension of the single server session-based name-and-password authentication. This option allows a Web user to log in once to a Domino or WebSphere server and then access any other Domino or WebSphere server in the same DNS domain without needing to authenticate again. The remainder of this paper discusses how to configure this Single Sign-on option.

Checklist for Single Sign-on
  • All servers participating in Single Sign-on must be at least Domino 5.0.5 or higher.
  • Your users' Web browsers must have cookies enabled because the authentication token that is generated by the server is transported to the browser in a cookie.
  • You should make a list of all the Domino servers that will be participating in Single Sign-on. You will need the DNS domain name (for example, .ibm.com) as well as the fully qualified host name of the servers hosting Web sites (for instance, example.ibm.com).
  • If you have WebSphere servers in your organization, make a list of the WebSphere servers that will be participating in the Single Sign-on. Consult WebSphere documentation for how to export the LTPA keys.
  • Determine what method you are using to set up Internet protocols for your Domino server. There are two methods you can use to configure Internet protocols and Web site settings:
    - Internet Site documents, a method new to Domino 6
    - Web Server Configurations view and the Server document, a method of managing Web sites introduced in Domino R5

    It is recommended that you use Internet Site documents to set up SSO because it offers more flexibility and ease in configuration. You may need to use the R5 method if there are any R5 servers or Domino extended products participating in the SSO environment.

    To determine or set the method, go to Server document, and examine the field "Load Internet configurations from the Server\Internet Sites documents" to see if it is enabled or disabled.

Using Internet Sites to set up Single Sign-on

Using Internet Sites to manage Internet protocols and Web sites is available for Domino 6 and Domino 7 servers, and was introduced in Domino 6. It is recommended that you use this method if all the servers in your environment are Domino 6 or later.

Verify that your Location document is correct

As part of setting up SSO, you create a Web SSO Configuration document. To successfully create this document, the Domino Administrator client's home server must be in the same domain as the participating Single Sign-on servers because the Web SSO Configuration document uses this server name to locate the Server document in the Domino Directory.
If the Location document is not correct, you see error messages indicating that one or more of the participating servers cannot be found.

Open your Location document, and go to the Servers tab. Make sure that the Home/mail server field lists a server in the Domain for which you intend to enable SSO.

Enable the use of Internet Site documents

Next you need to configure or verify that the use of Internet Site documents is enabled on the server.

In the Domino Administrator client, go to the Configuration tab.

Select Server -> All Server Documents. Select and open the document for the server for which you want to configure SSO.

Go to the Basics tab. Make sure that the field named "Load Internet configurations from the Server\Internet Sites documents" is Enabled.

Create Internet Site documents

The next step is to create an Internet Site document, specifically a Web Site document, for each server participating in SSO if it does not already exist. If the Internet Site documents for your sites already exist, then go to the next step to enable SSO for each site.

To create the Web Site document, in the Domino Administrator client, go to the Configuration tab. Select Web -> Internet Sites.

From the top menu, select Add Internet Site -> Web.

In the Web Site document, enter a Descriptive name for this site, an Organization name, and the fully qualified host name for the server.

Note: In Domino 6.x releases, the Organization field is case sensitive. Make a note of the Organization name you enter here because you must enter the exact same name in the Web SSO Configuration document that you will create.

Picture of an Internet Site - Web Site document


Repeat the above steps to create a Web site document for each server participating in SSO. If you have servers that are port mapped sharing a single IP address, then you only need to create one Internet Site document for that TCPIP address.

Create a Web SSO Configuration document

The Web SSO Configuration document is a domain-wide configuration document. This document, which should be replicated to all servers participating in the Single Sign-on domain, is encrypted for participating servers and contains a shared secret key used for authenticating user credentials. Once created, you will see the Web SSO Configuration document in your Internet Sites view.

To create the Web SSO Configuration document, in the Domino Administrator client, click Files, and open the Address Book (names.nsf). Select the Internet Sites view and click Create Web SSO Configuration.

(You can also go to the Configuration tab, select Web -> Internet Site, and then from the top menu select "Create Web SSO Configuration.")

Fill in the document, paying special attention to the following fields:
  • For the Configuration Name, use the default value of LtpaToken. (You can use other values in limited circumstances. Refer to the Domino Administrator Help for more information.)
  • Enter the same Organization Name as you specified in the Internet Site - Web Site document.
  • In the DNS Domain field, enter the DNS domain name. All servers enabled for Single Sign-on must belong to the same DNS domain.
  • In the Domino Server Names field, select all the servers participating in the SSO.
    Note: Group and wildcards are not allowed. Also list only the Domino servers, not WebSphere servers.

Picture of a Web SSO Configuration document


There are two ways to initialize the Web SSO Configuration document with the shared secret key.

1. Domino only

If there are no WebSphere servers participating in the Single Sign-On environment, you should select Keys -> Create Domino SSO Key.

Next, you see a dialog box with the message "Successfully created Domino SSO key," which indicates that the Domino SSO key is successfully created.

This document is encrypted for the creator of the document, the member of the Owners and Administrators fields in the Administration tab ,and the servers in the Domino Server Names field. You will see messages about the number of public keys encrypted in the status bar.



2. Domino and WebSphere

You can have one or more WebSphere servers participating in the Single Sign-On environment along with Domino servers. If needed, refer to WebSphere documentation for details on how to generate the LTPA keys.

In the Web SSO Configuration document, select Keys -> Import WebSphere LTPA Keys.

In the Enter Import File Name dialog box that appears, enter the path to the WebSphere LTPA file.

When prompted, enter the key file password. When completed, you will see a message box of "Successfully imported WebSphere LTPA keys."

Enable SSO in the Internet Site document

Next you must enable SSO in the Internet Site document.

Open the Internet Site - Web Site documents for your site. Select the Domino Web Engine tab.
    For the Session Authentication field, select Multiple Servers (SSO).
    For the Web SSO Configuration field, select LtpaToken, the name of the Web SSO Configuration document you created earlier.

Picture of Web Site document, Domino Web Engine tab


Click the Security tab. Make sure that Name & Password is enabled for TCP Authentication, and for SSL Authentication section if using SSL.

Picture of Web Site document, Security tab


Repeat the above steps for each server participating in SSO, and save and close all Internet Site documents.

Now replicate the Domino Directory to all the servers in the DNS domain, so the servers can access the Web SSO Configuration document as well as the Internet Site documents.

Finally start the HTTP task for each server using the console command "load http." If the HTTP task is already running, you can restart it with the console command "tell http restart."


Using the Web Server Configurations view to set up Single Sign-on

The Web Server Configuration view method of setting up Internet access is the style used for and introduced in Domino R5. It is recommended that you use this method only if you have one or more R5 servers in your environment or if using Domino extended products such as QuickPlace and Domino Document Manager that cannot be used with the Internet Sites configuration.

If you are using this configuration, the field named "Load Internet configurations from the Server\Internet Sites documents" on the Basics tab in the Server document is set to Disabled.

Verify that your Location document is correct

As part of setting up SSO, you create a Web SSO Configuration document. To successfully create this document, the Domino Administrator client's home server must be in the same domain as the participating Single Sign-on servers because the Web SSO Configuration document uses this server name to locate the Server document in the Domino Directory.
If the Location document is not correct, you see error messages indicating that one or more of the participating servers cannot be found.

Open your Location document, and go to the Servers tab. Make sure that the Home/mail server field lists a server in the Domain for which you intend to enable SSO.

Create the Web SSO Configuration document

The Web SSO Configuration document is a domain-wide configuration document that holds the keys needed for Single Sign-on.

To create this document, open the Domino Directory and go to the Servers view. Click Web -> Create Web SSO Configuration.

Fill in the document, paying special attention to the following fields:
  • In the DNS Domain field, enter the DNS domain name for which the token will be generated. The servers enabled for Single Sign-on must all belong to the same DNS domain.
  • For the Organization field, do not make an entry. The Organization field must be empty or blank when you use the Web Server Configurations view for SSO.
  • For Domino Server Names, select the servers that will be participating in Single Sign-on.

There are two ways to initialize the Web SSO Configuration document with the shared secret key.

1. Domino only

If all the servers participating in the Single Sign-on are Domino servers, then Select Keys -> Create Domino SSO Key.

Next, you see a dialog box with the message "Successfully created Domino SSO key," which indicates that the Domino SSO key is successfully created.

2. Domino and WebSphere

If you have one or more WebSphere servers participating in the Single Sign-On environment, refer to WebSphere documentation for details on how to generate the LTPA keys.

In the Web SSO Configuration document, select Keys -> Import WebSphere LTPA Keys.

In the Enter Import File Name dialog box that appears, enter the path to the WebSphere LTPA file.

When prompted, enter the key file password. Click OK when you see the Success message box: "Successfully imported WebSphere LTPA keys."

Picture of Web SSO Configuration document


Enable SSO in the Server document

Open the Server document. Go to the Port tab -> Internet Ports tab -> Web tab. Set Name & password authentication to Yes to enable the HTTP port.

Picture of Server Document - Web tab


Next, go to the Internet Protocols tab -> Domino Web Engine tab. Select Multi-server in the Session authentication field.

Repeat the above steps for each server participating in Single Sign-on. Save and close all Server documents.

Now replicate the Domino Directory to all the servers in the DNS domain, so the servers can access the Web SSO Configuration document as well as the Server documents.

Finally start the HTTP task for each server using the console command "load http." If the HTTP task is already running, you can restart it with the console command "tell http restart."


Verify the SSO configuration

To verify if Single Sign-on is configured correctly, launch a Web browser and enter the Web address of your server, using the full DNS name of the server (for instance, http://example.ibm.com). Enter your user name and password to log into this server. Then change the URL address to another server in the same domain. If SSO is set up correctly, you should not be prompted to enter your name and password again when accessing a protected resource.

Common problems in SSO configuration
For descriptions of common problems when setting up or using Single Sign-on, refer to the following documents:
  • Common questions and problems with Single Sign-on (SSO) (#1216978)
  • Hints and Tips for Troubleshooting Single Sign-on and Authentication Issues with Domino and WebSphere (#7003063)
 
Related information
Demonstration of configuring SSO using Internet sites
 
 
 

Copyright and trademark information
IBM, the IBM logo and ibm.com are trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.
Rate this page
Please take a moment to complete this form to help us better serve you.
This material provides me with the information I need.




This material is clear and easy to understand.




Did the information help you to achieve your goal?
What updates, improvements, or related information would you like to see in this document?
Your response will be used to improve our document content. Requests for assistance, if applicable, should be submitted through your normal support channel as we cannot respond from this site.
Input the verification number to submit feedback:
Document information
 Product categories:
 Software
 Messaging Applications
 Advanced Messaging
 Lotus Domino
 Lotus Domino Server
 Operating system(s):
  AIX, HP-UX, Linux, Solaris, Windows, i5/OS, z/OS
 Software version:
  6.0, 6.5, 7.0
 Software edition:
  All Editions
 Reference #:
  1217754
 IBM Group:
 Software Group
 Modified date:
 2005-09-29

Translate My Page
 
 

Rate this page

Help us improve this page. Your response will be used to improve our document content. Requests for assistance, if applicable, should be submitted through your normal support channel as we cannot respond from this site.