How To Add BotDetect CAPTCHA Protection to JSP Forms

Protecting your JSP forms with BotDetect Java Captcha requires a few steps, outlined on this page. Displaying the Captcha challenge can be as simple as:

<%
  // Adding BotDetect Captcha to the page
  Captcha captcha = Captcha.load(request, "exampleCaptcha");
  captcha.setUserInputID("captchaCode");

  String captchaHtml = captcha.getHtml();
  out.write(captchaHtml);
%>

<input id="captchaCode" type="text" name="captchaCode" />

and checking user input when the form is submitted:

boolean isHuman = captcha.validate(request.getParameter("captchaCode"));

First Time Here?

Check the BotDetect JSP Captcha Quickstart for key integration steps.

You can also see how BotDetect Captcha protection has been added to various kinds of JSP forms and projects by running the BotDetect Captcha JSP integration code examples coming with the BotDetect installation. You can also reuse the code example source code that fits your requirements.

CAPTCHA Integration Steps

To add BotDetect Captcha protection to a JSP application:

Add BotDetect library in the classpath
Register CaptchaServlet
Display Captcha protection on the JSP form
Validate Captcha user input during JSP form submission

Add BotDetect Java CAPTCHA Library Dependency

Here is how to add BotDetect Java CAPTCHA Library dependency in various dependency management scenarios:

Manual
Maven
Gradle
Ant+Ivy
Ant

Install BotDetect Java CAPTCHA dependencies

Download and unpack the BotDetect Java CAPTCHA library archive.

The folder where you unpacked the BotDetect archive will be referred as the <BDC-DIR> in this guide. It contains the BotDetect jars.

Copy the .jar files listed below to /your-app-backend-folder/WEB-INF/lib folder:

<BDC-DIR>/botdetect-4.0.beta3.7.jar
<BDC-DIR>/botdetect-servlet-4.0.beta3.7.jar
<BDC-DIR>/botdetect-jsp20-4.0.beta3.7.jar

Install BotDetect Java CAPTCHA dependencies

The free version Maven artifacts are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To reference the BotDetect dependency from our public repository, the repository itself has to be declared first -- add the highlighted lines to your app's pom.xml file:

<repository>
  <id>captcha</id>
  <name>BotDetect Captcha Repository</name>
  <url>https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/</url>
</repository>

Then, in the same file, declare the BotDetect dependency, too:

<dependency>
  <groupId>com.captcha</groupId>
  <artifactId>botdetect-jsp20</artifactId>
  <version>4.0.beta3.7</version>
</dependency>

Install BotDetect Java CAPTCHA dependencies

The free version Maven artifacts are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To reference the BotDetect dependency from our public repository, the repository itself has to be declared first -- add the highlighted line to your app's build.gradle file:

repositories {
  maven {
    url "https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/"
  }
  ...    
}

Then, in the same file, declare the BotDetect dependency, too:

dependencies {
  ...
  compile 'com.captcha:botdetect-jsp20:4.0.beta3.7'
  ...
}

Install BotDetect Java CAPTCHA dependencies

The free version Maven artifacts are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To reference the BotDetect dependency from our public repository, the repository itself has to be declared first -- add the highlighted line to your app's ivy-settings.xml file:

<ivysettings>
  <properties file="build.properties" />
  <settings defaultResolver="default-chain"/>
  <resolvers>
    <chain name="default-chain">
      <ibiblio name="botdetect" 
               root="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:" 
               m2compatible="true"/>
      ...
    </chain>
  </resolvers>
</ivysettings>

Then, declare the BotDetect dependency in your app's ivy.xml file:

<ivy-module version="2.0">
  <info organisation="org.apache" module="WebProject" />

  <!-- Classpath management, thanks Maven -->
  <configurations>
    <conf name="compile" description="compile dependencies"/>
    <conf name="runtime" description="runtime dependencies" extends="compile"/>
    <conf name="test"    description="test dependencies" extends="runtime"/>
  </configurations>

  <dependencies>
    <dependency org="com.captcha" 
	        name="botdetect-jsp20" 
	        rev="4.0.beta3.7" 
	        conf="compile->default"/>
    ...
  </dependencies>
</ivy-module>

And then, ensure that your app's build.xml file has a build target with the ivy:retrieve task:

<target name="resolve" description="retrieve dependencies with ivy">
  <echo message="Getting dependencies..." />
  <ivy:retrieve />
  <ivy:cachepath pathid="compile.path" conf="compile" />
  <ivy:cachepath pathid="runtime.path" conf="runtime" />
  <ivy:cachepath pathid="test.path" conf="test" />
</target>

Install BotDetect Java CAPTCHA dependencies

The free version BotDetect jars are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To declare the BotDetect dependencies from our public repository, an additional target has to be added to your app's build.xml file.

The target name will be the botdetect-dependencies-target, and it should consist of the following lines:

<target name="botdetect-dependencies" description="BotDetect Java CAPTCHA library">
    <echo message="Getting BotDetect..." />
    <mkdir dir="lib" />
    <get src="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/com/captcha/botdetect/4.0.beta3.7/botdetect-4.0.beta3.7.jar" dest="lib/botdetect-4.0.beta3.7.jar" usetimestamp="true" />
    <get src="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/com/captcha/botdetect-servlet/4.0.beta3.7/botdetect-servlet-4.0.beta3.7.jar" dest="lib/botdetect-servlet-4.0.beta3.7.jar" usetimestamp="true" />
    <get src="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/com/captcha/botdetect-jsp20/4.0.beta3.7/botdetect-jsp20-4.0.beta3.7.jar" dest="lib/botdetect-jsp20-4.0.beta3.7.jar" usetimestamp="true" />
