In part 1 of this article series, our intrepid (if somewhat obscure) secret agent pal Jim Bland helped us through the basics of single sign-on and multi-directory, multi-identity environments. Now we'll follow Mr. Bland and friends through several SSO scenarios, and conclude the series with a quick peek at SSO enhancements in Notes/Domino 7. As with part 1, we assume that you're an experienced user and/or administrator of Notes and Domino.

Single sign-on scenarios

There are several SSO solutions, and in this article we will discuss four particular deployment scenarios. It's important to note that no one solution is better than the other. It will always depend on the infrastructure of the organization, and the rules administrators must follow. For some parts of the organization, LDAP is the corporate directory, and all changes must be made in there. For other branches, LDAP schema is not allowed to be modified, so all changes need to occur in the Domino directory. (See this sidefile for more information about LDAP schema and Domino schema.)

There may be particular cases where an organization needs access to both an LDAP directory and the Domino Directory for reasons other than SSO. For example, TSGA has a special inventory system that tracks defective, blown-up, and top secret equipment. This inventory system needs access to the ITDS LDAP directory where some "Special Equipment" directory objects exist, so Directory Assistance is configured in their environment to point to the ITDS LDAP directory. In this case, managing the relationships between the various configured directories will be key to the SSO deployment.

To sum up, in the SSO scenarios we'll examine later in this article, some scenarios manage SSO information in the Domino directory, while others manage SSO in an LDAP directory. We also have scenarios where Directory Assistance comes into the picture. Hopefully, among the various scenarios you'll recognize one as being a close fit with your infrastructure and your organizational needs. The SSO configuration you choose will always depend on the needs of the organization at hand.

While the SSO approach may differ in the various scenarios, note that in all cases, Bland will always log into the WebSphere Portal Server first and an LtpaToken is created containing his ITDS identity uid=jb013.

Scenario 1: Name mapping using the Domino person document

Let's start by describing our most commonplace and basic scenario. This scenario describes how to manage SSO information in the Domino directory.

When Bland switches to the DWA portlet, the LtpaToken containing jb013 is sent via HTTP. How then will the Domino server allow Bland access to his DWA mail file, especially when the ACL entry on that file allows access to cn=Jim Bland/ou=secret/o=spies? Simple--the administrator can modify Bland's person document, adding uid=jb013/ou=secret/dc=spies/dc=com to a secondary value of his fullname field (see figure 1):

The Domino Web Access server will search in the Domino Directory for the value contained in the LtpaToken, and it finds a match because that value is contained in the person document. Domino resolves the name to the Domino distinguished name, Jim Bland/Secret/Spies, which is contained in the ACL on his mail file, so Bland is granted access to his mail portlet!

The TSGA administrator must keep these rules in mind for name mapping:

• When modifying the FullName field of a Domino person document, enter the agent's LDAP distinguished name in "Domino format."
  LDAP format: uid=jb013,ou=secret,dc=spies,dc=com
Domino format: uid=jb013/ou=secret/dc=spies/dc=com
• Add the LDAP DN to the FullName field as a secondary value. Do not add LDAP DN as the first or second value. Domino expects the primary value to be the Domino DN, and the second value to be a Domino "common name."
• Some applications are case-sensitive, so be careful! While Domino is forgiving on case, other applications may not be. Better to be safe than sorry.
• To facilitate directory changes, TSGA may want to consider utilizing the IBM Tivoli Directory Integrator to automate an implementation of their mapping policies.

Scenario 2: Name mapping using Directory Assistance: resolving multiple matches

As we mentioned previously, some organizations may require access to both directories simultaneously, often not for reasons of single sign-on. For the TSGA Research Department, their infrastructure requires that the Domino server have access to IBM Tivoli Directory Server (ITDS) for the lost equipment inventory system mentioned earlier. In order for TSGA's special inventory Notes application to access some "Special Equipment" directory objects that exist in ITDS, the Administrator creates an LDAP entry for the ITDS directory in the Directory Assistance database on the Domino server (the server also running Domino Web Access).

To achieve SSO in this environment, just as in the previous scenario, TSGA adds the LtpaToken value uid=jb013,ou=secret,dc=spies,dc=com to the person document in Domino. This brings up a new dilemma. The name uid=jb013,ou=secret,dc=spies,dc=com now exists in two places: in the ITDS entry for the user, and in a Domino person document for Jim Bland/Secret/Spies. How will the Domino server handle finding a match for Bland in both the Domino Directory and the ITDS server, when the DNs (distinguished names) differ? How does Domino determine that they really are the same person?

