ShowTable of Contents
Jan-Paul Buchwald - Advisory IT Specialist IBM WebSphere Portal Lab Services
Matthias Falkenberg - Software Engineer - IBM WebSphere Portal and IBM Web Content Manager
With the release of version 6.1 the WebSphere Portal platform supports the remembering of users that have previously authenticated to the website from a particular client, such as a web browser. This function is based on an HTTP cookie also known as remember me cookie that holds information on the user in an encrypted fashion. This information allows WebSphere Portal to identify the user without the user performing an explicit authentication to the website.
In conjunction with step-up authentication, the remember me cookie can also be employed to trigger a transition of the identified user from the public portal area (e.g., /portal
context) to the protected portal area (e.g., /myportal
While the implementation of the remember me function combined with the step-up authentication feature accommodates for many use-cases, some scenarios might need additional work in terms of registering custom extensions with the WebSphere Portal server. Considering the out of the box capabilities as ground work, the public security APIs of WebSphere Portal allow solution developers to enhance the existing foundation to meet the requirements of custom scenarios.
With some well-known shopping platforms or other online services in mind, one might wish for an automatic login of a remembered user as soon as the user accesses the website. Furthermore, upon logging out, the user should become anonymous to the portal, that is, the user cannot be identified by the website for subsequent requests any longer.
A standard WebSphere Portal installation already enables various aspects of this scenario. But the default implementation of the remember me function and step-up authentication will perform a user login only when the remembered user issues an explicit request to the protected portal area. Until then, the user navigates the public area and only limited personalization features are available to provide content and functions specific to the identified user. After all, the user still acts as the Anonymous Portal User from a portal access control point of view.
Moreover, when a user accesses the protected portal area and logs out eventually, the remember me cookie remains valid per default. For some WebSphere Portal-based solutions the preferred behavior might be to revoke the remember me cookie when the user performs an explicit logout. In this case, the remember me cookie serves the purpose to log a returning user back in only if the user has navigated away from the website or has closed the web browser without logging out.
This authentication pattern is widely spread across solutions on the Internet and therefore might be an expected behavior for WebSphere Portal-based websites too.
Table 1 below summarizes the different user authentication states and the resulting portal area access and personalization capabilities. Table 1: Portal access control, step-up authentication, and remember me
From the portal access control perspective any unauthenticated user accessing the portal acts as the one and only Anonymous Portal User. This implies that all users navigating the public portal space see the very same portal artifacts. It contains all portal resources that are visible to the Anonymous Portal User. Predominantly, this refers to labels, pages, and instances of portlets that reside on these pages. In addition, web content that the Anonymous Portal User is allowed to read can be displayed by the Web Content Viewer (JSR 286) portlet in the public portal space.
However, if the user is identified by the remember me function there are limited personalization options. For instance, custom portlets can access the Puma profile of the identified user to read user profile attributes to perform a sort of personalization. Also web content displayed by the Web Content Viewer (JSR 286) portlet can be personalized by the use of the user name component that is aware of identified users and supports to render different markup for identified or authenticated users than for anonymous users.
The comprehensive personalization features, however, are only available to users that are fully authenticated from a portal access control perspective, which implies that the user navigates the protected portal space. This area contains portal artifacts that the current portal user has the permission to access. The dynamic site composition based on portal access control permissions can result in different labels, pages, and portlets being visible to different users. Additionally, the IBM Web Content Manager items presented to users can differ.
The comprehensive personalization also includes the availability of WebSphere Portal Personalization rules, and the option for users to personalize pages and instances of portlets residing on those pages.
Details of the solution
The proposed solution encompasses implementations of two WebSphere Portal SPIs, namely the session validation filter and the explicit logout filter. Both security filter implementations are configured using the WP AuthenticationService resource environment provider.
Session validation filter
The session validation plug-point is called for each request targeting the portal. It allows solution developers to plug custom code that is executed before the action and rendering phase in WebSphere Portal. In the context of the servlet request and response, the custom code can access all WebSphere Portal APIs and it can interrupt the processing of the request by performing a redirection.
For the scenario described in this article, the custom session validation filter class com.ibm.portal.sample.RememberMeSessionValidator
analyzes incoming requests and conditionally redirects the client to the protected portal area as depicted in Illustration 1 below.Illustration 1: Remember me session validator flow
The custom session validation filter implements two main conditions. It first checks whether or not the request targets the public portal area. Only if this is the case, the filter continues with the attempt to locate the remember me cookie in the request. To make sure, the filter works in customized environments, it can be configured to override its default settings for the public and for the protected portal servlet path and for the name of the remember me cookie (see also Configure the custom security filters).
If the initial conditions are not met, the default request processing of WebSphere Portal continues and the portal resource is delivered as usual. However, if the conditions are met, that is the request addresses a public portal resource and the client presents a remember me cookie, the filter generates a URL pointing to the protected portal area using public WebSphere Portal APIs, namely the Portal State Manager Service and the URL Factory. The new URL is based on the original request URL meaning that both hold the same navigational state.
Eventually, the filter initiates a redirection to the protected portal space by setting the new URL on the filter chain context. Upon following the redirection, the user can be authenticated automatically by WebSphere Portal based on the remember me cookie. Henceforth, the user will browse the protected portal area without having performed a manual login. At that point, the user is authenticated from a portal access control point of view and identified from a step-up authentication point of view.
Explicit logout filter
The explicit logout plug-point can be used to perform additional operations before or after a user is logged out of WebSphere Portal when clicking a logout link. Custom code extending the explicit logout flow is called in the context of the servlet request and response of the user logout and can also set dynamic redirection targets.
The custom explicit logout filter class com.ibm.portal.sample.RememberMeExplicitLogoutFilter
of this article ensures that the remember me cookie is properly revoked whenever a user triggers an explicit logout. Illustration 2 below depicts how the filter is integrated into the logout flow.Illustration 2: Remember me explicit logout filter flow
The filter tries to locate the remember me cookie in the logout request. If the cookie is not present, the default logout processing of WebSphere Portal continues without further ado. In case the remember me cookie is found, however, its content is cleared and the path this cookie applies to is set in accordance with the configuration (see also Configure the custom security filters).
Before adding the cookie to the servlet response to deliver it to the client, the maximum age is set to zero, which tells the client that this cookie has just been revoked and must not be used any longer. Once the remember me cookie was added to the response for revocation, the default logout processing continues as usual and the user leaves the protected portal area.
Without the custom explicit logout filter, the custom session validation filter introduced earlier would detect the remember me cookie in the post-logout request and send the user back to the protected portal area for automatic authentication again. In case the user logged out wittingly as opposed to navigating away from the website or just closing the web browser, this re-login is neither expected nor desired. The revocation of the remember me cookie by the custom explicit logout filter makes sure that the user browses the public portal space after triggering the logout.
Although all important logic described in this section is implemented in the custom security filters, there are other classes that belong to the sample code.
class is a mere holder for constants used by the filters to access their configuration properties and select meaningful default settings if necessary.
class implements methods common to the security filters, hence, it avoids code duplication for getting initialization parameter and for retrieving cookies from a servlet request.
Lastly the com.ibm.portal.sample.exceptions.RememberMeSessionValidatorException
class and the com.ibm.portal.sample.exceptions.RememberMeSessionValidatorInitException
class are custom exceptions that only take exceptions caught by the custom session validation filter as their cause in order to pass them on to the session validation filter framework.
Working with the source code
The source code of this sample is available for download at Lotus Greenhouse
(Greenhouse login/registration required). The RememberMeSecurityFiltersSample_source.zip
file contains the source files that you can create a Java Project from using an IDE of your choice (for example, Rational Software Architect). Note that the project requires the following libraries in the build path:
- j2ee.jar from $appserver_root/lib
- wp.auth.base.jar from $portalserver_root/base/wp.auth.base/shared/app
- wp.base.jar from $portalserver_root/base/wp.base/shared/app
- wp.model.api.jar from $portalserver_root/base/wp.model.api/shared/app
The sample code has been tested with WebSphere Portal version 7.0.
Enable step-up authentication and remember me
A default installation of WebSphere Portal is not configured for step-up authentication and remember me. Therefore, both features need to be enabled by running the WebSphere Portal ConfigEngine tasks enable-stepup-authentication
first. Also make sure to follow the steps to configure remember me for J2EE authentication as described in the WebSphere Portal product documentation. Please refer to the detailed WebSphere Portal Family wiki topics about step-up authentication and remember me to learn how to configure your installation for the scenario illustrated in this article (see also Enabling step-up authentication, the Remember me cookie, or both
Deploy the custom security filters
Deploy the custom session validation filter and the custom explicit logout filter by placing the RememberMeSecurityFiltersSample_binary.jar
file, which is available for download at Lotus Greenhouse
(Greenhouse login/registration required), in the WebSphere Portal class path (for example, /shared/app
Register the custom security filters
Register the custom session validation filter and the custom explicit logout filter by setting the following properties in the WP AuthenticationService
resource environment provider:
sessionvalidation.filterchain = com.ibm.portal.sample.RememberMeSessionValidator
logout.explicit.filterchain = com.ibm.portal.sample.RememberMeExplicitLogoutFilter
Configure the custom security filters
Some settings of the custom session validation filter and of the custom explicit logout filter need to be aligned with the configuration of your WebSphere Portal installation. The default settings match the values of a default WebSphere Portal setup. However, if your environment uses custom portal servlet paths or special remember me cookie settings, set the following properties in the WP AuthenticationService
resource environment provider to change the default settings of the custom security filters:
// Servlet path of the protected portal area, see also uri.home.protected property of WP ConfigService (default: "/myportal")
// Servlet path of the protected portal area, see also uri.home.public property of WP ConfigService (default: "/portal")
// Name of the remember me cookie, see also name property of WP RememberMeConfigService (default: "com.ibm.portal.RememberMe")
// Name of the remember me cookie, see also name property of WP RememberMeConfigService (default: "com.ibm.portal.RememberMe")
// Path to which the remember me cookie applies, see also name property of WP RememberMeConfigService (default: "/")
Restart the portal server for the changes to take effect.
To test drive the modification of the authentication and logout flow, create a portal page named RememberMeAuthenticationTestPage
with the friendly URL name rememberme
: Illustration 3: Test page with friendly URL name
Allow All Authenticated Portal Users
and the Anonymous Portal User
to access the new page by assigning the User
role accordingly:Illustration 4: Portal access control settings of the test page
The Resource Permissions
portlet also allows you to change the step-up authentication level required by the new page. You can leave it at the standard level that is the default and context-related authentication level of WebSphere Portal: Illustration 5: Step-up authentication level set to standard for the test page
Log out from the protected portal area and delete the cookies held by the web browser. Then use the friendly URL of the test page in the public portal area (for example, http://$host:$port/wps/portal/Home/rememberme
) to navigate to the test page. Because you are not remembered by WebSphere Portal yet, the page is delivered as usual in the public portal context: Illustration 6: Accessing the test page as anonymous user
Log in to the portal and make sure to check the Remember me on this computer checkbox: Illustration 7: Logging in to WebSphere Portal with the remember me option checked
Note that the web browser has received a remember me cookie: Illustration 8: Remember me cookie
WebSphere Portal also issues other cookies, such as the LTPA token cookie. As long as there is a valid LTPA token cookie, you are considered fully authenticated. Therefore, close all instances of the web browser. This takes care of that cookie that is bound to the web browser session in contrast to the persistent remember me cookie.
Restart the web browser and request the test page again using the corresponding friendly URL (for example, http://$host:$port/wps/portal/Home/rememberme
). Verify that WebSphere Portal logs you in automatically and that you have access to other pages in the protected portal area:Illustration 9: Accessing the test page as remembered user after automatic login
Note that you might be asked to provide a user name and a password before gaining access to some pages. This is because you are authenticated from a portal access control perspective but for the step-up authentication framework you are only identified so far.
Log out from the protected portal area and verify that you are browsing the public portal space afterwards. The remember me cookie has been deleted preventing an automatic re-login:Illustration 10: Public portal area after explicit logout