Monday, July 20, 2009

Single SignOn from the operating system desktop to WebSphere Portal

How To:
A browser can automatically authenticate a user against the WebSphere Portal, based on the login to the operating system desktop. This feature is sometimes requested by customers for employee portals.


Warning: Some of the configurations described here are not officially supported. For details, see the Hint and Tip document 1104689: "Basic authentication is not supported as a login mechanism for WebSphere (R) Portal". These example configurations are intended for demo and proof of concept projects. For production environments, official support needs to be confirmed or negotiated on a case-by-case basis.


The Internet Explorer (IE) web browser can automatically use current or stored passwords to log in to web sites using one of the three HTTP authentication schemes basic, digest, or NTLM authentication. If the portal is configured to use one of these schemes instead of the default form-based authentication, the users do not have to log in to the portal explicitly.
This document describes three different basic architectures of how to achieve this, along with some variations in the configurations. The approaches differ in that the user is authenticated by using one of the three following components:

An authentication proxy, such as Tivoli Access Manager (TAM)
The WebSphere Application Server
An HTTP server

The authentication proxy solution is the only one to provide a viable alternative for production use. The other two approaches may be useful for demos and proofs of concept. Tests have been conducted using WebSphere Application Server Version 4.0 and WebSphere Portal Version 4.2, but the configurations described here can be applied to other versions as well.

This document is structured as follows:

The following section considers client requirements.
The next section after that gives background information required to understand the server discussion.
The last section addresses the server side architecture, with a subsection dedicated to each of the three approaches.

Browser and Platform Considerations

Internet Explorer on the Windows platform tries to automatically log in to selected web sites by using a stored user ID and password, or the user ID and password of the current user of the operating system. The default security settings allow this automatic login for the intranet zone and for trusted sites. If the HTTP server of the portal is found to belong to the intranet zone, nothing else has to be done. Otherwise, it has to be added explicitly to the intranet zone or, if HTTPS is used, to the list of trusted sites. This has to be done for each client machine. Due to security considerations, automatic login should never be used outside of an intranet or secure connection. It has not been verified whether IE on Apple MacIntosh computers provides the same features for automatic login.
Mozilla, as an example for other browsers, never logs in automatically, but prompts the user with a password dialog. If the password manager stores the user ID and password for the site, a single click is sufficient for login. While this does not provide an SSO experience, the portal will at least remain accessible for non-IE users with little extra effort. However, Mozilla supports the NTLM authentication mechanism only on Windows platforms.

The Authentication Problem

Requests and Sessions

Web applications such as the portal receive individual HTTP requests from all users. Each request for a protected resource, such as the protected area of a portal, needs to be authenticated individually. This means that a component is required to verify the identify of the user who sent the request, for example by checking a password. An HTTP session is constituted by all requests from a single user. Requests of a particular session are typically recognized by means of a cookie, which holds the session ID and is sent with each request.
The usual setup of the portal prompts the user for the password once, when the user enters the protected area of the portal. The user provides the user ID and the password. The server verifies the password and provides the LTPA cookie for that user ID and session. The LTPA cookie is sent with all subsequent requests in that session and proves that the user has been identified. The password itself is sent only once.

The authentication methods basic, digest, and NTLM mentioned above do not rely on a cookie or session. They add authorization data to each request, and the authorization can be checked for each request again. This poses a problem especially in the case of basic authentication, where the authorization data is the user ID and password in clear text. Each request exposes the password to eavesdroppers. Note that the portal still needs a session cookie, even if authentication is achieved without the LTPA cookie by one of these methods.

Combining per-request and cookie-based authentication schemes has the following consequences:
After the initial authentication, the browser continues to send the authentication data along with the LTPA cookie in each request. When the user logs out of the portal, the LTPA cookie is deleted, but the authentication data is still sent by the browser for subsequent requests to the portal. The next access to the protected area of the portal logs the user back in with the same user ID and password as before. For the scope of this document, that is exactly the intended Single SignOn behavior. In general, however, some users might want to log out and log back in under a different user ID, This can be the case, for example, if they have both a regular user and an administrator account. In that case, the browser program needs to be closed and restarted to remove the authentication data.

User Repositories

Automatic login to the portal involves up to three repositories where user data is stored:

First, there is the browser which selects the appropriate user ID and password for the site.
On the other end is WebSphere Application Server, which is configured to look up users in an LDAP directory.
Optionally, there is TAM or the HTTP server which perform the authentication on behalf of WebSphere Application Server.
In order to provide a seamless SSO experience, these user repositories need to be synchronized.
IE tries to use either the current user's ID and password to log in to a web site, or some user ID and password stored previously in the password manager. If neither approach succeeds, a password dialog is presented to the user. Other browsers typically have a password manager as well. The repository of the password manager runs out of synchronization each time the portal password is changed. For the next login, the user has to enter the new password explicitly. The password manager then stores the new password.
Assuming a password lifetime of 6 months, the manual update of the password manager repository is usually acceptable. If not, the portal and the desktop have to rely on the same user repository, which is probably Microsoft Active Directory, or maybe a Samba server that synchronizes with an LDAP directory.

Approaches to Single SignOn

As mentioned in the overview, all approaches rely on activating an authentication mechanism that can be handled by a browser automatically. In other words, the authentication is moved from the application server level (form-based) to the HTTP level. To log in to the portal, the protected area, by default under the path /wps/myportal, needs to be accessed. The login link on the public portal pages needs to be modified so it points to the protected area rather than to a public login page. There is another reference to the login page in the portals deployment descriptor (see subsection "Single SignOn via WebSphere Application Server Security" below). That should be changed to point to a publicly accessible error page, as it is not used if Single SignOn is configured correctly.
The following subsections discuss some alternatives for protecting the /wps/myportal area on the HTTP level, and how to transfer the authentication on the HTTP level back to the application server level. The latter basically means that WebSphere Application Server has to be informed about the successful user authentication.

