Summary

Grails plugin that creates simple image CAPTCHAs that protect against automated completion and submission of HTML forms.

Grails Versions

Versions of this plugin that are compatible with Grails 1.X and 2.X are on the master branch. Grails 3.X compatible versions are on the grails3 branch. The first Grails 3 compatible version is 1.0.0-grails3.

Description

Overview

A CAPTCHA is a small image that is embedded in a HTML form to protect against automated completion and submission of HTML forms. They generally consist of an image of a short string of random characters visually obsfucated in some way (see wikipedia for more information).

This plugin generates a small CAPTCHA image when the CaptchaController is invoked. The CAPTCHA image and it's solution is stored in the session by default, though the pugin can be used without session storage if necessary. A typical example of the CAPTCHAs generated by this plugin is shown below.

Why another CAPTCHA plugin?

Although there is already a Grails plugin available for reCAPTCHA (a very popular CAPTCHA implementation), there are a number of differences between these two plugins:

• reCAPTCHA can be slow to load because the CAPTCHA image is created and solved at a remote server. This plugin creates its own CAPTCHA images, so no remote requests are required to create or solve the CAPTCHAs
• reCAPTCHA challenges can be very difficult to solve, whereas the CAPTCHAs generated by this plugin are very easy to solve
• The solution of this plugin's CAPTCHA challenges is case insensitive
• The CAPTCHAs generated by this plugin can be displayed in multiple places on the same page, there is no easy way to do this with reCAPTCHA

On the other hand, reCAPTCHA provides a number of features that are absent from this plugin, e.g. audio CAPTCHAs for those with impaired vision.

Usage

A CAPTCHA can be added to a form using the following GSP code

<img src="${createLink(controller: 'simpleCaptcha', action: 'captcha')}"/>
<label for="captcha">Type the letters above in the box below:</label>
<g:textField name="captcha"/>

As mentioned above, the CAPTCHAs generated by this plugin can be simultaneously displayed in several places on the same page (this is only possible with reCAPTCHA if you use JavaScript to clone the CAPTCHA).

To check whether the solution to the CAPTCHA is correct:

class MyController {
  def simpleCaptchaService
  // This is the action that handles the submission of the form with the CAPTCHA
  def save = {
    boolean captchaValid = simpleCaptchaService.validateCaptcha(params.captcha)   
  }
}

The process of validating a CAPTCHA also removes it from the session, so it is only possible to validate each CAPTCHA once. The CAPTCHA is removed from the seesion after validation to ensure that the next time a CAPTCHA is requested, a different challenge will be presented.

Configuration

The plugin provides a number of optional configuration parameters that can be overriden in Config.groovy. The default values of these parameters are shown below:

simpleCaptcha {
    // font size used in CAPTCHA images
    fontSize = 30
    height = 200
    width = 200
    // number of characters in CAPTCHA text
    length = 6

    // amount of space between the bottom of the CAPTCHA text and the bottom of the CAPTCHA image
    bottomPadding = 16

    // distance between the diagonal lines used to obfuscate the text
    lineSpacing = 10

    // the charcters shown in the CAPTCHA text must be one of the following
    chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"

    // this param will be passed as the first argument to this java.awt.Font constructor
    // http://docs.oracle.com/javase/6/docs/api/java/awt/Font.html#Font(java.lang.String,%20int,%20int)
    font = "Serif"
}

Per-Locale Configuration

The characters that are shown in the CAPTCHA can be configured per-locale. For example, if you want only the characters ùûüÿÿàâê to be shown by the CAPTCHA in the French locale, add the following to messages_fr.properties

simpleCaptcha.chars=ùûüÿÿàâê

If a locale-specific configuration is found it will override the global configuration in Config.groovy

Session Storage

The plugin stores the CAPTCHA image and its solution in the session by default. If it is not feasible to use session storage, the plugin can instead store a digest (hash) of the solution in a cookie. When a CAPTCHA solution is submitted, it is validated by comparing the digested solution with this cookie value. This option can be enabled simply by adding the following config parameter:

simpleCaptcha.storeInSession = false

If session storage is disabled it is not possible to display a CAPTCHA in multiple places on the same page.