The latest Domino 6.x and 7.0 releases handle name-mapping scenarios where user entries are found in multiple locations when Directory Assistance is involved. Domino requires consistency between a Domino person document and an LDAP record; as a result Domino will now take extra steps to determine that there are matching values for the "Internet address" field located in both directories. To accomplish this, DA issues a search query for the identity uid=jb013 along with the equivalent LDAP attribute for the Notes field InternetAddress. For LDAP, the equivalent attribute is mail.

The bottom line is that if TSGA has an environment in which DA points to the LDAP directory that contains the SSO identities, the administrator must ensure that the value of the Domino attribute "Internet address" matches the value of the LDAP attribute "mail."

For additional information on how Domino and Directory assistance handles name-mapping and multiple matches refer to the Notes/Domino 6.0.4 Release Notes, "WebSphere and Domino names handled by Domino HTTP server."

Figures 2, 3, 4, and 5 follows Jim Bland as he progresses through the SSO steps when Directory Assistance is pointing to the LDAP directory that contains the same uid that's been added to the person document. In figure 2:
A. Bland browses to his DWA portlet. Portal passes the LtpaToken to the Domino Web Access server, which does a lookup in the Domino directory for uid=jb013,ou=secret,dc=spies,dc=com.
B. Domino finds a match for uid=jb013,ou=secret,dc=spies,dc=com in Bland's third FullName value in the primary directory, in the person document belonging to the user with the Domino distinguished name Jim Bland/Secret/Spies.

In figure 3:
C. Directory Assistance is configured so a search query is issued for the specified LDAP directory. LDAP search:
BaseDN: ou=secret,dc=spies,dc=com
Filter: uid=jb013
attrs to return: "mail"
D. The IBM Directory Server returns a match, and the requested value for the mail attribute: mail=JBland@secret.spies.com.

In figure 4:
E. Do the contents of "mail" match the contents of "InternetAddress"? In other words, does the value of the InternetAddress attribute in the Domino person document match the value of the mail attribute in ITDS?

And finally, in figure 5:
F. The same person (Jim Bland) is verified as being represented by the ITDS record and the Domino person document, based on the matching mail address in each of these records. The name mapping from LDAP name to Domino name succeeds, and Bland is allowed access to his Domino Web Access mail file.

Scenario 3: Name mapping by modifying foreign LDAP schema and DA

In various TSGA organizations, LDAP is the corporate directory of choice. There are policies and procedures in place to manage directory schema additions, deletions, and modifications in LDAP and only LDAP. In this example, modifications and updates are managed primarily through the IBM Tivoli Directory Server and modifications are not allowed in the Domino Directory. With the versatility of a new feature added to Directory Assistance in Domino 6.0, this is no problem. A TSGA administrator can choose to modify the corporate LDAP directory, adding the Notes distinguished name (DN) as an attribute of a user's LDAP identity. In Bland's case, the Notes distinguished name is added as an attribute of his uid=jb013,ou=secret,dc=spies,dc=com entry in IBM Tivoli Directory Server. An LDAP domain is added to Directory Assistance, pointing to the corporate LDAP directory server. If TSGA adopts this strategy to add information into LDAP, no modifications need to be made to Domino person documents (so no modifying secondary values of the FullName field).

The administrator must then choose which LDAP attribute to populate in IBM Tivoli Directory Server with the Notes distinguished name. The attribute can be one that already exists in the LDAP schema, or the administrator can choose to extend the LDAP schema creating a brand new attribute. Either way, the attribute must be of type DN syntax. For more information on attribute syntax types refer to RFC 2252.

Once an attribute has been selected, our TSGA administrator can add the Notes DN for each identity that requires SSO, in LDAP-style syntax. Suppose the administrator chooses to create a new attribute called NotesDN, which is part of the person schema in the IBM Tivoli Directory Server LDAP directory. He then adds the Notes distinguished name cn=Jim Bland, ou=secret, o=spies as a value of the NotesDN attribute. To configure for SSO, the administrator selects the LDAP tab (see figure 6) for the DA Domain entry and in the "Attribute to be used as Notes Distinguished Name" field adds the name of the LDAP attribute NotesDN and ensures that "Trusted for credentials" is set on the Naming Contexts (Rules) tab. Also, our TSGA guy validates that any naming context rules for LDAP hierarchies are correct. In other words, the directory hierarchy in IBM Tivoli Directory Server (ou=secret,dc=spies,dc=com) differs from that in Domino (ou=secret/o=spies). Verify that the rules are correctly defined in DA . For more information on Directory Assistance Naming Contexts, refer to Directory assistance and naming rules in the Domino Administration Guide.