Single SignOn via an Authentication Proxy

This is the only approach that looks promising as an architecture suitable for production use. It also is the most complex setup. The following description is an architecture overview rather than an installation guide. In the following graphic, you can see the major components directly involved in processing a request.

The components in red come with TAM or a third-party authentication proxy. They consist of the authentication proxy itself, a plugin installed in the HTTP server, and a so-called trust association interceptor (TAI) installed with WebSphere Application Server. When the request from the browser comes to the HTTP server, the plugin decides whether the user needs to be authenticated. If so, the plugin interacts with the authentication proxy to authenticate the user. This step usually involves more messages between the plugin, browser, and authentication proxy than are shown in the graphic.

Only when the user is authenticated successfully, the original request passes through the plugin and HTTP server to WebSphere Application Server. There, the TAI indicates to WebSphere Application Server that the request has already been authenticated. When an authentication proxy is involved, WebSphere Application Server is configured to use the same user repository as the authentication proxy itself.
Authentication proxies typically provide a selection of authentication options, including basic and digest authentication, form-based authentication, certificate-based authentication, and more. Here, one of the HTTP level authentication mechanisms has to be configured for protecting /wps/myportal. If you use more complex schemes, the authentication may be requested from a different HTTP server, so that the browser does not send authentication data for the subsequent requests to the portal.
Current versions of TAM support NTLM as an authentication option and Active Directory as a user repository. This way, it is possible to create an installation where the client (and therefore the browser), the authentication proxy and WebSphere Application Server use a single user repository.

Single SignOn via WebSphere Application Server Security

The second approach is simple, but has some restrictions. You can configure WebSphere Application Server and the portal to use basic authentication instead of form-based authentication. After you install the portal, search for the deployment descriptor of the WPS web application. Its path should be something like


where $WAS_HOME stands for the installation directory of WebSphere Application Server. Towards the end of the deployment descriptor file, you find the section where the authentication mechanism is configured. Change it from form to basic and restart the portal.
On the first access to /wps/myportal, WebSphere Application Server sends a reply that basic authentication is required. The browser sends the following request with authentication data. WebSphere Application Server then checks the user ID and password against its user repository, and, if the password is correct, creates the LTPA cookie.
This approach has several drawbacks:

This configuration is not officially supported.
Only WebSphere Application Server knows that the user is authenticated. It is not possible to include resources served directly by the HTTP server into the same security domain, or at least not without the requests taking a round trip through WebSphere Application Server, which degrades performance.
Finally, this configuration has been found to cause problems when tested with IIS as the HTTP server. It seemed that IIS tries to verify the authorization data although not configured to do so. As the user repository was only configured for WebSphere Application Server, all requests were either rejected by IIS or by WebSphere Application Server.

Single SignOn via HTTP Server Security

The third approach achieves a balance between the other two. It uses the built-in capabilities of the HTTP server to authenticate the user and a custom TAI to indicate the succesful authentication to WebSphere Application Server. On the one hand it is quite easy to implement a custom TAI that enables successful login. On the other hand it is quite difficult to implement one that is resistent against attacks. That is why this approach is suitable only for demo and proof of concept use. In a production environment, security must be provided by reliable components, such as the TAI that ships with TAM.

HTTP servers come with various options for user authentication that differ in the type of authentication as well as in the user repository on which they are based. If the HTTP server is configured to use a different user repository than WebSphere Application Server, both repositories must be kept synchronized manually. This may be feasible for demos or proofs of concept which involve a small set of test users who are known ahead of time. Self-registration cannot be implemented without a common user repository. The remainder of this section gives an overview of the options provided by Apache, IBM HTTP Server, and IIS.

IIS supports basic and NTLM authentication of the users in a domain. Active Directory can be used as the common user repository for IIS and WebSphere Application Server. The drawback of IIS is that security is managed based on virtual directories. The public and protected areas of the portal are not listed as virtual directories. Therefore, the whole server has to be protected, which disables anonymous access to public portal pages. Public information about the NTLM authentication mechanism is scarce, but the user ID that needs to be retrieved by the TAI should be easily accessible in the authentication data.

Apache in both Versions 1.3 and 2.0 comes with a selection of authentication modules. The standard modules for basic and digest authentication rely on manually updated files as the user repository. Version 2.0.41 and above come with an experimental module that performs basic authentication against an LDAP directory. Third-party LDAP authentication modules for version 1.3 exist, but there are dependencies on proprietary LDAP libraries, issues with the licenses of the authentication modules, and the problems with having to compile the modules for the respective platform. A third party NTLM authentication module for Apache 1.3 is available, but it has not been updated for a while, although security problems have been reported. The license and compile issues mentioned above for third-party authentication modules apply to the NTLM authentication module as well.

The IBM HTTP Server (IHS) is based on Apache and provides the same authentication modules. Additionally, IHS in both Version 1.3 and 2.0 ships with a module that supports basic authentication against an LDAP user registry. The configuration of the IBM LDAP authentication module is more complex than for the Apache 2.0 standard module, but it also provides more functionality. The configuration is described in the Info Center for IHS on the IBM web page, though not in the Apache manual that is installed automatically with IHS. You have to edit the sample ldap properties file $IHS_HOME/conf/ldap.prop.sample and then reference that file from within the httpd.conf file in the same directory.

Programming guidelines and detailed installation instructions for TAIs are available in the InfoCenter for WebSphere Application Server. To install a TAI, you have to put the implementation in the class path, for example in $WAS_HOME/classes. Then modify the file and enable TAI from the security center of the WebSphere Application Server administration console.