Netegrity SiteMinder and Domino-based collaborative services

Want to use SiteMinder for single sign-on with Domino, Lotus Team Workplace (QuickPlace), and Lotus Instant Messaging and Web Conferencing (Sametime), but don’t know where to start? This article provides you with a roadmap for implementation.

Share:

Raj Balasubramanian, Consulting IT Architect, IBM, Software Group

Raj Balasubramanian is a Consulting IT Architect for IBM Software Services for Lotus (ISSL). He works on customer engagements delivering application and infrastructure related projects. His interests range from anything technical to history and physics. During his copious spare time, he enjoys talking about robots with his sons.



22 December 2003

Also available in Japanese

More and more corporations are deploying single sign-on (SSO) across their enterprises. With SSO, users can log into one application and then open other SSO-enabled applications during the session without signing in again. One way to implement SSO is with Netegrity SiteMinder to provide this functionality across various Web-based applications. However, before you do this, you need to understand how SSO affects an existing Domino environment. When you deploy Netegrity SiteMinder as your SSO solution for Web-based applications, you must ensure that Domino and associated Lotus collaboration software can function within this new SSO environment.

This article covers the basics of how SiteMinder implements SSO on the Domino platform, offering a blueprint for making key decisions to best leverage SiteMinder and Domino. We begin by introducing SiteMinder. We then provide guidelines for implementing SiteMinder on Domino, Lotus Team Workplace (QuickPlace), and Lotus Instant Messaging and Web Conferencing (Sametime). This article assumes that you're an experienced administrator of Domino and/or other Lotus collaborative software.

Introducing SiteMinder

Netegrity SiteMinder is a directory-enabled, standards-based system that can help you work with heterogeneous Web and application servers, operating systems, and application development platforms. Using SiteMinder, you can easily implement security policies that protect Web applications and resources. It enables you to manage authentication and authorization privileges based on a user-centric policy-based model for security. SiteMinder can also help developers deliver secure Web applications by managing complex security and management requirements. SiteMinder includes two key components in its infrastructure for implementing SSO. The first is the Policy Server. Rules and other related information about directory, users, and resources are stored here. The second component is the webagent. This is the software installed on the Web server or application server that implements SSO. The following diagram illustrates how these components function and interact within a SiteMinder-enabled environment:

Figure 1. SiteMinder environment
SiteMinder environment

SiteMinder supports various Web servers, including Domino running on Windows NT/2000 and Solaris (and also the Domino Go Web server running on OS/390). As of this date, the current release of SiteMinder is version 5.5. However, most of the configuration information provided in this article also applies to version 4.x. (We will point out version-specific differences where they apply.) For detailed technical information about SiteMinder, consult the SiteMinder Web page.


Domino authentication

Domino provides authentication for HTTP-based access via the C API and DSAPI (Domino Server API). The following diagram illustrates the use of DSAPI to support custom authentication:

Figure 2. Custom authentication with DSAPI
Custom authentication with DSAPI

DSAPI is implemented as a shared library (a DLL file on Windows 2000/NT or shared object on UNIX/Linux) that is registered and invoked by the Domino HTTP process. There are key events associated with the HTTP task, and these events are overwritten by the custom code in the DSAPI. Because DSAPI is in effect replacing the Domino authentication model, it lends itself to the following:

  • A wide array of custom authentication requirements can be met by implementing DSAPI.
  • Every HTTP request is intercepted and processed by DSAPI.

The Netegrity SiteMinder webagent for Domino is implemented as DSAPI. SiteMinder implements SSO by issuing an SMSession cookie for the user session. Any other Web or application server configured to work within the SiteMinder environment can validate the credentials within the cookie and authenticate the associated user. The cookie is encrypted using secret keys. In addition to providing the basic user identity, you can configure some agents to look up user identity from the HTTP request header. The SiteMinder webagent for Domino is capable of providing the user identity based on certain values in the user’s HTTP request header.

In addition to providing SSO, you can also configure the webagents to provide a secure environment with protection against Cross Site Scripting (CSS) attacks, to provide rules to allow only trusted IPs/hosts, to authorize resources by building sophisticated authorization lists for Web resources, to check for malformed URLs, and to provide many other distributed security features. These configurations are normally set in the webagent configuration file on the target Web server (in version 4.x and 5.x of SiteMinder) or on the Policy Server (in version 5.x of SiteMinder). The file that contains the webagent configurations on the target Web server is named webagent.conf. While enabling the Domino server for SSO using SiteMinder, you can use Domino’s ACL feature for authorization or build the authorization list in SiteMinder. Our experience has shown that SiteMinder is often used for authentication and Domino’s ACL feature used for application authorization. Therefore, you can leverage the full ACL (server, database, view, and document level) within the SSO environment provided by SiteMinder.


