Single Sign-On for Java 3.3.2 - Administration Guide

Creating a deployment descriptor for SSO

This section describes how to build deployment descriptors to take advantage of Single Sign-on for Java.

Deploying SSO web components

The procedure for deploying Web components on an application server requires no programming, and is the same for both Servlets and JSPs. This is because it uses the concept of filters. These filters are used to filter incoming requests for data which they can use before forwarding the request to the intended recipient.

Single Sign-on for Java provides a filter called AuthFilter which is responsible for filtering authentication data from requests, and then authenticating the sender before forwarding the request onto Servlets and JSPs. The first step in adding the filter is to declare a mapping of it to the Servlet/JSP for which it authenticates:

<filter-mapping>

<filter-name>authFilter</filter-name>

<servlet-name>SimpleServlet</servlet-name>

</filter-mapping>

This addition to the deployment descriptor creates a new mapping of a filter called authFilter to an ordinary Servlet named SimpleServlet (the Simple example is included in the examples/simple/ directory of your installation). The authFilter (as yet undefined) is responsible for filtering any incoming HTTP requests to the SimpleServlet. This same mapping can be done for JSPs as well:

<filter-mapping>

filter-name>authFilter</filter-name>

<url-pattern>/test/index.jsp</url-pattern>

</filter-mapping>

Now that the filter mapping has been set up to intercept the HTTP requests to your Web component, you can expand the filter to perform the authentication. To define the new filter you must add the following XML fragment:

<filter>

<filter-name>authFilter</filter-name>

<filter-class>com.wedgetail.idm.sso.AuthFilter</filter-class>

</filter>

This addition declares a new filter called authFilter which is an instance of the Single Sign-on for Java filter com.wedgetail.idm.sso.AuthFilter. Now all requests to a Web component to which authFilter is mapped, pass through the Single Sign-on for Java AuthFilter.

Configuring the Single Sign-On parameters

Single Sign-on for Java requires a number of parameters so that it can validate credentials and ensure the security of the communications.

This can be done by either entering the configuration parameters and their values in the vsj.properties file (see examples/vsj.properties for an example properties file), as initialization parameters (<init-param>) or as context parameters (<context-param>).

By default, Single Sign-on for Java looks for a vsj.properties file on the classpath or in the WEB-INF/ directory of your web application.

Alternatively, you can specify the URL location of a properties file using the idm.propertyFileURL configuration parameter. For example:

<filter>

<filter-name>authFilter</filter-name>

<filter-class>com.wedgetail.idm.sso.AuthFilter</filter-class>

<init-param>

<param-name>idm.propertyFileURL</param-name>

<param-value>file:///C:/vsj.properties</param-value>

</init-param>

</filter>

Using initialization parameters is particularly good for binding specific credential validation information to individual servlets and filters since they are embedded in Web component definitions.

For example, defining a principal for an authentication filter can be done as follows:

<filter>

<filter-name>authFilter</filter-name>

<filter-class>com.wedgetail.idm.sso.AuthFilter</filter-class>

<init-param>

<param-name>idm.principalAtRealm</param-name>

<param-value>vsj_appservhost1@EXAMPLE.COM</param-value>

</init-param>

</filter>

This binds the defined principal to one filter only.

On the other hand, context parameters are valid and visible for all Web components defined in a deployment descriptor.

The following shows an example of a principal being defined in a context parameter:

<web-app>

<context-param>

<param-name>idm.principalAtRealm</param-name>

<param-value>vsj_appservhost1@EXAMPLE.COM</param-value>

</context-param>

</web-app>

See Single Sign-on Configuration Parameters for a detailed list of all Single Sign-on for Java configuration parameters.

Building a war file for Single Sign-on for Java

Once you have coded your Web components and set up an SSO deployment descriptor, you can prepare the Web components for deployment. As with normal Web components, you need to create a Web Application Archive (WAR) file to maintain a standardized structure.

You can then install the Single Sign-on for Java-configured WAR using the appropriate deployment mechanism for your application server.