Figures 7, 8, 9, and 10 follow Jim Bland's request as it progresses through the SSO environment using this new feature. In figure 7:
A. Jim browses to his Domino Web Access portlet and the Portal passes the LtpaToken to the DWA server, which does a lookup in the Domino directory for uid=jb013,ou=secret,dc=spies,dc=com. Again, unlike the scenario discussed in the previous section, uid=jb013,ou=secret,dc=spies,dc=com does not exist anywhere in the Domino directory.
B. The Domino directory is configured with Directory Assistance. Directory Assistance is configured with the "Attribute to be used as Notes Distinguished Name" feature.

In figure 8:
C. An LDAP search query is issued for uid=jb013 with a request to return the attribute NotesDn. LDAP search:
BaseDN: ou=secret,dc=spies,dc=com
Filter: uid=jb013
attrs to return: "NotesDN"
D. The IBM Directory Server returns a match with the NotesDN attribute containing the value cn=Jim Bland,ou=secret,o=spies.

In figure 9:
E. Because the NotesDN is returned, the uid=jb013/ou=secret/dc=spies/dc=com format name is mapped to the Notes distinguished name that is present on the mail file ACL.

And in figure 10:
F. Jim Bland is allowed access to his Domino Web Access mail file.

Scenario 4: IBM collaborative components using LDAP protocol for name mapping

So far, our scenarios have been reasonably straightforward to comprehend and to deploy. Brace yourself, as things are about to get more complicated. In this scenario, we focus on the SSO needs of our Domino extended product family.

Ever the model of spontaneity, Jim decides he wants to instant message with Agent 009 about a particularly sticky situation ongoing in Dubuque. Later, he plans to access the TSGA Agent Team Workspace from his WebSphere Portal Server portal page. He is now using two of the collaborative components in IBM's integrated environment for SSO: Sametime and Quickplace. Sametime and Quickplace are configured for SSO (they've both received the same LtpaToken that contains the name of the logged in user "uid=jb013..." ). Unlike DWA in our previous example, both Sametime and Quickplace are configured to look up users in the Domino Directory via the LDAP protocol, instead of using the Domino Directory interface based on the native Domino NRPC protocol. When the Sametime or Quickplace server queries Domino for the identity contained in the LtpaToken, the query is done using the LDAP protocol; therefore the Domino LDAP server will receive the request and begin its search.

If the Domino Server finds a match in its directory, it will return back to the requestor the Domino DN in LDAP formatted syntax - "cn=Jim Bland,ou=secret,o=spies." It's then the responsibility of Sametime or Quickplace to determine that "cn=Jim Bland,ou=secret,o=spies" is really the same identity as the LtpaToken value "uid=jb013,ou=secret,dc=spies,dc=com." In essence, the Sametime and Quickplace servers are now responsible for doing the name mapping. This is different from the previous scenarios. In the case where the applications access Domino via HTTP (for TSGA, this was a DWA portlet) the Domino Web Server will receive the request and the LDAP queries are created natively by Directory Assistance--as a result the Domino Directory will handle all the name mapping needs. However, in the case we're examining now, Domino and Directory Assistance are not taking responsibility for handling the name mapping, and instead the mapping must be handled by Sametime and Quickplace. As previously mentioned, directory lookup via the LDAP protocol is the means by which Sametime and Quickplace accomplish name mapping.

For all this to be accomplished, the all-knowing and all-powerful TSGA administrator will have to perform a few more feats of excellence:

The TSGA administrator must implement name mapping, adding the LDAP DN as a secondary value of the FullName field in the Domino person document. The TSGA administrator must also turn on LDAP alias dereferencing for the respective LDAP clients--in this particular case, the Sametime Links client as well as the Quickplace client. In order for the LDAP server to find an LDAP name that has been listed as a secondary value of the FullName field in the Domino person document, the LDAP client has to request the LDAP server to dereference aliases when doing a name search. LDAP aliases and Notes aliases are two different concepts. Basically, an LDAP alias is an entry in a LDAP or X.500 directory that points to another entry in the directory hierarchy. For Notes, aliases are any secondary value of the FullName field or the ShortName field. In order for the Domino server to resolve an alias (for instance, the LDAP name such as "uid=jb013...") to the Domino distinguished name, the LDAP server must receive a request from an LDAP client with Dereferencing of Aliases turned on:

