| We now present material concerning SSO and the WebSphere Portal Server (WPS). The purpose of this section is to discuss the issues related to using Lotus Domino and Lotus Collaborative products within the WebSphere Portal environment. It will discuss several scenarios related to having the Lotus Collaborative products work cohesively within the WebSphere Portal framework as well as the configuration of Domino Directory Assistance in this environment. The focus here is on using the native facilities in WebSphere Portal and Domino to provide an SSO experience. This section is targeted at Domino and WebSphere Portal administrators or IT architects who will integrate WebSphere Portal into an existing Domino environment using the native SSO capabilities of these products. We do not discuss implementing SSO with other products such as Tivoli Access Manager. As it relates to WebSphere Portal, SSO provides the ability to log into the WebSphere Portal Server and provide access with those user credentials to the Domino environment, such as Domino, Lotus Instant Messaging (IM), QuickPlace, and other Domino-based tools. Without an SSO relationship between WebSphere Portal and the Domino environment, users would need to log in to the Domino server each time they accessed a portlet containing information from a Domino-based application or service. Additionally, there are WebSphere Portal API's and services, such as People Awareness, that do not provide a facility for login. Even through these services do not provide distinct login facilities, they do require authentication through SSO in order to operate . WebSphere Portal provides a Credentials Vault capability. The Credentials Vault passes the username and password to the back-end application through the HTTP Basic Authentication Header. For the Domino server to accept credentials passed through this header, the server must be configured for Single-Server SSO mode, since, in Multi-Server mode, the Domino server will only accept credentials passed through the LTPA mechanism. With the Credentials Vault approach, the user authenticates once, and WPS forms a set of credentials for that user. The credentials are then stored in an encrypted database table and passed to the back-end application each time the user accesses a portlet requiring authentication. For details on configuring the Credentials Vault, see the WebSphere Portal InfoCenter. The option that most organizations work toward is to provide an automatic method of using the current credentials from WebSphere Portal to authenticate with back-end applications. How Does It Work? As we have discussed before, SSO function is based on the ability to share user authentication credentials between the application servers. For WebSphere and Lotus Domino, this credential sharing is done through a mechanism called Lightweight Third Party Authentication (LTPA). Both WebSphere (and thus WebSphere Portal and any other WAS-based products) and Domino use LTPA. The LTPA mechanism is based on the use of an HTTP cookie. An HTTP cookie is simply a set of data generated by a server and given to a browser to return on subsequent requests to URLs within the same Internet (DNS) domain. For LTPA, an encrypted session cookie is set in the user's browser and contains information that a WebSphere or Domino application server can decrypt and use to determine that the user is authenticated within the DNS domain that the cookie covers. We note that even without using the LTPA mechanism it is still possible to provide SSO behavior from WebSphere Portal. This is because there are two different methods that are used to authenticate the user into the Domino environment from WebSphere Portal. To understand how these methods work it is important to understand the points of integration from WebSphere Portal into Domino. WebSphere Portal to Domino Server Portlets integrate WebSphere Portal and backend applications. Portlets act as a sort of proxy when the user requests information from an external application, and that information is displayed in the WebSphere Portal page by the portlet. The Notes mail portlets demonstrate this behavior. The WebSphere Portal makes the request for data to the Domino server in the user's name . WebSphere Portal requests information from the Domino Server using the current user's credentials, which are collected from the session information. The portlet then formats the request and sends it to the Domino server. When the data is returned, it is formatted and integrated into the WebSphere Portal page and sent to the user's browser for viewing. When you log into the WebSphere Portal, you use an LDAP attribute that is typically a unique abbreviation of the user's name, employee serial number, or some other unique identifier. After the WebSphere Portal receives validation of the user name and password or existing LTPA token from the LDAP server, it gathers other information that includes the full Distinguished Name (DN) of the user. This information is then cached on the WebSphere Portal until the user logs off of the server or his session expires . Once this information is gathered, the portlet builds an HTTP, IIOP, or LDAP request and sends it to the Domino server. When the Domino server receives the request, it gets the user credentials and uses the Domino authentication and authorization facilities to see if the user is able to obtain the information. If authentication and authorization are granted, the information is retrieved and handed back to WebSphere Portal in XML format. If the user does not have authorization to the requested information, an error is returned to WebSphere Portal. There is another special case that is used by many of the Domino portlets. When in the configuration mode of the Domino portlets, the list of available databases is retrieved via the DIIOP interface of the Domino server. The only difference between IIOP and HTTP connections is the protocol used to talk to the Domino server; the LTPA information that is sent to the Domino server is the same as with an HTTP request. For this level of SSO to work, it is necessary for the DN and associated password to match between Domino and WebSphere Portal. This is a side effect of the level of SSO provided in WebSphere Portal to Domino server integration. The user's WebSphere Portal username and password are being passed along. Browser to Domino Server The second set of transactions involving SSO occurs between the user's browser and the Domino server. These transactions occur when the user opens a Lotus Notes document from the WebSphere Portal interface, or when any Domino application is opened in an iFrame portlet. If you take a look at the links in the Notes mail portlet or Notes view portlet, you will notice that the URLs point directly to the Domino server and bypass WebSphere Portal. Since the WebSphere Portal is not involved in the transactions, the user's identity is passed via the LTPA cookie that was created when the user authenticated to the WebSphere Portal. In other words, the standard LTPA mechanism is used for SSO between the portlet and Domino. Recall that the LTPA cookie contains the user's DN that was retrieved from the LDAP directory at login. The encrypted LTPA cookie information is passed along with the HTTP request to the Domino server. For the LTPA SSO to work, the LTPA cookie that is created by WebSphere must have been generated with an encryption key that is valid on the Domino server. As discussed in previous sections of this chapter, the LTPA key can be exported from WAS via the Administrative application and imported into Domino, providing a common key between the two environments. While Domino servers can consume the key created by WebSphere, Domino does not have the capability to export its own LTPA keys for use by WebSphere. Thus if LTPA were being used for other Domino-based applications such as Lotus IM or QuickPlace, a new set of LTPA keys generated by WPS must be imported into Domino in order for these applications to be used under WPS with SSO. Options for User Directory Sharing The following sections discuss the options for establishing a shared user directory between WPS and Domino. Recall that a shared user directory or registry is one of the requirements for providing SSO. These options reflect the most common environments found at customer sites. If you have an existing environment, you can focus on the section that most closely matches your environment. If you are creating a new environment, you can read each section and select the scenario that best fits your requirements. The scenarios fall into two categories: One Directory Serving Both WPS and Domino This scenario represents environments where a single LDAP directory is in place for the WebSphere Portal environment. If Domino exists in the environment, then the Domino Server provides the LDAP services, since it is one of the supported LDAP servers. If Domino will only be used for the support of QuickPlace and Lotus IM (which are Domino-based applications) within WebSphere Portal, it can be configured to use a non-Domino LDAP directory. WebSphere Portal must be configured to authenticate users against the LDAP directory. Recall that WAS servers (hence WPS servers) can only be configured to authenticate against a single LDAP directory. It is possible to use the Domino directory as the LDAP directory for an entire enterprise. The Domino server provides support for LDAP access to its directory and thus can be used for authentication from WebSphere Portal and other applications. If Domino will be used as the enterprise LDAP, the environment is considered a single directory environment. Separate Domino and WPS Directories In these scenarios, typical of environments that have existing Domino infrastructures , there are separate directories for Domino and WebSphere Portal. Typically, the Domino directory contains information on each of the Domino users, while the LDAP directory contains a super-set of this population. The LDAP directory must contain a user record for every user that will access WebSphere Portal. In the case where a given user is also a Domino user, there is certain information that must be reconciled between the two records. This is typically done either manually or with tools such as IBM Directory Integrator (IDI). We will discuss how to manually reconcile the LDAP and Domino directory entries later in this chapter. For this approach to work, the LTPA mechanism must be established between the WebSphere Portal and Domino environments. Configuring WPS for LTPA is similar to what is required for a standard WAS server. See the earlier sections in this chapter and information found in the Portal InfoCenter and WebSphere Portal Readme file for details. Using a Domino Directory WebSphere Portal can be configured to use the Domino directory for authentication. This is the simplest environment since the user credentials and passwords are derived from the same source and thus are the same when accessed either via LDAP or from within Domino. IBM recommends that you use this directory configuration if you will make use of the Lotus Collaborative Components (e.g., the Notes mail, Notes view portlets). Apart from configuring Domino to provide LDAP access to the Domino directory, you will have to ensure that the directory includes the necessary groups and users for WPS use and that it is configured to allow anonymous access to certain fields in the Person and Server documents. For Domino 6.x versions, the configuration will also include adding a new attribute to the Domino LDAP schema database. Consult the current WebSphere Portal InfoCenter and Readme file for more information on configuring Domino directory for WPS use. Lotus IM and QuickPlace servers can be configured to use the Domino Directory either natively or via LDAP. Using a Non-Domino Directory WebSphere Portal supports IBM Directory Server, Microsoft Active Directory, iPlanet, and Novell eDirectory. Because LDAP is used for directory access, other directory software, such as OpenLDAP, may be used as well (although not officially supported). In this scenario, Domino must be configured to use the separate LDAP directory for at least user authentication. In the same way as for WAS directory sharing, this can be done via the Domino Directory Assistance feature. In order for mail to route inside of the Domino environment there must be directory records containing mail information such as mail file and mail server for each user. This e-mail related information can be specified in a Person document in the Domino directory or in entries using an appropriate schema in an LDAP directory. Domino and Directory Assistance The Domino server has a mechanism for linking to an external LDAP directory, called Directory Assistance (DA). This mechanism allows the Domino server to search one or more LDAP directories after searching the Domino directory for user authentication. DA is enabled by creating a Directory Assistance database from the provided template, entering the name of the database in the Server document, and then filling out a document in the DA database. Group and user management can be done entirely from the LDAP directory. References to users' names in Domino database ACLs, group membership, and other contexts can be specified as the user's LDAP DN. The only difference is that the commas used in the LDAP DN must be replaced with the "/" character when entered in Domino. For example, "cn=Elizabeth Somebody,ou=users,o=YourCo," must be entered as "cn=Elizabeth Somebody/ou=users/o=yourco.com." Both the QuickPlace and Lotus IM environments should be configured to authenticate against the same directory as the WebSphere Portal. With QuickPlace, the LDAP directory is accessed directly, without the need for Directory Assistance. Early versions of Lotus IM relied on Directory Assistance to get information from LDAP, and it was recommended that Lotus IM should be configured to use the native Domino directory. However, the most recent version of Lotus IM can obtain user information directly from an LDAP directory. The use of Directory Assistance works in environments where the same users will not be listed in both the LDAP and Domino directories. If Domino is only being implemented to support QuickPlace and Lotus IM, this type of configuration can be used. In more complex environments with existing Domino infrastructures, where more Domino function will be used, it is necessary to configure multiple directories. The Multiple Identities Problem Although it is the natural choice for customers with existing directory infrastructures, the scenario in which separate directories are used for WebSphere Portal and Domino leads to a situation we refer to as the Multiple Identities problem. This problem often surfaces when WPS is built on top of an existing Domino installation and has caused consternation among the early adopters of WPS and Lotus collaboration components. Let's look at the nature of this problem more closely in order to understand how to configure the various parts to resolve the associated issues. We will begin our discussion of the Multiple Identities problem by defining an example environment that parallels what is found in a typical environment. Our example company is called YourCo. YourCo has a master LDAP directory with users existing in branches for each city under the OU for users. For our example employee, Elizabeth Somebody, we have the following information in her LDAP directory entry, which we refer to as her LDAP identity. Table 12-4. Example LDAP Directory Entry | Field | Value | | Dn | Elizabeth Somebody,ou=Boston,ou=users,dc=yourco,dc=com | | Uid | esomebody |
In the existing Domino environment, Elizabeth's Person document contains the following values, which we will refer to as her Domino identity. Table 12-5. Example Domino Directory Entry (Person Document) | Field | Value | | First Name | Elizabeth | | Last Name | Somebody | | User Name | Elizabeth Somebody/Boston/YourCo | | Elizabeth Somebody | Short Name Somebody |
Let's say Elizabeth uses Lotus IM within a portal. Elizabeth logs into the WebSphere Portal using her LDAP uid, esomebody. As part of the authentication process, the WAS retrieves her full DN from the LDAP directory and uses it to build an LTPA cookie. When she accesses a WebSphere Portal page as an authenticated user, the Lotus Collaborative Component (LCC) of the WebSphere Portal collects her user information (common name, LDAP uid, and DN) from WebSphere Portal. LCC then attempts to initiate a Lotus IM Links connection with the Lotus IM server. In establishing this link, the common name is supplied to Lotus IM to initialize and provide people awareness for Elizabeth. When Elizabeth accesses a WebSphere Portal page that contains a Notes portlet, her DN is passed to the Domino server over HTTP. The Domino server then searches the Domino Directory for the DN, where it will not be found (at this point, the LTPA cookie is not used). The seemingly obvious solution is to enable Directory Assistance on the Domino to include the LDAP server in the authentication path . When this is done, the search for the DN will include the LDAP directory, where a match will be found and the user authenticated. The problem is that Elizabeth is authenticated as "cn=Elizabeth Somebody,ou=Boston,ou=users,dc=yourco, dc=com," and Domino does not know that this is the same user as "Elizabeth Somebody/Boston/YourCo." Everything that Elizabeth does in the Domino environment will be done as her LDAP identity, not her Domino identity. For example, when Elizabeth sends mail, the From field will contain her LDAP DN. She will be able to address and send mail, but if a recipient replies to the mail they will receive a "name not found in directory" error because there is no Domino Person document with the exact LDAP DN. Furthermore, when Elizabeth creates documents in Domino databases, the author metadata will contain her LDAP DN. If a view is sorted on the Authors field, documents she creates through WebSphere Portal will sort in a different location than documents created through the Notes Client or than those created when accessing the Domino application directly from a Web browser. Elizabeth will not have access to databases where her Domino identity is listed in the ACL, either explicitly or through group membership. The same applies to documents where there are restrictions through either reader or editor fields. Because of these limitations, we are forced to abandon the use of DA as a solution to this problem. What is really needed is a method to map the LDAP identity to the Domino identity. Fortunately the Domino server provides this for us. The User Name field of the person document is a multi-valued field and can contain as many variations of the user's name as needed (although, as a best practice, each of these entries should be unique in the directory). When a match is found against one of the entries in this field, Domino maps the identity to the first entry in the field for the purposes of authorization. This is normally the hierarchical version of the user's name. To take advantage of this capability and overcome the issues discussed here, we need to turn off DA and then add the user's LDAP DN (replacing commas with "/") after the second line of the User Name field. Now when the Domino server receives the full DN, it searches the Domino directory. This initial search still fails. If DA were enabled on the server, DA would now search the LDAP directory, and you would end up with the same problems you had earlier. Instead, it examines all of the entries of the User Name field and finds a match of the full LDAP DN (with the commas translated to /). The user's LDAP DN is then associated with the first entry, and the user is authenticated as the Domino identity. All of their actions in the Domino environment are now carried out with their Domino Identity and those in the WebSphere Portal environment done with their LDAP identity. This same solution works when the LTPA cookie is used. Since the LTPA cookie is created with the user's LDAP DN, the Domino server will find that name in the User Name field and associate it with his or her Domino identity. Configuring to Avoid the Multiple Identities Problem The first thing to do is configure the Domino environment to establish the LTPA relationship between the WebSphere Portal and Domino servers. Directory Assistance is turned off by default. However, if you are using DA to cascade multiple Domino address books, it can be left enabled ”just do not include the WPS LDAP directory in the Directory Assistance search path. In each user's Person document you will need to add at least one entry to the User Name field. The first line of this field should already contain the full hierarchical Domino user name. The second entry should be the common name of the user (cn) (First Name, Last Name). These entries are set up by Domino when a user is registered and should be left as is. Additional entries, such as other forms of the common name, maiden name, and nicknames, may exist and are ok. After that you should include the user's LDAP DN in Domino format ("/" replacing commas). In the preceding example, the user's short name in LDAP matched the one in the Domino directory. If this is not the case, then the LDAP uid must also appear in the User Name field of the Person document. The same applies to other LDAP attributes, such as common name (cn). If the common name of the LDAP entry is different than the second line of the User Name field, the common name must be added to the field to allow people awareness to work. The following table illustrates the different values needed in the Domino User Name field. Table 12-6. Example Directory Entries for WPS | LDAP Entry | Old Domino Entries | New Domino Entries | | cn=Elizabeth Somebody,ou=Boston,o=YourCo uid=euser | User Name = Elizabeth Somebody/Boston/YourCo Elizabeth Somebody Beth Somebody Shortname = esomebody | User Name = Elizabeth Somebody/Boston/YourCo Elizabeth Somebody Beth Somebody cn=Elizabeth Somebody/ou=Boston/o=YourCo Short Name = esomebody | | cn=Elizabeth Somebody,ou=Boston,o=YourCo uid=y32483 | User Name = Elizabeth Somebody/Boston/YourCo Elizabeth Somebody Beth Somebody Shortname = eSomebody | User Name = Elizabeth Somebody/Boston/YourCo Elizabeth Somebody Beth Somebody cn=Elizabeth Somebody/ou=Boston/o=YourCo y32483 Short Name = esomebody | | cn=Beth Somebody, ou=Boston,o=YourCo uid=euser | User Name = Elizabeth Somebody/Boston/YourCo Elizabeth Somebody Shortname = esomebody | User Name = Elizabeth Somebody/Boston/YourCo Elizabeth Somebody Beth Somebody cn=Beth Somebody/ou=Boston/o=YourCo Short Name = esomebody |
Since WebSphere Portal may pass user name and password for some of the authentications, you also need to synchronize the Internet password between the Domino and LDAP directories. This is absolutely critical for full Domino integration with the WebSphere Portal. Remember, there are still transactions that occur between the Domino Server and WebSphere Portal using the credentials used to log on to WebSphere Portal. These requirements will require ongoing maintenance. This can either be done manually or with tools such as IBM Directory Integrator. Lotus IM Configuration The Lotus IM server should be configured to authenticate against the native Domino Directory to allow people awareness. With version 3.0, the Lotus IM documentation recommends that an LDAP directory be used. However, in a multiple directory environment configuring Lotus IM to use the Native Domino directory provides for more flexible People Awareness. The specific example is the use of the NotesView portlet. If People Awareness is turned on for a column that contains the common name of a user, either directory (LDAP or Native Domino) can be used. If the column contains the full canonical name of the user, Lotus IM will not be able to determine online status if Lotus IM is using the LDAP directory. Unlike QuickPlace, which makes LDAP calls to the directory server, Lotus IM uses Directory Assistance when authenticating against LDAP. Since Directory Assistance is necessary for Lotus IM to operate, DA must be configured on the Lotus IM. However, this is the only server where it should be configured. Although Lotus IM awareness will work, you will have the problems discussed earlier when authenticating to Domino applications running on the Lotus IM server. QuickPlace Configuration When using QuickPlace 2.08, you should configure the server to use Domino as the directory. When configuring the underlying Domino server for SSO, you must use a special version of the domcfg.nsf file. This version is available from www.lotus.com/support. This file contains an updated default domain login document that performs some additional processing to maintain the LTPA cookie. If you use the default domcfg.nsf that is provided with Domino, the LTPA cookie will be overwritten when you access a QuickPlace, and when you return to WebSphere Portal you will need to log in again. QuickPlace 3.0 should be configured to access the same LDAP directory as the WebSphere Portal. If you are accessing an existing QuickPlace environment that has migrated from an earlier version, this may be a problem. You may need to use the changemember command to update the user names in the QuickPlaces to their LDAP version. This will allow users to maintain their current QuickPlace capabilities in the environment. If you have a requirement that you must use either the Native Domino directory or Domino Directory through LDAP, then you will need to obtain a patch that supports the appropriate name mapping. SSO for WebSphere Portal and Domino Observations SSO is rarely simple to implement and must be well thought out. The methods outlined in this section will allow you to configure your WebSphere Portal and Domino environments to leverage their respective strengths. As WebSphere Portal and Domino evolve , other solutions will be available. In more complex environments, it may be desirable to consider the version of the WebSphere Portal Server that includes Tivoli Access Manager. | 