Configuring the SiteMinder Policy Server for a webagent

Let’s look at how the Policy Server is used to enforce SSO in the SiteMinder environment. Policy Server is the central location where the policy definition for a webagent is stored. Prior to deploying the webagents on any target Web server, you need to define various policy and agent-specific objects on the Policy Server.

The Policy Server provides options to determine how the installed webagent should behave. Every webagent should have the following defined on the Policy Server:

  • Agent profile consists of information about the IP address or host name of the agent.
  • Agent Configuration object, a feature available in SiteMinder 5.x, contains information about the IP address or host name of the agent.
  • Host Configuration object, available in SiteMinder 5.x, contains information about the Policy hosts and Policy Server-related settings.
  • Policy Domain is a grouping of related realms, rules, responses, and policies (see the following bullets).
  • Realm defines the resource to protect/unprotect with a definition of the authentication scheme.
  • Rule defines specific Web actions for the protected/unprotected resources. It also allows or denies access.
  • Response is an optional feature that defines HTTP headers sent to target Web servers. These can be static or custom built per request.
  • User directory defines a repository of users (predominantly LDAP-based).
  • Policy defines the combination of rule, realm, user directories, and responses.

The following diagram illustrates the relationships between components configured on the Policy Server for a webagent:

Figure 3. Relationships between components configured on Policy Server for a webagent
Relationships between components configured on Policy Server for a webagent

For our examples, we use the Domino user name in the format CN=Albert Einstein/OU=Physicists/O=Scientists, and the LDAP distinguished name (DN) in the format uid=emc2,ou=physicists,o=scientists.


Domino-specific webagent configurations

The SiteMinder webagent for Domino has special parameters that give flexibility to the workings of the webagent on a Domino server. For a detailed list of parameters, refer to the SiteMinder webagent guide. The key parameters discussed in this article are:

  • SkipDominoAuth skips the Domino authentication if set to Yes. For the webagent to work properly in Domino, set this parameter to No.
  • DominoSuperUser identifies a user name that has access to all resources. If SkipDominoAuth is set to No, this parameter is seldom used (although it is a good practice to set it anyway). The value for this parameter is encrypted.
  • DominoDefaultUser identifies a user name to serve as the default Domino user when SiteMinder authentication cannot resolve or obtain a valid user identity for the session. The value for this parameter is also encrypted. Set this value to Anonymous or Nobody.
  • DominoUseHeaderForLogin is the value of a SiteMinder header used to identify the user within the Domino environment. This is a very powerful parameter; it allows you to change user identity dynamically based on a variety of factors.
  • DominoLookupHeaderForLogin is set to Yes or No. When you set this to Yes, the webagent performs a local name lookup call to the underlying Domino Directory to get a Domino user name based on the value from the DominoUseHeaderForLogin.

Scenarios for introducing SiteMinder into a Domino environment

The core issue in introducing SSO into an existing Domino environment is the fact that all Domino application ACLs and authentication are based on the Domino Directory, while the SSO engine may be leveraging an LDAP directory. This situation can introduce a different user identity depending on the setup. It is therefore critical for you to understand the possible options while introducing SiteMinder into a Domino environment.

