Appendix H. Embedded Jetty Configuration
Prev		Next

Appendix H. Embedded Jetty Configuration

Table of Contents

H.1. Using OpenIDM Configuration Properties in the Jetty Configuration
H.2. Jetty Default Settings
H.3. Registering Additional Servlet Filters

OpenIDM includes an embedded Jetty web server.

To configure the embedded Jetty server, edit openidm/conf/jetty.xml. OpenIDM delegates most of the connector configuration to jetty.xml. OSGi and PAX web specific settings for connector configuration therefore do not have an effect. This lets you take advantage of all Jetty capabilities, as the web server is not configured through an abstraction that might limit some of the options.

The Jetty configuration can reference configuration properties (such as port numbers and key store details) from OpenIDM's boot.properties configuration file.

H.1. Using OpenIDM Configuration Properties in the Jetty Configuration

H.1.1. Accessing Explicit Bean Properties
H.1.2. Accessing Generic Properties

OpenIDM exposes a Param class that you can use in jetty.xml to include OpenIDM configuration. The Param class exposes Bean properties for common Jetty settings and generic property access for other, arbitrary settings.

H.1.1. Accessing Explicit Bean Properties

To retrieve an explicit Bean property, use the following syntax in jetty.xml.

<Get class="org.forgerock.openidm.jetty.Param" name="<bean property name>"/>

For example, to set a Jetty property for keystore password:

<Set name="password">
    <Get class="org.forgerock.openidm.jetty.Param" name="keystorePassword"/>
</Set>

Also see the bundled jetty.xml for further examples.

The following explicit Bean properties are available.

port: Maps to openidm.port.http
port: Maps to openidm.port.https
port: Maps to openidm.port.mutualauth
keystoreType: Maps to openidm.keystore.type
keystoreProvider: Maps to openidm.keystore.provider
keystoreLocation: Maps to openidm.keystore.location
keystorePassword: Maps to openidm.keystore.password
keystoreKeyPassword: Maps to openidm.keystore.key.password, or the key store password if not set
truststoreLocation: Maps to openidm.truststore.location, or the key store location if not set
truststorePassword: Maps to openidm.truststore.password, or the key store password if not set

H.1.2. Accessing Generic Properties

<Call class="org.forgerock.openidm.jetty.Param" name="getProperty">
  <Arg>org.forgerock.openidm.some.sample.property</Arg>
</Call>

H.2. Jetty Default Settings

By default the embedded Jetty server uses the following settings.

The HTTP, SSL, and Mutual Authentication ports defined in OpenIDM
Same key store/trust store settings as OpenIDM
Trivial sample realm, openidm/security/realm.properties to add users

The default settings are intended for evaluation only. Adjust them according to your production requirements.

H.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.

Prev		Next
Appendix G. Router Service Reference	Home	Appendix I. Release Levels & Interface Stability