Documentation‎ > ‎I. User Guide‎ > ‎

Orbeon Form Runner - Programmer and Administrator Guide

Securing Form Runner

It is very important to make sure your Form Runner deployment is protected from unauthorized access. The way to do this depends on the version of Orbeon Forms you are using.

With Orbeon Forms 4.0

With Orbeon Forms 3.x

Protecting services

Orbeon Forms 3.x does not protect services automatically by default. It is important to prevent external access to Form Runner services, including the eXist database (if used) and services used internally by Form Runner.

One way of  implementing the protection is to ensure that callers come from the same IP address as the server on which Orbeon Forms is located.

Within the servlet container, you can use UrlRewriteFilter or similar to protect accesses to:
  • Form Runner services, under /fr/service/*
  • The eXist database, under /exist/rest/*
With Apache, here is an example of Apache configuration using mod_rewrite:

# Don't allow eXist REST API from outside
RewriteRule ^/exist/rest/.* - [F]

# Don't allow Form Runner REST API from outside
RewriteRule ^/orbeon/fr/service/.* - [F]

In addition, you will probably still want an IP filter on the servlet container side.

Scenarios with an Apache front-end

NOTE: The following configurations needs to be reviewed.

Apache front-end configuration

Example Apache configuration to proxy requests to Tomcat:

ProxyRequests Off
ProxyPreserveHost On

ProxyPass / ajp://localhost:8099/
ProxyPassReverse / ajp://localhost:8099/

Example Tomcat connector configuration:

<Connector port="8099" protocol="AJP/1.3" redirectPort="8443" maxThreads="10"
 enableLookups="false" backlog="50" tomcatAuthentication="true" address=""/>

With this configuration:

  • the address="" attribute limits requests to Tomcat from the local server (where Apache is assumed to be located)
  • authentication proper is delegated to Tomcat

Scenario: protecting forms from anonymous access

Example Apache configuration ensuring that Form Runner paths require a logged user:

<LocationMatch /orbeon/fr/.*)>
  AuthType Basic
  AuthName "Orbeon Forms"
  AuthUserFile .htpasswd
  AuthGroupFile .htgroups

  Require valid-user


Scenario: data capture only

In this scenario, you want users (logged in or anonymous) to be able to:
  • enter form data
  • review the data
  • submit the data
But not:
  • view/edit data already submitted
  • view other users' data
In this case, you want to allow paths of the form:
But disallow any other path.

Example Apache configuration requiring a valid user except for the "new" paths:

<LocationMatch /orbeon/fr/orbeon/register(?!/new/?)>
  AuthType Basic
  AuthName "Orbeon Forms"
  AuthUserFile .htpasswd
  AuthGroupFile .htgroups

  Require valid-user


Form Runner pages


Form Runner features a number of different pages:
  • Summary page:
    • the summary page shows the form data for a given form
  • Detail page:
    • "new" mode: create new form data, starting usually with a blank form
    • "edit" mode: edit existing form data loaded from the database
    • "view" mode: same as "edit", but read-only, to review the data entered in edit mode
  • Home page
    • show all the forms and actions available to the current user
    • NOTE: This is only available for the Oracle and MySQL persistence layer as of 2012-02.

Summary page




The following buttons are available on the summary page:
  • New
  • Review
  • PDF
  • Test (Form Builder only)
  • Delete
  • Import
You configure the presence of these buttons on the page via properties.

Detail page

The detail page can be shown in 3 modes:
  • new: in this mode, you create new form data
  • edit: in this mode, you edit existing form data
  • view: in this mode, you review form data

Home page

See Home page.


Sending via GMail using TLS

[SINCE Orbeon Forms 4.0]

You can send email via GMail with TLS encryption with a setting as follows:

<property as="xs:string" name="*.*"        value=""/>
<property as="xs:string" name="*.*"             value=""/>
<property as="xs:string" name="*.*"               value=""/>
<property as="xs:string" name="*.*"    value="username"/>
<property as="xs:string" name="*.*" value="secret"/>
<property as="xs:string" name="*.*"  value="tls"/>

Customizing the email subject

You can customize the email subject by setting a property:

  value="Here is your confirmation: "/>

  value="…: "/>

Form Runner appends to the subject specified in these properties the values from the fields that have been marked with "Show in Email Subject".

Form structure

Data saved to the persistence layer

When Form Runner saves XML data to the persistence layer, or sends it through the workflow-send button:
  • saving/sending works only if the data is valid
  • the data for non-visible sections and controls is not pruned from the XML document

Customizing the form's look and feel 

See: Styling.

Configuring the presentation of automatic PDF output

See: Styling.


Form Runner is an internationalized application. This means that it supports multiple languages. This is done at two levels:
  • The language of the Form Runner interface: navigation buttons, etc.
  • The language of the form's labels, help, etc.
Usually, a language selector appears in the Form Runner navigation bar at the top of the page.

The fr-language URL parameter allows requesting a specific language, for example:


The requested language is matched against available languages, and Form Runner then chooses the appropriate language.

The selected language is stored into the user's session and the session language, if present is used if no URL parameter is present.