</target>

To retrieve BotDetect dependencies during the build, reference the botdetect-dependencies-target inside the depends attribute of your compile target, by adding the lines listed below into the same file:

<target name="compile" depends="botdetect-dependencies">
  <copydir src="${web.dir}" dest="${build.dir}" />
  <mkdir dir="${web.classes.dir}" />
  <javac destdir="${web.classes.dir}" source="${jdk.version}" target="${jdk.version}"
    debug="true" includeantruntime="false" classpathref="compile.path">
    <src path="${src.dir}" />
  </javac>
</target>

[back to top]

Register `CaptchaServlet`

Update your application configuration (web.xml) file.

<servlet>
  <servlet-name>BotDetect Captcha</servlet-name>
  <servlet-class>com.captcha.botdetect.web.servlet.CaptchaServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>BotDetect Captcha</servlet-name>
  <url-pattern>/botdetectcaptcha</url-pattern>
</servlet-mapping>

[back to top]

Display Captcha Protection on the JSP Form

We'll assume you already have a form which can be posted (<form method="post" ...), with other fields in place.

JSP Scriptlet
Captcha Tag

This approach is especially useful when <form> tag has no action attribute since Captcha object will already be instantiated for validation.

First, on the top of the JSP form source file add:

<%@page import="com.captcha.botdetect.web.servlet.Captcha"%>

To display the Captcha test on your form, you will need the following Html elements:

A textbox for the Captcha code user input, with a label displaying Captcha instructions
The Captcha markup including the image, sound and reload icons etc., which will be generated by the Captcha library

For example:

<label for="captchaCode" class="prompt">
  Retype the characters from the picture:</label>

<%
  // Adding BotDetect Captcha to the page
  Captcha captcha = Captcha.load(request, "exampleCaptcha");
  captcha.setUserInputID("captchaCode");

  String captchaHtml = captcha.getHtml();
  out.write(captchaHtml);
%>

<input id="captchaCode" type="text" name="captchaCode" />

The JSP scriptlet above creates a new instance of the Captcha class defined by the BotDetect Java Captcha library, tells it which textbox is used to input Captcha codes (default is captchaCode), and calls the getHtml() method to generate all needed BotDetect Html elements.

BotDetect custom captcha tag is designed to add CAPTCHA protection to JSP form as simple as possible.

At the top of the file put BotDetect taglib declaration:

<%@taglib prefix="botDetect" uri="https://captcha.com/java/jsp"%>

Boilerplate Html elements are the same as in previous example, but JSP scriptlet is replaced with custom tag:

<label for="captchaCode" class="prompt">
    Retype the characters from the picture:</label>
<botDetect:captcha id="exampleCaptchaTag" userInputID="captchaCode"/>
<input id="captchaCode" type="text" name="captchaCode" />

[back]

When you open your form in a browser, the above declarations should render as:

If you are adding Captcha protection to multiple JSP forms in the same website, you should initialize each Captcha object with unique name (e.g. "registrationCaptcha", "commentCaptcha", ...).

[back to top]

Validate Captcha User Input During JSP Form Submission

Since we want to ensure only real human users can perform a certain action (e.g. account registration or comment submission), we also have to add Captcha validation code which will process form submissions, and only allow certain actions if Captcha validation succeeds.

Form Has No Action

In the simplest case (when the form posts to itself, i.e. the action attribute is not set), you will process form submissions on the form itself:

<%
  if ("POST".equalsIgnoreCase(request.getMethod())) { 
    boolean isHuman = captcha.validate(request.getParameter("captchaCode"));
    if (isHuman) {
      // TODO: Captcha validation passed, perform protected action
    } else {
      // TODO: Captcha validation failed, show error message
    }
  }
%>

The above code is very simple:

The if ("POST".equalsIgnoreCase(request.getMethod())) { line ensures the code only runs when the form is submitted.
The boolean isHuman = captcha.validate( request.getParameter("captchaCode")); line calls the validate(String userInput) method of the Captcha object, which returns true if the submitted Captcha code matches the one used for Captcha image generation, or false otherwise.

This approach is shown in the BotDetect basic JSP integration code example included in the BotDetect download package.

Separate Servlet Processing Action

If your form posts to a separate servlet, you can use the same Captcha validation code. You just have to create Captcha object instance with the same name as the one used on the form first:

Captcha captcha = Captcha.load(request, "exampleCaptcha");
// validate the Captcha to check we're not dealing with a bot
boolean isHuman = captcha.validate(request.getParameter("captchaCode"));
if (isHuman) {
  // TODO: Captcha validation passed, perform protected action
} else {
  // TODO: Captcha validation failed, show error message
}

RequestDispatcher dispatcher = getServletContext().getRequestDispatcher("/index.jsp");
dispatcher.forward(request, response);

In this trivial case response is redirected back to original form.

This approach is shown in the BotDetect JSP Captcha Tag integration code example included in the BotDetect download package.

[back to top]

Please Note

BotDetect Java Captcha Library v4.0.Beta3.7 is an in-progress port of BotDetect 4 Captcha, and we need you to guide our efforts towards a polished product. Please let us know if you encounter any bugs, implementation issues, or a usage scenario you would like to discuss.