Captcha

Which captcha is right for you

reCAPTCHA is almost a de facto standard on the web: more than a million reCAPTCHA are solved every day, it is used by a large number of mainstream sites, like Facebook, and is constantly updated providing a high level of security. Since 2009, 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, SimpleCaptcha, which runs entirely within Orbeon Forms, without the need to connect to any external server.

Events

Both the fr:recaptcha and fr:simple-captcha components support the same events:

Verifying the answer entered by users — Both components 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.
- One of the values listed in the reCAPTCHA API documentation (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.)
```
<fr:recaptcha id="my-captcha">
    <xf:send ev:event="fr-verify-done" submission="save-submission"/>
    <xf:action ev:event="fr-verify-error">
        <xf:toggle case="failure-case"/>
        <xf:dispatch target="my-captcha" name="fr-reload"/>
    </xf:action>
</fr:recaptcha>
```

reCAPTCHA

Supported versions

Orbeon Forms supports the reCAPTCHA v2 since Orbeon Forms 2018.1 and 2017.2.2, and reCAPTCHA v3 since Orbeon Forms 2024.1. Google stopped supporting reCAPTCHA v1 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.

Usage

You can use this component to show users a captcha, like the one shown in the following screenshot:

First, you need to sign up with reCAPTCHA to get your own public/private key pair.

Store your public keys (now called "site keys") and private keys in your properties, as follows:

<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.recaptcha.v2.public-key"
    value="..."/>
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.recaptcha.v2.private-key"
    value="..."/>
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.recaptcha.v3.public-key"
    value="..."/>
<property
    as="xs:string"
    name="oxf.xforms.xbl.fr.recaptcha.v3.private-key"
    value="..."/>

If your version of Orbeon Forms only supports reCAPTCHA v2 (before Orbeon Forms 2024.1), use the oxf.xforms.xbl.fr.recaptcha.public-key and oxf.xforms.xbl.fr.recaptcha.private-key properties.

Add the reCAPTCHA component to your form:
- For forms you're creating in Form Builder, enable the reCAPTCHA by setting the following property:
  <property as="xs:string" name="oxf.fr.detail.captcha.*.*" value="reCAPTCHA"/>
- 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.
  <fr:recaptcha id="my-recaptcha"/>

Configuration

You can configure:

The theme using properties, either:

For forms you're creating with Form Builder, with:

<property 
    as="xs:string" 
    name="oxf.xforms.xbl.fr.recaptcha.theme.*.*" 
    value="light"/>

For forms you're creating by writing XForms "by hand", with:

<property 
    as="xs:string" 
    name="oxf.xforms.xbl.fr.recaptcha.theme"     
    value="light"/>

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:
```
.orbeon .fr-captcha .xbl-fr-recaptcha.xforms-visited .xforms-alert.xforms-active {
	display: block;
}
```
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:
```
<property
    as="xs:decimal"
    name="oxf.xforms.xbl.fr.recaptcha.v3.score-threshold"
    value="0.5"/>
```

See the reCAPTCHA documentation, under Look & Feel Customizations for more information on the possible values for the theme and lang properties.

Resetting the captcha

[SINCE Orbeon Forms 2022.1.8, 2023.1.3, 2024.1]

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 by adding the following to the process you are running, before the action that navigates away from the page.

then xf:dispatch(
	name     = 'fr-reload',
	targetid = 'fr-captcha'
)

SimpleCaptcha