Document Properties
Kbid2B8550
Last Modified22-Jun-2020
Added to KB25-Jan-2018
Public AccessEveryone
StatusOnline
Doc TypeGuidelines, Concepts & Cookbooks
Product
  • ICM 7.7
  • ICM 7.8
  • ICM 7.9
  • ICM 7.10

Concept - Captcha Framework

1 Introduction

This document gives a high level overview of the Enfinity Captcha Framework (cartridge: bc_captcha).

The captcha framework provides the ability to connect to any captcha validation service/provider or implementation. The implementation is based on the Overview - Managed Service Framework for easy activating and configuration.

It defines the base and ensures that all possible captcha check implementations are done the same way using the here given API to connect with Enfinity.

1.1 Definition

A CAPTCHA is a program that protects websites against bots by generating and grading tests that humans can pass but current computer programs cannot. For example, humans are able to read distorted text or alienated audio sound, but current computer programs are not.

The term CAPTCHA (for Completely Automated Public Turing Test To Tell Computers and Humans Apart) was coined in 2000 by Luis von Ahn, Manuel Blum, Nicholas Hopper and John Langford of Carnegie Mellon University.

1.2 Glossary

Name

Meaning

captcha

functionality to protect against spam or bots

challenge

the audio/video task to solve

generate

create an audio/a video challenge

validate

check the given solution for a challenge

1.3 References

Implementations:

2 High Level Overview

The following class diagram shows the major classes and interfaces of the captcha framework that are relevant for the most use cases.

captcha framework overview

The overview diagram shows:

  • CaptchaCapabilities configures the core functionality of the CaptchaService implementation
  • template module "CaptchaFormField" invokes the implementation of the interface CaptchaService to create a captcha
  • CaptchaValidator is defined in the webform definition (Captcha.webform)
  • CaptchaValidator invokes the implementation of the interface CaptchaService to verify a captcha response
  • CaptchaResponse is a data container for the verification response

3 Displaying and Generating a CAPTCHA

The framework wraps the displaying/generating of a captcha in two template modules described below.

3.1 CaptchaFormField

bc_captcha\staticfiles\cartridge\templates\default\modules\captcha\CaptchaFormField.isml

A form containing a CAPTCHA includes at least the <isCaptchaFormField> template module wherever the CAPTCHA appears.

The module <isCaptchaFormField> checks the following preconditions:

  • Is a CAPTCHA service implementation available (enabled for the current channel);
  • CAPTCHA preference for this feature is "on";
  • The user is NOT logged in;

The last precondition is controversial and it may be dropped in future releases. Alternatively, some brute force protection might be implemented for logged in adversaries. Currently CAPTCHAs are not displayed for logged in customers.

If the preconditions are fulfilled, the module invokes:

  • The prepareViewCaptcha method defined in the CaptchaService interface which returns a map containing all necessary data to display the CAPTCHA (the actual creation of the CAPTCHA is service-specific and has to be done in each captcha service implementation);
  • The getCaptchaTemplate method defined in the CaptchaCapabilities interface to include the service-specific template (the actual template is service-specific and has to be created in each captcha service implementation);

By calling the two methods mentioned above, the process of creation of the CAPTCHA (e.g., an image or an audio challenge) and the corresponding user input fields are covered. It is important to note that:

  • The actual work of creating captcha image and input fields is CAPTCHA service-specific and therefore needs to be done in the service-specific template referenced by the getCaptchaTemplate method;
  • The prepareViewCaptcha responds a Map with all data needed to render the CAPTCHA;
  • In the service-specific template you can access the map by the key captchaFormData;

3.2 CaptchaInclude

bc_captcha\staticfiles\cartridge\templates\default\modules\captcha\CaptchaInclude.isml

The second module comes into play if the captcha implementation needs any static or global data (e.g., CSS and/or Javascript).

Therefore the module is included in the header section of the HTML site.

The module <isCaptchaFormField> checks the following preconditions:

  • Is a CAPTCHA service implementation available (enabled for the current channel);
  • CAPTCHA preference for this feature is "on";
  • The CaptchaCapabilities demands a header template;

If the preconditions are fulfilled, the module invokes:

  • The prepareViewCaptchaHeader method defined in the CaptchaService interface which returns a map containing all necessary data for the header template (the required data of the CAPTCHA is service-specific and has to be done in each CAPTCHA service implementation);
  • The getCaptchaHeaderTemplate method defined in the CaptchaCapabilities interface to include the service-specific header template (the actual header template is service-specific and has to be created in each captcha service implementation);

By calling the two methods mentioned above, the process of preparing the required data to include static files and to include the service-specific header template (contains the reference to static files or static code blocks) are covered.

  • The module is responsible for adding necessary javascript or css to the html site header.;
  • The actual work of creating these things is CAPTCHA-service-specific and therefore needs to be done in the service-specific header template.
  • The prepareViewCaptchaHeader responds a map with all data needed in the service-specific header template.
  • In the template the map can be accessed by the key captchaHeaderData.

4 Captcha Validation

The framework wraps the validation as described in the following section.

