HTTP client

Proxy setup

To configure an HTTP proxy to be used for all the HTTP connections established by Orbeon Forms, add the following two properties:

<property
as="xs:string"
name="oxf.http.proxy.host"
value="localhost"/>
<property
as="xs:integer"
name="oxf.http.proxy.port"
value="8090"/>
<property
as="xs:boolean"
name="oxf.http.proxy.use-ssl"
value="false"/>
<property
as="xs:string"
name="oxf.http.proxy.exclude"
value=""/>
<property
as="xs:string"
name="oxf.http.proxy.username"
value=""/>
<property
as="xs:string"
name="oxf.http.proxy.password"
value=""/>
<property
as="xs:string"
name="oxf.http.proxy.ntlm.host"
value=""/>
<property
as="xs:string"
name="oxf.http.proxy.ntlm.domain"
value=""/>

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

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

SSL hostname verifier

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:

<property
as="xs:string"
name="oxf.http.ssl.hostname-verifier"
value="strict"/>

The possible values are:

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.

SSL key store

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:

<property
as="xs:anyURI"
name="oxf.http.ssl.keystore.uri"
value="oxf:/config/my.keystore"/>
<property
as="xs:string"
name="oxf.http.ssl.keystore.password"
value="changeit"/>
  • oxf.http.ssl.keystore.uri

    • specifies the URL of the key store file

    • this can use the file: or oxf: protocols

    • if this property is blank, the default JSSE algorithm to find a trust store applies (see the [JSSE Reference Guide][3])

  • oxf.http.ssl.keystore.password

    • 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

  • setup the oxf.http.ssl.keystore.* properties to point to that same key store

This enables a secure connection between Orbeon Forms and the servlet container.

Headers forwarding

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:

<property
as="xs:string"
name="oxf.http.forward-headers"
value="Authorization"/>

WARNING: For security reasons, you should be careful with header forwarding, as this might cause non trusted services to receive client headers.

Cookies forwarding

Similar to general headers forwarding, cookies can be forwarded. By default, the property is as follows:

<property
as="xs:string"
name="oxf.http.forward-cookies"
value=""/>

If you need to forward, say, JSESSIONID and JSESSIONIDSSO to services, set this in properties-local.xml:

<property
as="xs:string"
name="oxf.http.forward-cookies"
value="JSESSIONID JSESSIONIDSSO"/>

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:

    1. The value of the oxf.http.forward-cookies.session.prefix property

    2. The session id

    3. The value of the oxf.http.forward-cookies.session.suffix property

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.

<property
as="xs:string"
name="oxf.http.forward-cookies.session.prefix"
value=""/>
<property
as="xs:string"
name="oxf.http.forward-cookies.session.suffix"
value=""/>

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 plugin-cfg.xml) is 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.

<property
as="xs:string"
name="oxf.http.forward-cookies.session.prefix"
value="0000"/>
<property
as="xs:string"
name="oxf.http.forward-cookies.session.suffix"
value=":123"/>

WARNING: For security reasons, you should be careful with cookies forwarding, as this might cause non trusted services to receive client cookies.

Stale checking

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):

<property
as="xs:boolean"
name="oxf.http.stale-checking-enabled"
value="false"/>

Socket timeout

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:

<property
as="xs:integer"
name="oxf.http.so-timeout"
value="60000"/>

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.

Request chunking

<property
as="xs:boolean"
name="oxf.http.chunk-requests"
value="false"/>

Expired and idle connections

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

The oxf.http.expired-connections-polling-delay property sets the expired connection checking polling delay. The default is 5,000 milliseconds (5 seconds).

<property
as="xs:integer"
name="oxf.http.expired-connections-polling-delay"
value="5000"/>

The oxf.http.idle-connections-delay property sets the idle connection time to live. The default is 30,000 milliseconds (30 seconds).

<property
as="xs:integer"
name="oxf.http.idle-connections-delay"
value="30000"/>

If oxf.http.expired-connections-polling-delay is commented out or not present, neither checks are performed.

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

See also