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.

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.

Glossary

References

Implementations:

• Concept - ReCaptcha (valid to 7.7)
• Concept - ReCaptcha (valid to 7.1)
• Concept - ReCaptcha v2
• Concept - ReCaptcha v3 (valid to 7.10)
• Cookbook - ReCaptcha (valid to 7.7)
• Cookbook - ReCaptcha v2
• Cookbook - ReCaptcha v3
• Concept - SimpleCaptcha (valid to 7.5)

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.

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

Displaying and Generating a CAPTCHA

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

CaptchaFormField

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;

CaptchaInclude

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.

Captcha Validation

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

To use captcha validation, the following things are required:

• Form with a CAPTCHA challenge and an answer form field (See Concept - Captcha Framework - Displaying the Captcha);
• Corresponding webform definition with a reference to the CaptchaValidator at the CAPTCHA answer parameter (see Concept - Webforms for further details in webform and webform validation handling);

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>

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;
  
  

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>

Activation and Configuration

Activation and configuration is done via the Managed Service framework, see Concept - Managed Service Framework for details.

Each feature that uses a CAPTCHA (e.g., the "E-mail to a friend" feature) has a preference that controls the activation/deactivation of the CAPTCHA for that specific feature. These preferences can be viewed in the back office, as shown in 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 then available and configurable in the back office as shown in the next screenshot. Note that the parameters are service-specific.

For information on activating a service, refer to Concept - Managed Service Framework.

bc_captcha

Defined Artifacts Diagram

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

Defined Artifacts Description

CaptchaService

This interface must be implemented by each CAPTCHA service that should be developed. The implementation must be done using the Managed Service 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

This 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