Captcha Template

There are several processors that utilize captchas to prevent automation. These processors include:

• Request Captcha Processor

  This processor allows you to attach a captcha to any page on the web application. It is also responsible for enforcing the "Force Captcha Validation" counter response.

• Login Processor

  This processor utilizes captchas to prevent brute force attacks on login dialogs. Once there have been more than three (3) failed login attempts on a single username (from any users), any future attempts to login as that user will require a captcha.

When a captcha must be presented, the format in which it is displayed is defined as a Captcha Template. By default, there is a captcha template defined for both processors that will work on all websites. In the event that you would like to customize the way the captcha looks when it is presented (such as wrapping it with the standard template of the website being protected), the captcha template can be modified. This is done by accessing the advanced configuration parameters for the two aforementioned processors and editing the "Captcha Template" parameter.

In order to edit the parameter, it is recommended that you first download a copy of the existing default template. If you have already made modifications to the template, you can get the original by selecting the suggestion "Default Unbranded Template", and then downloading the associated file.

Once you have a copy of the default template, open it in a text editor. You can make any modifications to the HTML as required, but be sure not to modify the existing JavaScript or remove any of the existing HTML. To prevent introducing changes that might prevent the captcha from functioning, it is recommended that modifications be limited to stylistic changes (do not alter the content of the SCRIPT tags, and do not alter the contents of the FORM tag). After your modifications, you can upload the new file into the parameter to update the captcha HTML served by WebApp Secure. It is recommended that you keep a copy of the modified template to make future modifications easier.

You will also notice that there are a few special HTML tags in the template. These tags are replaced by WebApp Secure before the template is served to the end-user. These tags reside either in a SCRIPT tag or in a FORM tag, so as long as those elements are not modified, these tags should continue to function correctly. These special tags include:

• <%captchaDir> The directory name that all captcha images and audio files are served from.
• <%signature> The file name for the captcha image or audio resource to load.
• <%includeAudio>...<%includeAudio> Displays the content between the open and closing tags only if audio captchas are enabled.
• <%cancel> The URL to redirect the user to if they cancel the captcha operation.
• <%delay> The number of seconds the user has to complete the captcha before it expires.
• <%multiPart>...<%multiPart> Displays the content between the opening and closing tag only if the original request that is being protected by a captcha was a multipart form submission (vs. a URL encoded form post [by default, forms are URL encoded]).
• <%datasignature> The signature of the data that was originally posted to the page protected by the captcha. This is used to ensure that the data is not modified after submission, but before the captcha is solved.
• <%data> The encrypted data submitted to the original page that required a captcha. This is used so that once the captcha is solved, the original request can be reconstructed and submitted to the backend servers.
• <%inputname> The name of the input used to identify when a user submits a captcha. The value for this input name is configurable and should not conflict with any existing inputs the site uses. A random string of 5 or more characters should be sufficient (but must be set in configuration so that it can be injected in place of the custom tag when serving a captcha).

After the new template has been uploaded and saved in configuration, you can test your changes by triggering the applicable captcha.

• Request Captcha Processor Access the protected page and request http://www.domain.com/.htaccess which will generate a profile for your session. Find the new profile in the security monitor and manually activate the "Force Captcha Validation" response. Then go back to the protected site and make a few more requests until the captcha shows up.
• Login Processor If the login processor is configured to protect a login dialog on the site, then simply provide 3 or more invalid passwords for the same username. On the 4th attempt, you should be presented with the login processor captcha.

Note: Note: Changes to the captcha template are made to the live deployment. So if you break the captcha template during modifications, it may cause the captcha to stop working for some of the users on the site until the template is repaired. Creating a new "Page" in configuration for a fictitious URL and making the changes on that page first would allow you to test the modifications without impacting every use on the site.