Java Toolbox OpenSSOFilter Reference Guide

Hannes Holtzhausen

$Id: open_sso_filter.xml,v 1.2 2007/11/02 09:55:48 hannes Exp $

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Table of Contents

1. Introduction
2. Configuration
3. Deployment
4. Sample Application

1. Introduction

The OpenSSOFilter provides a simple Filter based interface to the OpenSSO access management server. It provides functionality to validate Single Sign-on tokens and provides access to the attributes of signed on users. When deployed on remote containers, the filter can also be configured to manage the lifecycle of HttpSession instances based on the state of Single Sign-on tokens.

This document will serve as reference to the OpenSSOFilter configuration and deployment.

2. Configuration

The filter is configured using the init-param configuration facility provided by the Java Servlet Deployment Descriptor XML document. The following table contains a description of each configuration parameter that can be specified:

Table 1. Filter configuration parameters

Parameter	Valid Values	Description	Required
manage.httpsession	true/false	Instruct the filter to manage the HttpSession lifecycle	Yes
redirect.invalid.session	true/false	Instruct the filter to redirect when an invalid token is encountered.	Yes
redirect.url	HTTP URL	The URL to redirect to when redirect.invalid.session is set to true and an invalid token is encountered.	No,unless redirect.invalid.session=true
error.invalid.session	true/false	Instruct the filter to forward the request to an error page within the application when an invalid token is encountered.	Yes
error.url	Relative HTTP URL	The URL to forward to when error.invalid.session is set to true and an invalid token is encountered	No,unless error.invalid.session=true
user.attribute.map	true/false	Instruct the filter to use a java.util.Map instance to store user attributes in the HttpSession. When set to false the user attributes will be stored in the HttpSession directly.	Yes
user.attribute.map.name	String	When using a Map instance to store user attributes, use this name to store the Map instance in the HttpSession.	No,unless user.attribute.map=true
user.attribute.exclude.patterns	CSV String	A comman separated list of regular expressions used to exclude user attributes from the HttpSession or Map.	No
session.token.attribute	String	Use this name to create a HttpSession attribute that will indicate that the HttpSession is valid.	Yes
roledn.key.name	String	When storing the user's role DN's use this value as the name of the user Map key or session attribute name.	Yes
rolecn.key.name	String	When storing the user's role CN's use this value as the value of the user Map key or session attribute name.	Yes

3. Deployment

The filter can be deployed to any Java Servlet Container that supports the OpenSSO client SDK or OpenSSO Policy Agent.

For the filter to function correctly you must include the toolbox_opensso.jar file in your WAR file under WEB-INF/lib. The jar is located in the lib directory of the toolbox_opensso module you installed.

The following is an XML fragment that can be customised to include the filter as part of a web application deployment:

  <filter>
    <filter-name>OpenSSOFilter</filter-name>
    <filter-class>toolbox.opensso.web.OpenSSOFilter</filter-class>

    <init-param>
      <param-name>manage.httpsession</param-name>
      <param-value>true</param-value>
    </init-param>

    <init-param>
      <param-name>redirect.invalid.session</param-name>
      <param-value>false</param-value>
    </init-param>

    <init-param>
      <param-name>error.invalid.session</param-name>
      <param-value>true</param-value>
    </init-param>

    <init-param>
      <param-name>error.url</param-name>
      <param-value>/error.jsp</param-value>
    </init-param>

    <init-param>
      <param-name>user.attribute.map</param-name>
      <param-value>false</param-value>
    </init-param>

    <init-param>
      <param-name>user.attribute.exclude.patterns</param-name>
      <param-value>sun\S*,userpassword,objectclass</param-value>
    </init-param>

    <init-param>
      <param-name>session.token.attribute</param-name>
      <param-value>hasToken</param-value>
    </init-param>

    <init-param>
      <param-name>roledn.key.name</param-name>
      <param-value>roledn</param-value>
    </init-param>

    <init-param>
      <param-name>rolecn.key.name</param-name>
      <param-value>rolecn</param-value>
    </init-param>
  </filter>

4. Sample Application

The toolbox_opensso module contains an example web application that includes the filter. It is located in the doc/samples/filter directory.