The three key mechanisms that we need to worry about in a Domino environment are:

  • Authentication (validating a user's credential to ensure that the user is who he says he is)
  • Authorization (which operations are users allowed to perform)
  • Awareness (on-line presence status of an authenticated user)

As discussed in the previous section, authentication is handled by the webagent on a given Domino server, and authorization is performed by the Domino ACL per application. Awareness is handled by Lotus Instant Messaging and Web Conferencing. Both authorization and awareness rely on the given user identity after the successful authentication process. Therefore, the identity of a given user should be the same on any given Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing servers that participate in SSO and that require Domino-based authorization and instant messaging or Web conferencing-based awareness for users.

How you introduce SiteMinder into a Domino environment depends on the answers to the following questions:

  • Is there an existing Domino infrastructure?
  • Do you want to use Domino LDAP for the SiteMinder infrastructure?
  • Is there an existing LDAP directory that SiteMinder uses?
  • Do you want your applications to use Domino user names?
  • Will names be looked up in the local Domino Directory?
  • Can you add attributes to the LDAP directory?
  • Can you modify the Domino Directory?

The following sections offer guidelines for various scenarios defined by different combinations of answers to these questions. In addition, be aware of two types of identity and directory patterns: single-identity/single directory, and multi-identity/multi-directory. The single-identity and single-directory pattern supports the concept of using a single LDAP directory (Domino or non-Domino-based) for both Lotus Team Workplace and Lotus Instant Messaging and Web Conferencing and the SiteMinder environment. The authentication yields a standard DN across SiteMinder and Lotus Team Workplace and Lotus Instant Messaging and Web Conferencing, and the authorization list and awareness are based on this user identity:

Figure 4. Single-identity and single-directory pattern
Single-identity and single-directory pattern

The multi-identity and multi-directory pattern supports the concept of using the Domino Directory for Lotus Team Workplace and Lotus Instant Messaging and Web Conferencing, while using a different LDAP directory (Domino or non-Domino-based) for the SiteMinder environment. The authentication yields an LDAP DN in a non-Lotus platform, while yielding a Domino DN within Lotus Team Workplace and Lotus Instant Messaging and Web Conferencing. The authorization list and awareness are based on the Domino DN of the user identity, hence the Domino Directory:

Figure 5. Multi-identity and multi-directory pattern
Multi-identity and multi-directory pattern

Scenario 1

This scenario applies if the following is true:

  • There is an existing Domino infrastructure.
  • You want to use Domino LDAP for the SiteMinder infrastructure.

Because Domino LDAP is supported by SiteMinder, you can use it as the user directory for the SiteMinder SSO environment. Because Domino groups don’t have a hierarchy by default , we suggest you rename or recreate groups with a hierarchy. This provides a base DN for the groups within Policy Server.

If the Domino Directory belongs to a different Domino domain from the deployed target Web servers (Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing), then you need to set up Directory Assistance on these Domino servers for successful name resolution.

The user name authenticated by the SiteMinder webagent uses the Domino format. No additional steps are required for webagent setup. Proceed to configuring the webagent on Domino. See the description for the single-identity and single-directory pattern in the previous section for additional information.

Scenario 2

In this scenario:

  • There is either an existing Domino infrastructure, but no Domino LDAP for the SiteMinder infrastructure or no existing Domino infrastructure.
  • There is no existing LDAP directory that SiteMinder uses.

Because there is no LDAP directory in the environment, build an LDAP directory that is supported by SiteMinder as well as Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing. Using a relational database requires further customizing the environment because Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing do not support a relational database for user registries. Refer to the description for the multi-identity and multi-directory pattern in the previous section for additional information.

Scenario 3

For scenario 3:

  • There is either an existing Domino infrastructure, but no Domino LDAP for the SiteMinder infrastructure or no existing Domino infrastructure.
  • There is an existing LDAP directory that SiteMinder uses.
  • You don't want your applications to use Domino user names.

You have chosen not to use the Domino user name format, so it is imperative to note that none of the Domino mail files can be accessed within the SSO environment without modifying the Person documents and the mail file ACLs with the LDAP DN.

Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing continue to function as long as they are mapped to the same LDAP directory because they use the underlying LDAP DN to identify the user internally. Also see the previous description for the single-identity and single-directory pattern.

Scenario 4

Scenario 4 applies if the following is true:

  • There is either an existing Domino infrastructure, but no Domino LDAP for the SiteMinder infrastructure or no existing Domino infrastructure.
  • There is an existing LDAP directory that SiteMinder uses.
  • You want your applications to use Domino user names.
  • Names are looked up in the local Domino Directory.

Because the choice has been made to allow lookups to the local Domino Directory, the resulting user identities are in Domino user name format. This is normally done via a specific webagent configuration parameter on the target Domino server (in SiteMinder 4.x and 5.x) or centrally on the Policy Server (SiteMinder 5.x). This parameter is called DominoLookupHeaderForLogin, and it needs to be enabled, as follows:

DominoLookupHeaderForLogin="Yes"

This parameter ensures that the webagent performs a name lookup call to the underlying Domino Directory, supplying the value specified in DominoUseHeaderForLogin as the key. If both the LDAP directory and the Domino Directory contain the EmployeeID of the user, then this can be used as the key to perform the user lookup by completing the following:

  1. If the user logs into SiteMinder with his employee ID, there is no need to set any response. Otherwise, configure a response (on the Policy Server) for the Domino-related realm. Set the response to be the LDAP attribute, for instance, EmployeeID.
  2. (optional) Associate the newly created response with the realms in the defined policy for the Domino webagent(s).
  3. On the target Domino server, add the following parameter to the webagent configuration file (webagent.conf): DominoUseHeaderForLogin="HTTP_EMPLOYEEID" if EmployeeID is the response; DominoUseHeaderForLogin="HTTP_SMUSER" if the user logs into SiteMinder with his EmployeeID.
  4. On the target Domino server, add the following parameter to the webagent configuration file (webagent.conf):DominoLookupHeaderForLogin="YES"
  5. Ensure that the value of EmployeeID appears in the Person document for the user in the Domino Directory.

Because the identity is Domino-based, this implies that Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing should be using the Domino Directory as their user registry for user lookups to build the ACL or awareness. See also the previous section describing the identity/directory patterns.

Scenario 5

In this scenario:

  • There is either an existing Domino infrastructure, but no Domino LDAP for the SiteMinder infrastructure or no existing Domino infrastructure.
  • There is an existing LDAP directory that SiteMinder uses.
  • You want your applications to use Domino user names.
  • Names are not looked up in the local Domino Directory.
  • You can add attributes to the LDAP directory.

Because you decided to change the LDAP directory, you can extend the LDAP schema to include the following:

  • A Domino name in the format CN=Albert Einstein/OU=Physicists/O=Scientists stored as an attribute for every person entry in LDAP that needs to access Lotus Team Workplace and Lotus Instant Messaging and Web Conferencing with SiteMinder SSO.
  • Lotus Instant Messaging and Web Conferencing Home Server name of the format CN=LIM/O=Scientists. This is a requirement if the Lotus Instant Messaging and Web Conferencing server is using the LDAP directory as the user registry and your environment has more than one Lotus Instant Messaging and Web Conferencing server.

After successful propagation of the Domino name (in our example, we refer to it as Domino DN) for the user entries in the LDAP Directory, you can implement the following to perform a name translation to a Domino-specific name instead of the LDAP DN at the webagent level per target Domino server.

  1. Configure a response (on the Policy Server) for the Domino-related realm. Set the response to be the LDAP attribute; in this instance, it is Domino DN.
  2. Associate the newly created response with the realms in the defined policy for the Domino webagent(s).
  3. On the target Domino server, add the following parameter to the webagent configuration file (webagent.conf): DominoUseHeaderForLogin="HTTP_DOMINODN"

In this scenario, users are authenticated by SiteMinder as their LDAP DN (for example, uid=emc2,ou=physicists,o=scientists). When they access any Domino resources (on a Domino server that has this setup), they are identified by the webagent as their Domino name (for instance CN=Albert Einstein/OU=Physicists/O=Scientists).

Because the identity is Domino-based, this implies that Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing should be using the Domino Directory as their user registry for user lookups to build the ACL or awareness.

Scenario 6

Finally, scenario 6 applies when:

  • There is either an existing Domino infrastructure, but no Domino LDAP for the SiteMinder infrastructure or no existing Domino infrastructure.
  • There is an existing LDAP directory that SiteMinder uses.
  • You want your applications to use Domino user names.
  • Names are not looked up in the local Domino Directory.
  • You cannot add attributes to the LDAP directory.
  • You can modify the Domino Directory.

Because you want to modify the Domino Directory to assist name resolution, you can modify the Person document for a given user to add the LDAP DN in a Domino format. The user DN uid=emc2,ou=physicists,o=scientists is entered as uid=emc2/ou=physicists/o=scientists. This entry is secondary to existing entries in the user name (FullName field) of the Person document. This ensures that, although the webagent sets the authenticated user to be the LDAP DN of the user, Domino resolves the First name entry in the FullName field of the user’s Person document in the Domino Directory:

Figure 6. Person document
Person document

The identity is Domino-based. This means Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing should be using this Domino Directory as their user registry for user lookups to build the ACL or awareness.

If all the criteria listed previously in this scenario apply to your environment, but modifying the Domino Directory, you should probably reconsider your choices and adapt your environment to conform to one of the six scenarios discussed in this article.


Summary

SiteMinder provides an SSO environment across the enterprise, including Domino and other Lotus collaboration products. Companies considering SiteMinder-enabling their Domino environments need to evaluate their options before embarking on this venture. The key factors to consider when planning this are user directory, user identity, and whether or not this identity will differ within the SSO environment. This article shows several potential paths to consider when contemplating an SSO environment for Domino, Lotus Team Workplace, and Lotus Instant Messaging and Web Conferencing using SiteMinder.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into IBM collaboration and social software on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Lotus, Security
ArticleID=87939
ArticleTitle=Netegrity SiteMinder and Domino-based collaborative services
publish-date=12222003