How to reCAPTCHA Your Java Application

ReCAPTCHA is a novel CAPTCHA system developed by the School of Computer Science at my alma mater, Carnegie Mellon University. I won't explain its coolness here since they do a good job of explaining that coolness themselves. What I will do here, though, is explain how to get your Java app reCAPTCHAed very quickly. Note however that reCAPTCHA is not tied specifically to Java.

In this tutorial I'm using Spring 2.5 MVC with annotations, and Commons Validator, but you'll be able to follow this whether or not you're using Spring and Validator.

These instructions are based on the instructions from the reCAPTCHA site, but I'm focusing specifically on Java integration whereas the site makes you dig around a bit to get the information. Not too bad, but enough that there's value in my writing a Java-specific tutorial. :-)

Step 1. Get your account and key pair

First, go to the reCAPTCHA web site and create an account. As part of that account creation process you'll have to specify the domain your reCAPTCHA will be protecting. The reCAPTCHA site will will give you a key pair for that domain. The key pair allows you to authenticate your reCAPTCHA requests to the reCAPTCHA servers, as we'll see.

Step 2. Put the reCAPTCHA JavaScript in your app's form

Here's the JavaScript you need to put in your form, meaning in between the <form> and </form> tags. Put it wherever you would have normally put a CAPTCHA text box. This JavaScript will generate the reCAPTCHA box when users request the page:

<script type="text/javascript"
    src="http://api.recaptcha.net/challenge?k=<your_public_key>">
</script>
<noscript>
    <iframe src="http://api.recaptcha.net/noscript?k=<your_public_key>"
        height="300" width="500" frameborder="0"></iframe><br>
    <textarea name="recaptcha_challenge_field" rows="3" cols="40">
    </textarea>
    <input type="hidden" name="recaptcha_response_field" 
        value="manual_challenge">
</noscript>

It probably goes without saying, but I'll say it anyway: you need to replace the two instances of <your_public_key> with the public key that you received during the account creation process. Be careful that you don't use your private key by mistake. If you do that then everybody will be able to see your private key and act like they're you.

Step 3. Run your app and make sure the reCAPTCHA is showing up

You should see it there in your form. It's OK if you are coming from localhost or 127.0.0.1 instead of the domain that you specified in the account creation step; reCAPTCHA will allow that. You should be able to click the buttons on the reCAPTCHA box and they should work.

After you goof around with that a bit, you'll need to update your app itself so that it actually uses the reCAPTCHA box to validate the form submission.

Let's turn now to the Java piece, where we validate the form and reCAPTCHA.