To use captcha validation, the following things are required:

A webform definition example is shown below:

<parameters xsi:type="webform:FormParameter" optional="false" name="<yourCaptchaAnswerParameterName>" type="java.lang.String">
    <validatorBindings validator="Captcha-ValidatorCaptcha">
       <parameterBindings xsi:type="core:ParameterValueBinding" name="<yourCaptchaPreferenceName>" value="<yourFeatureCaptchaPreferenceID>"/>
    <validator/>
</parameters>

Note

The framework contains a webform definition Captcha.webform to provide an access to the validator in every webform. It is located at bc_captcha\staticfiles\cartridge\webforms\Captcha.webform.

A CAPTCHA form parameter must never be optional. If the parameter is made optional, a malicious user could remove the form field from the source code in its web browser and the validation would still pass.

4.1 Submitting a Form

If a form with a CAPTCHA is submitted and the corresponding webform parameter contains a reference to the CaptchaValidator, the following preconditions are checked:

  • Is a CAPTCHA service implementation available (enabled for the current channel);
  • Captcha preference for this feature is "on";
  • The user is not logged in;

If the preconditions are not fulfilled, the validator will always succeed.

If the preconditions are fulfilled:

  • The validator collects all webform parameters and additionally all request form parameters which are not contained in the webform. They are put in a map (Map<String, Object>);
  • It invokes the verifyCaptcha method defined in the CaptchaService interface;
  • The actual verification of the CAPTCHA is service-specific and has to be done in the verifyCaptcha method of each CAPTCHA service implementation;
  • The validator receives a response data container CaptchaResponse containing the verification result;
  • The container will be evaluated from the validator to set a validation error or validation success;

Note

Together with the current field (which is the field the validator is connected to) the from parameter map is given as arguments to the verifyCaptcha method of the captcha service. The current field name should contain a prefix. Using this prefix, all other fields which belong to the captcha service may be found with the help of this prefix in the map with all sent parameters.

In case of a validation error an error message should be displayed. This is not handled by the ISML module to keep the possibility of free placement and design of the error message. Nevertheless, this can be easily achieved by using the webform functionality. See the example below:

<isif condition="#ForgotPasswordFormStep1:recaptcharesponsefield:isError("error.captcha")#">
    <istext key="captcha.yourErrorText"/>
</isif>

5 Activation and Configuration

Activation and configuration is done by using the Enfinity Managed Services framework (see Concept - Managed Service Framework for further details).

Each feature that uses a CAPTCHA (e.g., the "E-mail to a friend" feature) has a preference that controls the on/off switching of CAPTCHA for the specific feature. These preferences may be seen in the back office as shown on the next screenshot.

Dynamic configuration of each CAPTCHA service is possible as described in the Concept - Managed Service Framework. Basically the two important steps are:

  • Define the parameters in staticfiles/configdef;
  • Create localization values in sld_enterprise_app or a similar cartridge;

The dynamic parameters are available and configurable in the back office then as shown on the next screenshot. Of course they are service-specific.

A service may be activated as any Concept - Managed Service Framework.

6 bc_captcha

6.1 Defined Artifacts Diagram

The following image shows the defined interfaces and classes. An explanation of each follows below.

captcha framewrok artefacts v2


6.2 Defined Artifacts Description

CaptchaService

This interface needs to be implemented by every CAPTCHA service that should be developed. The implementation needs to be done using the Enfinity Managed Services framework.

com.intershop.component.captcha.capi.CaptchaService

CaptchaCapabilities

This interface defines the core capabilities for the CAPTCHA services.

Basically:

  • References to the used templates;
  • Is a header template required;

com.intershop.component.captcha.capi.CaptchaCapabilities

CaptchaResponse

This class defines a data container used to hand over the CAPTCHA check output data (method verifyCaptcha in CaptchaService) back to the CaptchaValidator.

com.intershop.component.captcha.internal.CaptchaResponse

CaptchaValidator

The class is referenced in the Captcha.webform definition for the webform parameter holding the CAPTCHA answer. In this class the CAPTCHA validation service implementation (method verifyCaptcha) is invoked.

Preconditions are:

  • Captcha Check is available and active;
  • Captcha Check is enabled for the channel;
  • Captcha Check is enabled for the feature;
  • User is not logged in;

com.intershop.component.captcha.internal.CaptchaValidator

Captcha.webform

Contains the reference to the CaptchaValidator.

bc_captcha\staticfiles\cartridge\webforms\Captcha.webform

CaptchaFormField.isml

Encapsulates the functionality to display and validate a CAPTCHA implementation.

bc_captcha\staticfiles\cartridge\templates\default\modules\captcha\CaptchaFormField.isml

CaptchaInclude.isml

Encapsulates static includes (CSS, JS, etc.) required by the CAPTCHA implementation.

bc_captcha\staticfiles\cartridge\templates\default\modules\captcha\CaptchaInclude.isml

Modules.isml

Conatins the module definition for the two ISML template modules mentioned above.

bc_captcha\staticfiles\cartridge\templates\default\modules\captcha\modules.isml

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets