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:
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:
The possible values are:
strict— (the default) SeeStrictHostnameVerifier.browser-compatible— SeeBrowserCompatHostnameVerifier.allow-all— SeeAllowAllHostnameVerifier.
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.
2-way SSL
When using HTTPS, you might want Orbeon Forms to authenticate itself by presenting a client certificate. For this, you need the client to have a key and certificate in a keystore, and point Orbeon Forms to that keystore using the propertied below.
oxf.http.ssl.keystore.uriSpecifies the URI of the keystore file.
The URI can use the
file:or [SINCE Orbeon Forms 2021.1]oxf:protocol.Relationship to the truststore:
[SINCE Orbeon Forms 2021.1] Whether this property is specified or not, the server certificate is verified using the default truststore, which you override by setting the
javax.net.ssl.trustStoreproperty (more on this in the JSSE Reference Guide).[UNTIL Orbeon Forms 2020.1] If you specify a keystore, it is also used as a truststore. This is the case even if connecting to server whose key is signed by a recognized certificate authority (CA), which means that you need to add the certificate of the CA who signed the key of the server you want to connect to the keystore.
If this property is blank, the default JSSE algorithm to find a truststore applies.
oxf.http.ssl.keystore.passwordSpecifies the password needed to access the keystore file.
You might also want to:
For Orbeon Forms to accept incoming connections using the same certificate, set up your servlet container, on Tomcat in the
server.xmlon the<Connector>used for HTTPS, to point to same keystore.[SINCE Orbeon Forms 2021.1] Set the
oxf.http.ssl.keystore.*system property to point to a truststore that contains the certificate of the certificate authority who signed the certificate of the server you want to connect to.
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:
For more, see HTTP headers forwarding.
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:
If you need to forward, say, JSESSIONID and JSESSIONIDSSO to services, set this in your 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
oxf.http.forward-cookies.session.prefixpropertyThe session id
The value of the
oxf.http.forward-cookies.session.suffixproperty
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 clone 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 clone 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.
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):
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:
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
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).
The oxf.http.idle-connections-delay property sets the idle connection time to live. The default is 30,000 milliseconds (30 seconds).
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
Last updated