LDAP alias dereferencing must also be enabled on the LDAP server: By default, the Domino LDAP Server does not dereference aliases. The TSGA administrator will enable this feature by opening the global configuration record *-[ALL Servers] from the Configurations options in the primary Domino directory, selecting the LDAP tab, and setting "Allow dereferencing of aliases on search requests?" to Yes (see figure 11):

Upgrade both the Sametime and Quickplace servers to latest point releases (hotfixes may also be required for multi-directory configurations).

There's even more to know. Sametime administrators can view this sidefile to learn more about Sametime administration tips, and Quickplace administrators can view this sidefile for Quickplace-related information.

Back to top

Instant death scenarios

Jim Bland dreams of exciting assignments filled with intrigue and danger. However, his current parking sting probably does not involve any life and death scenarios. The same cannot be said for SSO. We know that your defenses may already be worn down by our multi-directory, multi-identity technobabble. However we must persevere and bring to your attention some critical issues regarding names that contain special characters. Names containing special characters can cause instant death in SSO scenarios.

Domino distinguished names have a different format from LDAP distinguished names. As mentioned previously, Domino uses slash separators, whereas LDAP uses comma separators. Various IBM products have implemented logic to transform a name in one format to a name in the other format. However, in addition to the separator character, there are also a number of other syntactic differences between Domino format and LDAP format names that must be handled correctly. In particular, the following characters need special handling when present in an LDAP name:

• less than character <
• greater than character >
• semicolon character ;
• comma character , (within a name, not being used as separator)
• plus sign character +
• double quote character "
• backslash character \
• A space or # character occurring at the beginning of the string
• A space character occurring at the end of the string

Names with special characters can cause trouble in SSO scenarios at the time that the name in an LTPA cookie is transformed from LDAP format to Domino format, and vice versa. As names are critical to SSO, clearly SSO falters if there is any hitch in the transformation such that the name is rendered unrecognizable. The underlying software must be equipped to do the job of proper transformation. You can avoid instant death scenarios in your environment only by getting the latest and greatest releases. To ensure that special characters in names are properly handled in SSO scenarios, you should upgrade to Domino 6.5.4 or later.

Names containing special characters also cause problems in the Collaborative Portlets as well as the Domino extended product family. If you have deployed a version of WebSphere Portal earlier than 5.1, you may need fixes for handling names with special characters. Likewise, there are also fixes required for Quickplace and Sametime servers to support special characters.

Back to top

Coming attractions

Currently, in a multi-identity scenario, the user must always log in first to WebSphere (or to a WebSphere component, such as the portal). WebSphere must create the LTPA cookie, placing in it the user's LDAP name that WebSphere can recognize. SSO works fine because Domino is flexible and can be configured to accept an LTPA cookie created with an LDAP name known to WebSphere. However, the reverse situation is problematic: in a multi-identity scenario, WebSphere has trouble accepting a name in Domino format. Why would the name be in Domino format? If the user logs in first to Domino, Domino creates the LTPA cookie and will put a Domino format name into it. When WebSphere receives a cookie and looks up the name in the cookie, SSO breaks because the Domino name is not found in WebSphere's user directory. In order for WebSphere to be made flexible enough to accept a Domino name, you would have to write some custom code for the WebSphere side. Since a custom solution takes work to deploy and support, this is usually not a desirable strategy, and instead you would simply advise your users to log in first to WebSphere. Help is on the way. For the convenience of users, Domino 7 removes the restriction that users must log in first to WebSphere. In Domino 7, we provide configuration options that allow users to log in first to Domino. The idea is that the administrator picks the format of the user's name that should be put into any LTPA cookie created by Domino for the user. Instead of placing a Domino-format name into an LTPA cookie, Domino 7 can be configured to put an LDAP name into an LTPA cookie. For maximum SSO interoperability, the administrator should pick the name format that will be acceptable to Domino, WebSphere, and any Domino extended products.

