The problemOrbeon Forms is typically deployed in a servlet container and access with the HTTP protocol. This is especially convenient during development as that's a simple setup which also allows you to monitor HTTP requests. When deploying Orbeon Forms on a real server, it is often necessary to switch to HTTPS (the secure version of HTTP) instead. This page describes an HTTPS configuration with Orbeon Forms that takes into account the tricky parts, such as Orbeon Forms calling itself. NOTE: Some scenarios described here depend on properties available since 2011-05-25 and 2012-02-16. The solutionHTTPS from the browserThis is the first and most important part of the configuration: enabling HTTPS between the browser and Orbeon Forms. First, follow instructions for your servlet container, app server or HTTP server. Here is the documentation for plain Tomcat: Here is a configuration of the Tomcat SSL connector that typically works:
Note that if you have more than one key in the key store, you can specify which one to use with an extra attribute:
JBoss uses Tomcat so the JBoss configuration is very similar to plain Tomcat, except that JBoss specifies a location for the key store. Here are relevant locations for JBoss 5.1.0:
Now, once you have such a connector in place you can connect from your browser to the Orbeon Forms address and see the Orbeon Forms home page. If you are using a self-signed certificate (instead of a CA certificate), the browser will first display a warning message. Now, one of two things might happen when you navigate to a Form Runner page:
Things should work out of the box in the following situation:
In other cases, you will likely see errors like "peer not authenticated". The reason is that Form Runner (and other XForms applications) often perform HTTP (or HTTPS) requests themselves. Form Runner, for example, calls services to load resources, read and write form definitions, etc. Those connection must either use HTTP, or have a correct HTTPS configuration to work. Several options a described below. HTTPS for services, using a CA certificate and a different host nameIf you have installed a CA certificate, say for forms.acme.com, but for some reason (network configuration/policy) you cannot allow Orbeon Forms to reach forms.acme.com, you must set the following properties:
Note the oxf.http.ssl.hostname-verifier which tells Orbeon Forms to disable checking that the name of the host matches the name on the certificate.NOTE: This property is only available since 2011-05-25. The other properties make sure that Orbeon Forms is looping back using localhost instead of forms.acme.com.Here we use localhost as that's usually the easiest way to make sure the local host is reached, but depending on your network configuration you can use any name or IP address that loops back to Orbeon Forms.HTTP for servicesEven though you might use HTTPS between the browser and Orbeon Forms, using HTTP for services might be acceptable if you have a trusted server. By default, Orbeon Forms determines URLs for local services automatically, based on information from the incoming requests from the client, including the protocol (HTTP or HTTPS), port, and servlet context. So say you access Orbeon Forms with:
Orbeon Forms will try to reach services under that URL as well. In order to change that and use HTTP, you must set a few properties in your properties-local.xml:
Notice the use of the http protocol.Here we use localhost as that's usually the easiest way to make sure the local host is reached, but depending on your network configuration you might be able to use forms.acme.com, or any name or IP address that loops back to Orbeon Forms.With this, Form Runner will work without any fancy SSL configuration on the server, but with the caveat that connections from Orbeon Forms to itself are not secured. HTTPS for services, using a self-signed certificate[SINCE 2012-02-16] Often, when dealing with services within an organization, using self-signed certificates is an attractive option because it is easy to generate such certificates. There is a lot of information out there about generating such certificates, including the Tomcat documentation linked above. Here is an example command:
You must use a password for the key store (typically "changeit" for development). Once you have a key store ready, you must tell a Tomcat SSL connector to point to it, as shown above. Now here is a fun problem: with SSL, a given connector can only be associated with one certificate. So if you are using a CA certificate for forms.acme.com on a given connector, you cannot in addition use a self-signed certificate.So the solution here is to create two connectors:
To do this, the two connectors must differ in at least one way:
A fairly easy way is to do the following:
As far as key stores are concerned, you can:
A resulting server.xml configuration might look like this:
Finally, Orbeon Forms must be told to trust the self-signed certificate, by setting the following in your properties-local.xml:
The same comments about the use of localhost described above apply.NOTE: This oxf.http.ssl.keystore.uri and oxf.http.ssl.keystore.password properties are only available since 2012-02-16. If the host name in the self-signed certificate doesn't match the host name (e.g. localhost) specified in the properties, you can also set this property:
But since it is easy to specify the correct host name with self-signed certificates, it's best to have the host names match. HTTPS for services, using a CA certificateYou can also use a separate certificate from a Certificate Authority for internal connections, for example local.acme.org.As in the case of using a self-signed certificate, you have to use two separate SSL connectors. Unlike the case of using a self-signed certificate, you might not have to specify the oxf.http.ssl.keystore.uri property, as the certificate chain might be properly setup by default. However, if your CA is not known by the Java runtime environment, you will have to specify the oxf.http.ssl.keystore.uri property. |
|
|
|
|
How-to guides >
Use SSL (HTTPS) |