Captcha
Last updated
Last updated
If you are creating a public form, you might want to add a to avoid spam. You can do so by enabling the Orbeon Forms captcha feature. Under this umbrella, Orbeon Forms supports several captcha implementations.
is almost a de facto standard on the web: more than a hundred million reCAPTCHA are solved every day, it is used by a large number of mainstream sites and is constantly updated providing a high level of security. This service is owned by Google.
Because of the high level of safety provided by reCAPTCHA, we recommend you use it, unless doing so isn't possible in your situation. Maybe, for instance, you don't want the server on which Orbeon Forms runs to connect to any external service, which the reCAPTCHA component does to verify the answer provided. If you can't use the reCAPTCHA, Orbeon Forms provides an alternate component which runs entirely within Orbeon Forms, without the need to connect to any external server.
Using is another solid option. Friendly Captcha is an alternative to Google's reCAPTCHA and, in their own words, "GDPR-Compliant Bot Protection".
You enable a captcha by adding the following property to your properties-local.xml. For example:
[SINCE Orbeon Forms 2020.1]
[UNTIL Orbeon Forms 2019.2]
The property name changed in Orbeon Forms 2020.1 with the introduction of new captcha-related properties (more on this below). The old property name, without the component part, is still supported, but deprecated. Allowed values are:
Blank or empty string: no captcha is added to your form (default)
fr:recaptcha
You can also use the deprecated token reCAPTCHA for backward compatibility.
Make sure that, at the top of your properties-local.xml file, you have xmlns:fr="http://orbeon.org/oxf/xml/form-runner" defined (this should be present by default).
fr:friendly-captcha
make sure that, at the top of your properties-local.xml file, you have xmlns:fr="http://orbeon.org/oxf/xml/form-runner" defined (this should be present by default)
fr:on-premise-captcha
You can also use the deprecated tokens OnPremiseCaptcha or SimpleCaptcha for backward compatibility.
Make sure that, at the top of your properties-local.xml file, you have xmlns:fr="http://orbeon.org/oxf/xml/form-runner" defined (this should be present by default).
SimpleCaptcha
This uses the SimpleCaptcha implementation.
If you use Orbeon Forms 2023.1.1 or newer, use fr:on-premise-captcha instead.
Qualified name of an XBL component that implements a captcha
[SINCE Orbeon Forms 2017.2]
Example: acme:custom-captcha
When doing so, you need to have a namespace defined in your property file for the component prefix you're using, say xmlns:acme="http://acme.org/".
If using the reCAPTCHA, you'll also need to add properties to specify your reCAPTCHA public and private keys.
You can use this component to show users a captcha, like the one shown in the following screenshot:
Store your public keys (now called "site keys") and private keys in your properties, as follows:
[UNTIL Orbeon Forms 2023.1]
Add the reCAPTCHA component to your form:
For forms you're creating in Form Builder, enable the reCAPTCHA by setting the following property:
For forms you're creating by writing XForms "by hand", add the component to your form as follows. You'll also want to add handlers for the fr-verify-done and maybe fr-verify-error events.
You can configure:
The theme using properties, either:
For forms you're creating with Form Builder, with:
For forms you're creating by writing XForms "by hand", with:
The language with the lang attribute on the <html> element.
When a control is invalid, an alert message appears directly below it. This applies to the reCAPTCHA as well. However, the error summary typically appears just below the reCAPTCHA, causing the alert to be shown twice: once below the reCAPTCHA and again in the summary. To address this, the reCAPTCHA alert is hidden by default using CSS. If you want the alert to be visible below the reCAPTCHA, perhaps because you're not showing the error summary, you can use the following CSS:
The score threshold (for reCAPTCHA v3 only). When verifying the response, the reCAPTCHA API returns a score between 0 and 1. If the score is higher than the threshold, the verification is considered successful. If it is lower, the component will switch to reCAPTCHA v2 (visible reCAPTCHA) for further verification. The default score threshold is 0.5. You can customize this threshold with the following property:
When users submit a form with a captcha and subsequently navigate away from the page containing that form, they can use their browser's back functionality to return to the form. By default, the captcha will appear as already resolved. In some cases, you might prefer to require users to complete a new captcha for each submission they make. If so, you'll want to reset the captcha.
Add the following to the process you are running, before the action that navigates away from the page.
[SINCE Orbeon Forms 2022.1.8, 2023.1.3, 2024.1]
Add the following to the process you are running, before the action that navigates away from the page.
You can use this component to show users a simple captcha like the one shown in the following screenshot:
Note that this doesn't offer as much security as reCAPTCHA, for example, but it is entirely handled by Orbeon Forms and does not call external services.
You enable the simple on-premise captcha by adding the following property to your properties-local.xml:
NOTE: The older SimpleCaptcha value is still accepted but deprecated.
To use this component with plain XForms, where you want the captcha to show in your form, add:
Most likely, you'll want to add code dispatching an fr-verify event to your component to trigger a verification, and listeners on the fr-verify-done and fr-verify-error events. For more information on this, see the section Events below.
Similar to reCAPTCHA, you must configure properties in properties-local.xml. You start by enabling Friendly Captcha by setting the following property:
The public key (or application, or "site key") is set with:
The private key is set with:
The private key will remain on the Orbeon Forms server and be sent server-side to the Friendly Captcha API endpoint to verify the captcha. It will never be shown to the end-user.
As of Orbeon Forms 2023.1.4, Orbeon Forms uses version 0.9.16 of the Friendly Captcha widget. You can change the URL to the widget script with the following property:
You can configure the Friendly Captcha start mode with the following property:
Allowed values:
auto: the solver starts as soon as possible after the page loads (the default)
focus: the solver starts when the user focuses in the form or presses the start button in the widget
none: the solver only starts when the user presses the start button
[SINCE Orbeon Forms 2020.1]
The following property allows you to configure where the captcha is shown, if enabled. The possible values are:
form-bottom: displays the captcha at the bottom of the form (default).
inside-wizard: displays the captcha on every page of the wizard.
When all the following conditions are met:
The captcha is shown inside the wizard.
You have set the oxf.fr.detail.captcha.visible.*.* property (see below) to have the captcha show only on certain pages.
Users attempt to save or submit the form, or otherwise perform an action that requires data to be valid.
The captcha hasn't been solved yet.
Then:
While an error will show in the error summary to inform users that the captcha needs to be solved, when users click on the error message, Form Runner will not switch to the page where the captcha appears. (The situation here is somewhat different relative to what happens with normal fields, as depending on how you set the oxf.fr.detail.captcha.visible.*.* property, the captcha could appear on multiple pages.)
The page or pages in which the captcha appear won't be highlighted, as is the case for other invalid fields.
[SINCE Orbeon Forms 2020.1]
Even when not visible according this property (i.e. your value template returns false), as long as the captcha is enabled, solving it is required; so this property isn't intended to be used to dynamically decide whether to have a captcha on a page or not, but it is to decide at what point during the form filling process you want the captcha to show.
The fr:recaptcha, fr:on-premise-captcha (formerly:fr:simple-captcha), and fr:friendly-captcha components support the same events:
Verifying the answer entered by users — Some implementations don't include a Verify button that triggers the value entered by users to be checked. This is to give more control to you, the form author, as to when the verification is done. For instance, you might want to verify the captcha when users click on a Save button on your form. To trigger the value to be verified, dispatch a fr-verify event to the captcha.
Verification succeeded — When the verification succeeds, the component dispatches a fr-verify-done event. The example below, using the reCAPTCHA, listens to that event to run a submission.
Verification failed — When the verification fails, you get the fr-verify-error event. The example below, using the reCAPTCHA, listens to that event to show a case id failure-case (which might tell users the verification failed).
Loading another captcha — Specifically for the reCAPTCHA, as part of the context information for the fr-verify-error event, you get an error code, which you can access with event('fr-error-code'). This is the error code returned by the reCAPTCHA API, which is a string. Its value can either be:
empty — this tells you users didn't provide any answer. When that happens, you could notify users and keep the same challenge.
This enables .
This enables .
This enables the implementation.
This uses to the implementation.
Orbeon Forms supports the reCAPTCHA v2 since Orbeon Forms 2018.1 and 2017.2.2, and reCAPTCHA v3 since Orbeon Forms 2024.1. Google used by earlier versions of Orbeon Forms after March 31, 2018. Hence, if you're using the reCAPTCHA, and are using an older version of Orbeon Forms, you'll want to upgrade to a newer version which supports reCAPTCHA v2 or v3.
First, you need to to get your own public/private key pair.
See the , under Look & Feel Customizations for more information on the possible values for the theme and lang properties.
You must configure keys, which you obtain by signing up with and following their .
inside-wizard-first-page: displays the captcha on the first visible page of the wizard.
inside-wizard-last-page: displays the captcha on the last visible page of the wizard.
Only use inside-wizard, inside-wizard-first-page, or inside-wizard-last-page if your form is using the . If you use one of these tokens without the wizard view, the captcha will not be displayed.
When the captcha is enabled, you can control its visibility with the following property. The default value is true (shown below), and you can use a , to make it dynamic.
One of the values listed in the (look for the table under Error Code Reference). When this happens, you could notify users, and need to change the challenge by dispatching fr-reload to the reCAPTCHA. (For added safety, the reCAPTCHA won't let users try to solve the same captcha multiple times.)