Domino 7 users can try out this new feature today. The first step is to flip the switch that says you want to configure LTPA user names. The switch is located in the SSO configuration document in a new field (see figure 12). If the switch is not flipped, Domino will continue to place the user's Domino name into an LTPA cookie that Domino creates for the user. If the switch is flipped, then Domino will be looking for an LDAP-configured name to put into an LTPA cookie.

In Domino 7 person documents, a new field has been added for specifying the LTPA user name. This field in the person document will be consulted if the SSO configuration is enabled for mapping names in LTPA tokens. In the "LTPA user name" person document field, the administrator can configure Jim Bland's LDAP name that can be accepted by both WebSphere and Domino. This is the name that Domino 7 will put into any LTPA cookie that Domino creates for Bland. Note that a configured LTPA user name must always be entered into the person document in Domino format, with slashes instead of commas. But fear not--when Domino creates an LTPA cookie, it converts from Notes format to LDAP format as necessary before placing the name into the cookie, handling special characters in the name as needed.

Of course, some users don't have a Domino person document. Instead, these users have user records in a foreign LDAP directory. Domino Directory Assistance is used in this case to locate users in that LDAP directory. Since these users don't have a Domino person document, obviously the new LTPA user name field in the person document cannot be used in the case that the SSO configuration is enabled for mapping names in LTPA tokens. For Domino users in an LDAP directory, the administrator can instead configure the LTPA user name in the Directory Assistance document. In the Directory Assistance configuration in Domino 7, there is a new field, "Attribute to be used as name in an SSO token." Typically, an administrator will populate this field with the special keyword $DN. The $DN keyword is a shorthand way to indicate that the user's LDAP distinguished name should be put in the LTPA cookie. Whenever Domino creates an LTPA cookie for any user in that foreign LDAP directory, Domino would place the user's LDAP distinguished name in the cookie if $DN has been configured as the attribute to be used as name in an SSO token.

Back to top

The (less) mysterious world of SSO: closing credits

Here we are, at the end of our story, and it's time for you to emerge from the shadows and become an SSO action hero. Your mission, should you choose to accept it, will be to help all of the Jim Bland characters in your office get their work done efficiently. Nothing could be more rewarding.

In this article series, we hope we have equipped you with the information you need to forge ahead with your SSO deployment, especially if your environment contains multiple directories and multi-identities. Perhaps you now understand more about how SSO works and the infrastructure choices you can make to accommodate users known by more than one name. The choices you make will depend on your administrative strategy. IBM provides solutions for managing SSO information in the Domino directory and in an external LDAP directory. Once your SSO directory deployment is underway, your mission may include configuring Sametime and Quickplace, taking note of our special tips for success in a multi-identity environment. You, the administrator, must arm with all the right weapons, so that your users can successfully and reliably move through the tricky world of SSO.

We've seen that our hero Jim Bland can maneuver through his SSO-enabled Web portal just as easily as he does the domestic world of espionage. Meanwhile, Bland's boss VM is happy to see SSO giving Bland a much-needed productivity boost. No longer will Bland face multiple identity challenges while he goes about getting his work done. The only downside to Bland's fully integrated SSO environment is that he'll miss hearing the sound of his own name spoken at every turn. With a functional SSO environment, Jim Bland can rest assured that whenever that elevator door opens, there will be a floor waiting for him to step out onto. Two thumbs-up for SSO!

Resources

• Part 1 of this article series discusses the basics of single sign-on and multi-directory, multi-identity environments.
  
  
• See the developerWorks: Lotus article, “Security APIs in Notes/Domino 7.0,” to learn about the new encryption/decryption APIs offered by Lotus Notes and Domino 7.0.
  
  
• For more information about new security-related features in Lotus Domino 7.0, see the article, "New features in Lotus Domino 7.0."
  
  
• See the Lotus Notes/Domino product page for more information about the Lotus Notes and Domino products.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  

About the authors

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Single sign-on scenarios
• Instant death scenarios
• Coming attractions
• The (less) mysterious world of SSO: closing credits
• Resources
• About the authors
• Comments

Next steps from IBM

• Try: Lotus Notes and Domino Administrator
• Demo: Lotus Notes 8 composite applications
• Webcast: Modernization approaches to reduce the total cost for multi-platform enterprise applications
• Briefing: Smarter collaboration with IBM Lotus solutions
• Buy: Lotus Notes and Domino Administrator

My developerWorks community

Dig deeper into Lotus on developerWorks

Calling all developers

Download no charge Lotus Domino Designer

Special offers