3. Registering Additional Servlet Filters

You can register generic servlet filters in the embedded Jetty server to perform additional filtering tasks on requests to or responses from OpenIDM. For example, you might want to use a servlet filter to protect access to OpenIDM with an access management product such, as OpenAM. Servlet filters are configured in files named openidm/conf/servletfilter-name.json. These servlet filter configuration files define the filter class, required libraries, and other settings.

A sample servlet filter configuration is provided in openidm/samples/openam. The sample configuration includes the servlet filter configuration file (conf/servletfilter-openam.json) and the extension script that implements the filter (script/security/populateContext.js).

The sample servlet filter configuration file is shown below:

{
    "classPathURLs" : [
        "file:/jetty_v61_agent/lib/agent.jar",
        "file:/jetty_v61_agent/lib/openssoclientsdk.jar",
        "file:/jetty_v61_agent/lib/",
        "file:/jetty_v61_agent/locale/"
    ],
    "systemProperties" : {
        "openam.agents.bootstrap.dir" : "/jetty_v61_agent/Agent_001/config"
    },
    "requestAttributes" : {
        "openidm.authinvoked" : "servletfilter-openam"
    },
    "scriptExtensions" : {
        "augmentSecurityContext" : {
            "type" : "text/javascript",
            "file" : "script/security/populateContext.js"
        }
    },
    "filterClass" : "com.sun.identity.agents.filter.AmAgentFilter"
}

The sample configuration includes the following properties:

"classPathURLs"

The URLs to any required classes or libraries that should be added to the classpath used by the servlet filter class

"systemProperties"

Any additional Java system properties required by the filter

"requestAttributes"

The HTTP Servlet request attributes that will be set by OpenIDM when the filter is invoked. OpenIDM expects certain request attributes to be set by any module that protects access to it, so this helps in setting these expected settings.

"scriptExtensions"

Optional script extensions to OpenIDM. Currently only "augmentSecurityContext" is supported. A script that is defined in augmentSecurityContext is executed by OpenIDM after a successful authentication request. The script helps to populate the expected security context in OpenIDM. For example, the login module (servlet filter) might select to supply only the authenticated user name, while the associated roles and user ID can be augmented by the script.

Only JavaScript is supported ("type":"text/javascript"). The script can be provided inline ("source":script source) or in a file ("file":filename). The sample filter extends the filter interface with the functionality in the script script/security/populateContext.js.

"filterClass"

The servlet filter that is being registered

The following additional properties can be configured for the filter:

"httpContextId"

The HTTP context under which the filter should be registered. The default is "openidm".

"servletNames"

A list of servlet names to which the filter should apply. The default is "OpenIDM REST".

"urlPatterns"

A list of URL patterns to which the filter applies. The default is ["/openidm/*", "/openidmui/*"].

"initParams"

Filter configuration initialization parameters that are passed to the servlet filter init method. For more information, see http://docs.oracle.com/javaee/5/api/javax/servlet/FilterConfig.html.

When a servlet filter is used to integrate an access management product, the specific servlet filter that is used, and the configuration that is associated with that filter, is product-specific. The sample configuration in openidm/samples/openam is specific to OpenAM. For a detailed description of the OpenAM implementation, see Protecting OpenIDM With OpenAM.