CAPTCHA API

Last modified by Admin on 2024/10/01 01:41

status_busyAPI to generate and validate CAPTCHAs.
TypeJAR
CategoryAPI
Developed by

XWiki Development Team

Rating
LicenseGNU Lesser General Public License 2.1
Bundled With

XWiki Standard (XWiki 10.8RC1+)

Compatibility

XWiki 10.8RC1+

Installable with the Extension Manager

Description

The main thing you need, when using a CAPTCHA, is to be able to display the CAPTCHA inside your form, so that the human user can solve it and to be able to validate the user's response, on the server side.

To get the default CAPTCHA (i.e. the one configured using the CAPTCHA Application), all you need to do is: 

$services.captcha.default

If you always want a specific implementation (not recommended), ignoring the configured one, but as long as it is installed on the XWiki instance:

$services.captcha.<implementationName>
## e.g.
$services.captcha.jcaptcha
## or
$services.captcha.recaptcha

Finally, to display the CAPTCHA:

$services.captcha.default.display()

Once the user submits your form, together with their answer to the proposed CAPTCHA, you need to validate it:

#if (!$services.captcha.default.isValid())
 {{error}}Hey! We don't serve their kind here! (http://starwars.wikia.com/wiki/Anti-droid_sentiment){{/error}}
#end

Both display and validate operations also accept an optional parameters map, useful when you want to go beyond the configured parameters or even the configured default CAPTCHA in your form. Example:

$services.captcha.default.display({'type' : 'sound', 'engine' : 'com.octo.captcha.engine.sound.speller.SpellerSoundCaptchaEngine'})

Just make sure that, when using custom parameters on the display, you use the same parameters for the validation as well, or the user's answer might not validate correctly:

$services.captcha.default.isValid({'type' : 'sound', 'engine' : 'com.octo.captcha.engine.sound.speller.SpellerSoundCaptchaEngine'})

For other API methods, see the CaptchaScriptService.

Implementing your own CAPTCHA

Components you will need:

  • A Captcha component implementation. It is recommended to extend the AbstractCaptcha (example) base class which simplifies things by adding some simple conventions:
    • A Displayer document (example) that will render the CAPTCHA
      • When evaluating the Displayer, the script context will contain a captchaParameters map that will be holding the CAPTCHA's configuration parameters, as read from the configuration document, including possible default values where it's the case (i.e. nothing specified in the configuration document)
      • The Displayer's JavaScript, if it has any, will have to re-evaluate whenever the xwiki:captcha:reloaded event will be triggered (example), signaling that the CAPTCHA has been reloaded (e.g. by some AJAX call)
    • A ConfigurationClass that will define the CAPTCHA's configuration properties
    • A Configuration document that will hold the CAPTCHA's configuration
    • An Administration document that will present the CAPTCHA's configuration, when the CAPTCHA is enabled. It will implement the org.xwiki.captcha UIXP (example).
    • A Translations document (example) that provides, at minimum, the text the CAPTCHA's name (i.e. when enabling it in Administration).

Reference implementations:

Prerequisites & Installation Instructions

We recommend using the Extension Manager to install this extension (Make sure that the text "Installable with the Extension Manager" is displayed at the top right location on this page to know if this extension can be installed with the Extension Manager).

You can also use the manual method which involves dropping the JAR file and all its dependencies into the WEB-INF/lib folder and restarting XWiki.

Dependencies

Dependencies for this extension (org.xwiki.platform:xwiki-platform-captcha-api 16.8.0):

Get Connected