Wednesday, May 30, 2007


What is Single Sign On?

SSO is an authentication system that permits users to access multiple servers in a domain through
a single point of entry. When SSO is deployed in the portal, user sessions are authenticated
transparently by an SSO service against authentication sources commonly deployed in the
enterprise, such as LDAP or Active Directory.
Enables communication of user identity without requiring the user to re-authenticate
User identity is passed across servers, networks, or applications
Secure transition through a distributed application is transparent to the user

Benefits of SSO

Improved User Productivity
Better Security
Lower administrative / helpdesk cost

Why should SiteMinder be important to you?

If you have an intranet or plan to develop one, you will need provide a
way to use the internet to deliver ubiquitous access to your policies
and procedures, personnel and employment announcements and
other "Agency centric" intranet information.

In many environments, but particularly in portal environments, it is desireable to have a user challenged to authenticate themselves only once over a set of web applications deployed on a particular virtual host. This can be accomplished by nesting an element like this inside the Host element for this virtual host:


Single Sign On Rules

* All web applications configured for this virtual host must share the same Realm. In practice, that means you can nest the Realm element inside this Host element (or the surrounding Engine element), but not inside a Context element for one of the involved web applications.

* As long as the user accesses only unprotected resources in any of the web applications on this virtual host, they will not be challenged to authenticate themselves.

* As soon as the user accesses a protected resource in any web application associated with this virtual host, the user will be challenged to authenticate himself or herself, using the login method defined for the web application currently being accessed.

* Once authenticated, the roles associated with this user will be utilized for access control decisions across all of the associated web applications, without challenging the user to authenticate themselves to each application individually.

* As soon as the user logs out of one web application (for example, by invalidating or timing out the corresponding session if form based login is used), the user's sessions in all web applications will be invalidated. Any subsequent attempt to access a protected resource in any application will require the user to authenticate himself or herself again.

* The Single Sign On feature utilizes HTTP cookies to transmit a token that associates each request with the saved user identity, so it can only be utilized in client environments that support cookies.

What's involved?

A small piece of software resides on your web server. It understands
what pages are part of your intranet site(s) and intercepts url requests
for them. These requests are held and a transaction is sent to a
policy server that handles the authentication through LDAP to the
NDS tree. The user is given a login page and asked for an ID and
password. Once authenticated, the user's request for the protected
intranet site / page is then sent back to the agency intranet web

Who controls the agent software?
How is ITS involved?

The agency controls the rules and policies implemented by the agent
and have administration rights to change it's behavior. ITS will assist
you in setting up the agent that communicates with the policy server.
ITS has no continuing involvement or control.

How to setup your site so it uses SiteMinder Security.

There are 9 Steps in this process. Prerequisets You must use IIS, or Netscape web
servers. Are you protecting an existing web server that can’t go down? If so skip to the
second set of instructions.
1st Set of instructions
Step 1. Obtain a copy of the Siteminder Agent.
Step 2. Install your web server.
Step 3. Publish your content to the web server.
Step 4. Install your web agent.
Step 5. Work with ITS to create the Agent, and Realm configuration.
Step 6. Login to Siteminder.
Step 6. Setup your rules.
Step 7. Setup your policies.
Step 8. Setup any responses required and associate them with rules in the policy.
Step 9. Enable the Webagent.
Netscape: Edit the Webagent.conf
IIS: Use Siteminder agent Util.
2nd Set of instructions
Step 1. Obtain a copy of the Siteminder Agent.
Step 2. Create a new web server with a new IP address.
Step 3. Publish your site to the web server.
Step 4. Create an entry in your host file with a test name. Ie
Step 5. Install your web agent.
Step 6. Work with ITS to create the Agent, and Realm configuration.
Step 7. Login to Siteminder.
Step 8. Setup your rules.
Step 9. Setup your policies.
Step 10. Setup any responses required and associate them with rules in the policy.
Step 11. Enable the Webagent.
Netscape: Edit the Webagent.conf
IIS: Use Siteminder agent Util.
SiteMinder admin URL

Sample Web agent configuration file
# WebAgent.conf - configuration file for SiteMinder Web Agent
# Web Agent Version=351
# Web Agent InstallPath=
/opt # Do not remove or edit the preceding lines,
or you may not # be able to perform


SiteMinder components

The three major components of SiteMinder are:

  • Policy Server
  • Web Agent
  • User Directory

Policy Server

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 URLs. The Web agent DSAPI plugin communicates with SiteMinder to authenticate users.

Web agent

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 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).

User directory

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.

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.

To use HTML forms-based authentication, 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, \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.
The following steps take place during HTML forms-based authentication:
  1. A user requests a resource contained in a realm protected by HTML forms-based authentication.
  2. The Web agent contacts the Policy Server and determines that the user’s request must be redirected to the credential collector.
  3. The Web agent redirects the request to the URL of the credential collector file.
  4. The Forms Credential Collector (FCC) displays the form described in the FCC file in the user’s browser.
  5. The user fills out the custom form and posts (submits) the form. The FCC processes the credentials.
  6. The FCC logs the user into the Policy Server. The Policy Server returns user session data to the FCC.
  7. 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.
  8. 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.
Configuring Netegrity SiteMinder Web Agent (5.5 SP3 or 6.0) on Linux/Unix

To set up SiteMinder Web Agent:

1. If you have not done so already, on the host computer , install Apache HTTPd.
2. On the portal host computer, install:

Either these components:
* SiteMinder Web Agent 5.5
* SiteMinder Web Agent 5.5 Quarterly Maintenance Release (QMR) 6
* SiteMinder Web Agent 5.5 QMR 6 CR007

Or these components:
* SiteMinder Web Agent 6.0
* SiteMinder Web Agent 6.0 Quarterly Maintenance Release (QMR) 2
* SiteMinder Web Agent 6.0 QMR 2 CR005

For details on installing Netegrity SiteMinder components, refer to the Netegrity Customer Care Web site and Netegrity SiteMinder documentation.

For an example of installing the SiteMinder Web Agent, Web Agent QMR, and hotfix, see Knowledge Base article DA_236222, "Netegrity Siteminder 5.5 Web Agent Installation Tips."
3. Invoke the SiteMinder configuration utility, for example, from the command-line, enter:


When prompted, enter your preferences but be sure to specify the settings you configured in the previous section for the following objects:
* Policy Server IP Address
* Host Configuration Object name

When prompted, enter the location for the Apache Web server root directory, for example, /opt/httpd/.
4. Source the Netegrity environment script. From the command-line, enter:

source /opt/netegrity/siteminder/webagent/

5. Modify the Apache Web server httpd.conf configuration file to enable the SiteMinder Web Agent. The lines in the following excerpt show an httpd.conf file that enables the SiteMinder Web Agent:

LoadModule sm_module /opt/netegrity/siteminder/webagent/lib/

# SSO Configuration

SmInitFile /opt/httpd/conf/WebAgent.conf

Alias /siteminderagent/pwcgi/ "/opt/netegrity/siteminder/webagent/pw"

Options Indexes MultiViews ExecCGI

AllowOverride None

Order allow,deny

Allow from all

Alias /siteminderagent/pw/ "/opt/netegrity/siteminder/webagent/pw"

Options Indexes MultiViews ExecCGI

AllowOverride None

Order allow,deny

Allow from all

Alias /siteminderagent/ "/opt/netegrity/siteminder/webagent/samples/

Options Indexes MultiViews

AllowOverride None

Order allow,deny

Allow from all

##SITEMINDER .exe ##

AddHandler cgi-script .exe

##SITEMINDER .fcc ##

AddHandler smformsauth-handler .fcc

##SITEMINDER .scc ##

AddHandler smadvancedauth-handler .scc

##SITEMINDER .ccc ##

AddHandler smcookieprovider-handler .ccc

The lines that configure SiteMinder Web Agent must be before lines that include a Web application server configuration file, such as bea.conf.

6. Modify the following settings in /opt/httpd/conf/WebAgent.conf:
* Ensure: enablewebagent="YES"
* Add: ServerPath="/opt/httpd/conf/httpd.conf"

7. Restart the Apache Web server.

Configuring Netegrity SiteMinder Web Agent on (5.5 SP3 or 6.0) Windows

To configure SiteMinder Web Agent for your deployment:

1. Install the Web Agent setup program on the same host as the portal. See Configuring Netegrity SiteMinder Web Agent (5.5 SP3 or 6.0) on Linux/Unix for the supported Netegrity versions.
2. When setup is complete, you are prompted to complete the Web Agent Configuration Wizard. If you choose to run the wizard at a different time, click Start | Programs | SiteMinder | Web Agent Configuration Wizard to open the wizard.
3. When prompted, specify the settings you configured in the previous section for the following objects:
* Policy Server IP Address
* Host Configuration Object name
4. In the \IIS\bin\WebAgent.conf file, set the EnableWebAgent parameter to yes.

The real Scenario
Authentication is done the first time a user accesses a protected part of a Web site, just like a login. The HTTP 1.0 and 1.1 protocols define the steps a browser follows for authentication. Some of the steps are visible level to you and others are not. It is important to understand what happens during an authorization in order to understand what the Login Scenario measurements mean.
Authorization Process

The following simplified sequence will walk you through the authorization process and show you how what you see ties in with the authorization process:

1. When you click on a link or enter a URL in your browser your browser sends the requested URL to the Web server.
2. The Web server determines that you must be authenticated before it returns the resource at the requested URL. Typically, the authentication requirement is specified as part of the Web server's configuration or via an authentication/authorization product embedded in the Web server.
3. The Web server sends back a "401" HTTP response to your browser indicating that you are not authorized to see that requested resource (generally a Web page).
4. Your browser pops open a window and asks you to enter your user ID and a password.
5. After you enter your user ID and password, your browser stores them in memory and associates them with the protected space (called a realm ) containing the URL you requested.
6. Your browser then resends a request for the same URL but this time it includes an HTTP authorization header containing your user ID and password.
7. This time the Web server checks your user ID and password to see if they match the authentication information in the authentication system. If they do, you are authenticated.
8. Now that you have been authenticated, the authorization system checks whether or not you are authorized to access Web pages in the realm. If you are authorized, the Web server sends the Web page you requested.

Notice that the URL you clicked on or entered is actually sent twice (in steps 1 and 6). This means that the authentication system is used twice—first, it finds out that the requested URL requires the user be authenticated, then it processes the authorization header when the request is resent.

After the user is authenticated, the request is checked to see if the user is authorized to use the requested resource. The authorization check does not require any contact with the Web browser.

Once a user has been authenticated, the Web browser automatically sends the authorization header whenever the user requests a URL in a realm requiring authentication. So, the user will not see a window open up asking him or her to login again to a realm that has already been visited.