Customizing DirX Access Components

The HTTP response-rendering delegation is implemented with the servlet forwarding technique. When the FEP needs to render the output, it prepares all possibly useful data for the renderer, stores them in the request attributes and forwards the request (and response) to the rendering servlet. See Java Servlet API, servlet forwarding, especially RequestDispatcher.forward() method, which is the cornerstone of the technique.

For the parameters and parameter types that the SAML FEP uses for passing the data to the rendering servlets, see com.siemens.dxa.common.web.rendering.api package JavaDoc documentation in dirxaccess-base-javadoc.zip which is available on the DirX Access product DVD under Documentation\DirXAccess. The forwarding is always performed by the servlet name and the FEPs use the default names. The deployment descriptor (web.xml) of the Web application that hosts the FEP must define these servlets.

The purpose of the parameter sanitization servlet filter is to prevent the possibility of cross-site scripting attacks. To accomplish this task:

The administrator chooses HTTP request parameters (sent via an HTTP URL query or an HTTP request body) that might be displayed at the Web page and lists them in the Web application’s configuration file.

The servlet filter removes potentially harmful characters without replacing them using a regular expression pattern to specify the filtered characters.

A custom filter can be set individually for each parameter or for a list of parameters.

For a single parameter use the following format: filtered.keys..

For a list of parameters use the following format: filtered.keys.[,].

A default filter can be used, to filter every other unlisted parameter, the configuration parameter to be used is “defaultFilter”.

If the default filter is empty or omitted, only the listed parameters will be filtered.

Note: The parameters names are case sensitive!

To set up the servlet filter:

Uncomment the filter definition and the filter mapping in web.xml. Example filters can be found in the filter definition. Remove or change these to match your needs.

Customize the defaultFilter parameter to filter all non-specified parameters. If the default filter is omitted or empty, only the listed parameters will be filtered.

Customize the specific filter names, either one-by-one or as a list.

Restart the service for the changes to take effect.

The default implementation, which uses JSP for rendering the visual output, is a good starting point that demonstrates the use of the API. Modifying only the default JSP pages or only their style sheets can be sufficient in many cases, too, without the need to create the renderer from scratch.

Regarding the look and feel customization, DirX Access Client SDK offers a nice customization in the ClientSDK\Integration\webapps\saml‑fep folder under the DirX Access installation folder. It is a good starting point for your own customization or an example of how the minimalistic and very basic user interface, which is deployed by default, can be extended into a usable presentation to the user. Note that the DirX Access Client SDK customization is written with minimal JSP support required, thus avoiding some advanced constructs.

Note that the name of the rendering servlet used by the SAML FEPs is currently hardcoded (the SAML FEP uses the default). Because SAML specification requires using XHTML for form-based redirection responses, the default HTML form redirection servlet must return XHTML to be compliant with the specification. This behavior can cause problems if the servlet is shared with another component that has different requirements but uses the default name. However, such a situation is very unlikely.