To configure an HTTP proxy to be used for all the HTTP connections established by Orbeon Forms, add the following two properties:
By default, the host and port properties are commented and Orbeon Forms doesn't use a proxy. Some of the use cases where you will want to define a proxy include:
Your network setup requires you to go through a proxy.
You would like see what goes through HTTP by using a tool that acts as an HTTP proxy, such as Charles.
To connect to the proxy over HTTPS, instead of HTTP which is the default, set the
oxf.http.proxy.use-ssl property to
[SINCE Orbeon Forms 4.6]
You can exclude host names from the proxy using the
oxf.http.proxy.exclude property, which contains a space-delimited list of hostnames.
When using HTTPS, you can specify how the hostname of the server is checked against the hostname in its certificate. You do so with the following property:
The possible values are:
strict — (the default) See
browser-compatible — See
allow-all — See
Typically, you'll leave this property to its default value (
strict). However, you might need to set it to
allow-all to be able to connect to a server with a self-signed certificate if the
cn in the certificate doesn't match the hostname you're using to connect to that server.
When using HTTPS, you can specify which key store (or trust store) to use to verify the server you are connecting to. The following properties are relevant:
specifies the URL of the key store file
this can use the
if this property is blank, the default JSSE algorithm to find a trust store applies (see the [JSSE Reference Guide])
specifies the password needed to access the key store file
This can be useful for using self-signed certificates:
setup your servlet container (usually via a connector configuration) to point to a key store containing your certificate
oxf.http.ssl.keystore.* properties to point to that same key store
This enables a secure connection between Orbeon Forms and the servlet container.
When Orbeon Forms performs XForms submissions, or retrieves documents in XPL over HTTP, it has the ability to forward incoming HTTP headers. For example, if you want to forward the
Authorization header to your services:
WARNING: For security reasons, you should be careful with header forwarding, as this might cause non trusted services to receive client headers.
Similar to general headers forwarding, cookies can be forwarded. By default, the property is as follows:
If you need to forward, say,
JSESSIONIDSSO to services, set this in properties-local.xml:
When a username for HTTP Basic authentication is specified, cookies are not forwarded. The first cookie in the list, typically
JSESSIONID, is interpreted by Orbeon Forms to be the session cookie. If the value of the session cookie doesn't match the current session, say because the provided
JSESSIONID has expired or is invalid, then the value of the cookie from the incoming request isn't forwarded. Instead, in that case, the new value of the session cookie is:
[UP TO Orbeon Forms 2016.3] The session id.
[SINCE Orbeon Forms 2017.1] The concatenation of the following 3 values:
The value of the
The session id
The value of the
By default, the value of the prefix and suffix properties is empty, as shown below, which works well with application servers like Tomcat that set the
JSESSIONID directly to the session id.
On the other hand, some application servers, add a prefix and suffix to the session id. For instance, WebSphere uses the cache id as prefix, and the colon character (
:) followed by the clone id as suffix. So, on WebSphere, assuming that in your situation the cache id is always
0000, and the client id (found in WebSphere's
123, you will want to set those properties as shown below. Note how the value of the client id follows the colon character in the value of the suffix property.
WARNING: For security reasons, you should be careful with cookies forwarding, as this might cause non trusted services to receive client cookies.
This property is tied to the HttpClient stale checking:
Defines whether stale connection check is to be used. Disabling stale connection check may result in slight performance improvement at the risk of getting an I/O error when executing a request over a connection that has been closed at the server side.
By default, Orbeon checks for stale HTTP connections. You can disabling stale connection checking by setting the following property to
false (it is
true by default):
This property is tied to the HttpClient SO timeout:
Sets the default socket timeout (SO_TIMEOUT) in milliseconds which is the timeout for waiting for data. A timeout value of zero is interpreted as an infinite timeout.
By default, Orbeon doesn't set a timeout with HttpClient. Setting a timeout can be potentially dangerous as it can lead to service calls that take longer to run than the timeout you specified to fail in a way that can be unpredictable, as it is possible for your services to sometimes return before the timeout and sometimes after. If, nevertheless, you need to set a timeout, you can do so by adding the following property, e.g. here setting a timeout at 1 minute:
NOTE: These two headers are computed values and it is only possible to override them with constant values by using the properties above. In general we don't recommend overriding these headers by using the properties above.
[SINCE Orbeon Forms 2019.1]
Since the HTTP client uses connection pooling, some connections can be come stale, which can cause errors at inopportune times. Enabling expired and idle connections checking can help reduce this issue.
oxf.http.expired-connections-polling-delay property sets the expired connection checking polling delay. The default is 5,000 milliseconds (5 seconds).
oxf.http.idle-connections-delay property sets the idle connection time to live. The default is 30,000 milliseconds (30 seconds).
oxf.http.expired-connections-polling-delay is commented out or not present, neither checks are performed.
oxf.http.idle-connections-delay is commented out or not present, but
oxf.http.expired-connections-polling-delay is present, then only the check for expired connections takes place.
Keeping expired and idle connections checking enabled can improve the reliability of connections to remote servers.