Corporate operations today are getting increasingly automated, relying on a wide range of enterprise applications. These include HR databases, CRM, ERP, corporate directories, and many more. While these applications help to streamline business processes, they also create an environment where user data is often highly fragmented and difficult to manage.
Netegrity SiteMinder is a leading provider of security software solutions that securely manage identities and their access to enterprise information assets. SiteMinder provides single sign-on (SSO) functionality across single and multiple cookie domains, simplifying the use of applications across different Web servers and platforms. It also provides policy-based centralized control of user authentication and access management. Lotus Document Manager 7 (formerly Domino.Doc) supports Netegrity SiteMinder as an authentication mechanism. Users can access Document Manager libraries via the Notes client, Web browsers, and integrated applications in computing environments where SiteMinder is used to administer single sign-on (SSO) services.
This article helps you to understand Netegrity SiteMinder basic and forms-based authentication schemes when configured with Domino. It explains how support for these authentication schemes was implemented in Domino Document Manager 7.0. This article is based on the author's experiences while implementing support for SiteMinder authentication in Domino Document Manager 7.0. Developers interested in delegating the authentication process for their Domino application to SiteMinder (and thus leveraging its single sign-on functionality) will find this article helpful. We assume you're an experienced developer, familiar with Domino Document Manager.
The three major components of SiteMinder are:
- Policy Server
- Web Agent
- User Directory
The SiteMinder Policy Server is the controlling server for protecting sites. It detects URLs, challenges for credentials of protected URLs, communicates with the LDAP user directory for authenticating users, and communicates with the Web agent DSAPI plugin for Domino URLs. The Web agent DSAPI plugin communicates with SiteMinder to authenticate users.
The SiteMinder Web agent is a software component that controls access to any application or resource that can be identified by a URL. SiteMinder Web agents work with the Netegrity Policy Server to authenticate and authorize users for access to Web server resources. A SiteMinder Web agent is integrated with a Web server. The agent intercepts requests for a resource and determines whether or not the resource is protected by SiteMinder.
The Netegrity SiteMinder Web agent for Domino is implemented as a DSAPI. A DSAPI application can register for a variety of server events, so that the application is called whenever the particular event occurs. When a DSAPI application is called to potentially handle an event, it is passed the event, a context, and a data structure to hold any memory that the DSAPI application may need to allocate and use. Two events that the Netegrity Web agent registers are for handling raw URL requests (kFilterRawRequest) and for authentication (kFilterAuthUser).
A user directory in SiteMinder is an object that contains details for connecting to an existing user directory that resides outside of SiteMinder. User directories store user data, including organizational information and credentials such as passwords. The Policy Server user interface allows you to configure connections to existing user directories. The Policy Server uses these connections to verify user identities and retrieve user attributes contained in the directories. The Policy Server supports LDAP, Microsoft SQL Server, Oracle, and custom user directories.
The following steps occur when a user tries to access a protected resource on a Domino server configured to use SiteMinder authentication:
- The user requests a resource through a Web browser.
- This request is received by the Web server and is intercepted by the SiteMinder Web agent.
- The Web agent determines whether or not the resource is protected, and if so, gathers the user's credentials and passes them to the Policy Server.
- The Policy Server authenticates the user against user directories, then verifies whether or not the authenticated user is authorized for the requested resource, based on rules and policies contained in the Policy Store.
- After the user is authenticated and authorized, the Policy Server grants access to protected resources and delivers privilege and entitlement information.
Figure 1 illustrates this process:
Figure 1. SiteMinder authentication process
Let's take a closer look at step 3 in this process, where the Web agent intercepts user requests for resources and checks with the Policy Server to determine whether or not the requested resource is protected. If the resource is unprotected, the access request proceeds directly to the Web server. If the resource is protected, the following occurs:
- The Web agent checks which authentication method is required for this resource. Typical credentials are name and password.
- The Web agent challenges the user for credentials.
- The user responds with the appropriate credentials.
- The Web agent passes the credentials to the Policy Server, which determines whether or not the credentials are correct.
- If the user passes the authentication phase, the Policy Server determines whether or not the user is authorized to access the resource. After the Policy Server grants access, the Web agent allows the access request to proceed to the Web server.
Figure 2 shows the logic flow of this process:
Figure 2. Authentication flowchart
SiteMinder authentication schemes
Authentication schemes provide a way to collect credentials and determine the identity of a user. SiteMinder supports a variety of authentication schemes. These range from basic user name/password authentication and HTML forms-based authentication, to digital certificate and token authentication.
In this section, we begin with a brief introduction about basic and forms-based authentication schemes. We then discuss the details of how a client that uses HTTP for communicating with the server application that is configured for single sign-on with SiteMinder should handle the authentication process, and how to acquire the SiteMinder cookie so that it can participate in the SSO environment provided by SiteMinder.
Basic authentication identifies a user based on a user name and password. The user’s identity is stored in a user directory. With the basic authentication scheme, the Policy Server locates a user in a directory based on the user name, then verifies that the password matches the one saved in the user directory (in other words, it binds the user to the directory). If the user name and password supplied by the user match the data in the user directory, SiteMinder authenticates the user.
To use the Basic authentication scheme, the following prerequisites must be met:
- The client user name and password information must exist in a user directory.
- A connection to the user directory must be configured using the SiteMinder User Directory dialog box.
The authentication process for a client using SiteMinder basic authentication with Domino Document Manager 7 is as follows:
- From the client application, the user tries to access an application or resource on the Domino Document Manager server, which has been configured to use Netegrity SiteMinder basic authentication.
- The server hook code notes that there is an event handler (the SiteMinder Web agent) registered for handling requests. The server calls out to the Web Agent to handle this request.
- The SiteMinder Web agent inspects the URL of the application or resource, notes that it is protected, and looks for the Netegrity cookie smsession. Because the user is not authenticated, the cookie does not exist, so the HTTP status code "401 access denied/unauthorized" is returned. The HTTP response includes a WWW-Authenticate header specifying the authentication method and realm (for example, WWW-authenticate:basic realm="DocMan”).
To implement SiteMinder basic authentication for your Domino Document Manager application, you must add code to it that can detect this error and prompt the user for a user name and password. After the user submits the user name and password, you need to send an HTTP GET request with the FTTP header "Authorization: Basic” set with the Base64 encoded value of the user name and password.
The HTTP status code '401 Access Denied' could also be returned when the session has expired and the cookie needs to be refreshed. If you want to prompt the user for a user name and password when the session has expired, check for the status code 401, and when it occurs always display the login dialog. But if you only want to prompt the user for a user name and password once and refresh the cookie behind the scenes, you need to store the user name and password globally, check whether or not the user name and password exists, and if it does, use it to refresh the cookie (that is, send an HTTP GET request with the basic authorization header and the Base64 encoded value of user name and password).
If the request succeeds, you must query the response for the smsession cookie, and if it is present retrieve the cookie value. Then set this cookie value in the session for the original request and resend the request. When the Web agent looks for the cookie, it will find a valid one and the user will be authenticated and granted access to the requested resource. After the client application has the smsession cookie, it can participate in the SSO environment provided by SiteMinder.
HTML forms-based authentication
HTML forms-based authentication provides a method for authentication based on credentials gathered in a custom HTML form. This flexible means of credential collection allows a customer to:
- Provide a branded look, including a company logo if desired.
- Substitute custom labels for user name and password collection.
- Provide authentication based on credentials that include user attributes in addition to the user name and password.
- Provide authentication based on credentials other than a user name and password (via user directory attributes). In this case, an authentication scheme library on the Policy Server machine maps the user’s data to a DN. By doing this, the Policy Server can match an attribute list to the appropriate values in a user directory.
SiteMinder credential collector is an application within the Web agent that gathers specific user credentials to authenticate a user. The credentials gathered by the credential collector are based on the type of authentication scheme configured for a particular group of protected resources. For forms-based authentication, credentials are collected by the Forms Credential Collector (FCC) process. The default extension for FCC files is (naturally enough) 'FCC'. The FCC process files are composed in a simple mark-up language that includes HTML and some custom notation. This file contains the custom form definition and additional information that the FCC uses to process HTML forms-based authentication. The FCC extracts credentials that a user enters in the custom form generated from the FCC file. For example, the Web agent is installed with a form called login.fcc, which we can customize and use for login purposes (more on this later).
SiteMinder displays the contents of the .unauth file to users who exceed the maximum number of failed authentication attempts specified by the authentication scheme. One .unauth file should exist for each FCC file. For example, if you have a login.fcc file on a Web server, you should also have a login.unauth file in the same location. If a smerrorpage variable has been defined in the FCC file, the .unauth file is not required. For the Domino server, the login.fcc and other forms are stored in the domino/html/siteminderagent directory.
To use HTML forms-based authentication with Domino Document Manager, the following prerequisites must be met:
- A customized FCC file must reside on a Web agent server in the cookie domain in which you want to implement forms-based authentication. Netegrity provides sample FCC files under the Samples\Forms subdirectory where you installed your Web agent. For example, <SM_Web_Agent_Install_Dir>\Samples\Forms.
- A customized .unauth file must reside on the Web agent server unless the FCC file uses the smerrorpage directive.
- A connection to the user directory must be configured using the SiteMinder User Directory dialog box.
Figure 3 illustrates the HTML forms-based authentication process:
Figure 3. HTML forms-based authentication
As figure 3 shows, the following steps take place during HTML forms-based authentication:
- A user requests a resource contained in a realm protected by HTML forms-based authentication.
- The Web agent contacts the Policy Server and determines that the user’s request must be redirected to the credential collector.
- The Web agent redirects the request to the URL of the credential collector file.
- The Forms Credential Collector (FCC) displays the form described in the FCC file in the user’s browser.
- The user fills out the custom form and posts (submits) the form. The FCC processes the credentials.
- The FCC logs the user into the Policy Server. The Policy Server returns user session data to the FCC.
- If the user is authenticated, the FCC creates a session cookie, passes the session cookie to the browser, and redirects the user to the resource that was originally requested.
- The user uses the session cookie to authenticate. Then, the Web agent handles user authorization.
The FCC can interpret a number of special name/value pairs:
- smenc contains information that tells the browser what language encoding to use.
- smlocale is the language used in the HTML forms that collect user information or display status messages.
- username is the name to use as the login user name.
- password is the password to use to perform the login.
- target is the resource to access after login.
- smauthreason is the reason code associated with a login failure.
- smusrmsg contains the text that describes why the user was challenged or failed to login.
- smagentname is the agent name used for logging the user in.
- postpreservationdata is the data that a user submits through a post request.
- smerrorpage is the page to which the user's browser will be redirected if there is an error on a post to the custom form.
- smretries defines the maximum number of allowed failures when attempting to login.
The process for a client using SiteMinder HTML forms-based authentication is as follows:
- From the client application, the user tries to access an application or resource on the Domino Document Manager server that has been configured to use SiteMinder HTML forms-based authentication.
- The server hook code notes that the SiteMinder Web agent is registered for handling requests. The server calls out to the Web agent to handle this request.
- The Web agent inspects the application/resource URL, notes that it is protected by HTML forms-based authentication, and looks for the Netegrity cookie smsession. The cookie does not exist here, so the agent redirects the request to the URL of the credential collector file. This produces an entry in the Domino Document Manager server's HTTP log; the following is an example:
GET /domdoc/SiteMinderTestLib.nsf/ DMGetCabinetsV4?OpenAgent HTTP/1.1 User-Agent: Lotus Domino.Doc Host: ddocqe2.in.ibm.com:8080 Cache-Control: no-cache Cookie: client=1; msp=alreadyOffered; OIAccessServletVer1.01=NH34J5ZDX32XO3WDWPGCGKI1088763852763147 HTTP/1.1 302 SM redirectServer: Lotus-DominoDate: Fri, 16 Jul 2004 06:33:03 GMTConnection: closeSet-Cookie: SMDOMINODATA=+cTBS2A7YxWIq3xVdNdDdho76QNjV54PEAp25HrCj8hcfH ROBlO05TB/N9T5y4/; path=/; domain=.in.ibm.com Location: http://ddocqe2.in.ibm.com:8080/siteminderagent/forms/login.fcc?TYPE=33 554433&REALMOID=06-5b44daa9-e3b3-4694-b401- bfd3e8edca0a&GUID=&SMAUTHREASON=0&METHOD=GET &SMAGENTNAME=$SM$Ojd6R9kXODDOvjLWmOP2s6uSs3O%2bzBsfCVYx6 Pxjpxer%2fuj5z7uNXQ%3d%3d&TARGET=$SM$http%3a%2f%2fddocqe2%2ein% 2eibm%2ecom%3a8080%2fdomdoc%2fSiteMinderTestLib%2ensf%2fDMGetCabine tsV4%3fOpenAgent
The Location tag contains the SiteMinder login form URL to which users will be redirected to authenticate. In this URL is a tag called TARGET, which contains the original request that will be sent to the Domino server by the SiteMinder Web agent after your application provides the correct authentication information.
To get the smsession cookie in the client application, you must add code to your application that posts the login.fcc URL to the FCC with the SiteMinder-specific attributes and user credentials. The code should search through the login form (login.fcc) in the HTTP response string for special SiteMinder-specific tags the FCC can process, and get their values.
Your application can then extract the value of the Location tag and store it in a variable, for example loginURL. This is the URL that you need to post to the FCC with the SiteMinder-specific attributes and user credentials, so that the user will be authenticated and a valid smsession cookie will be generated. The HTTP log helps explain the default SiteMinder tags required while posting the login form. The usual format of the post data while posting the login URL is as follows
SMENC=ISO-8859-1&SMLOCALE=US-EN&USER=wpsadmin15 &PASSWORD=wpsadmin15 target= http://ddocqe2.in.ibm.com:8080/domdoc/SiteMinderTestLib.nsf/ DMGetCabinetsV4?OpenAgent &smauthreason=0&smagentname=%24SM% 24Ojd6R9kXODDOvjLWmOP2s6uSs3O%252bzBsfCVYx6Pxjpxer% 252fuj5z7uNXQ%253d%253d&postpreservationdata=$$postpreservationdata$$
You can write a utility function called GetSMTagValue(String Tag) that returns the value of the requested SiteMinder tag from the login.fcc in the response data buffer. Construct the post data string by using the function GetSMTagValue to get the values of SMENC and SMLOCALE. Next, append to it the user and password tags with values. Then use the function GetSMTagValue to get the values of target, smauthreason, smagentname, and postpreservationdata. Post the login URL with the preceding post data. The FCC processes the credentials and other customized login form attributes, if any. If the user is authenticated, the FCC creates the smsession cookie and the user will be automatically redirected to the target URL (which is the resource that was originally requested).
Sample Login.fcc form
To demonstrate the concepts discussed in this article, we have provided a sample Login.fcc form you can use for forms-based authentication with Domino Document Manager 7. The code for Login.fcc is contained in this sidefile. Note that in the code, SiteMinder tags that you must parse and obtain the values from to post in the login form are highlighted in bold text.
In this article, we have explained the basics of how SiteMinder basic and forms-based authentication work. We have also provided you with code for a sample Login.fcc form that you can copy and use to implement forms-based authentication in your own Domino Document Manager 7 environment. We hope you found this article useful -- please let us know what you think!
- The code for our sample Login.fcc is contained in this sidefile.
- The developerWorks: Lotus article, "Netegrity SiteMinder and Domino-based collaborative services," describes how to set up Netegrity SiteMinder with other Lotus Domino products.
- For more information on what's new in Notes/Domino 7, see the article, "New features in Lotus Domino 7.0 Beta 3."
- Get involved in the developerWorks community by participating in developerWorks blogs.
Dig deeper into IBM collaboration and social software on developerWorks
Experiment with new directions in software development.
Software development in the cloud. Register today to create a project.
Evaluate IBM software and solutions, and transform challenges into opportunities.