Introduction

This document provides a high-level overview of the Intershop CAPTCHA Framework (cartridges: bc_captcha, ac_captcha_recaptcha).

The bc_captcha cartridge provides all interfaces required to implement a CAPTCHA managed service. The concrete implementations of the individual services (reCAPTCHA V2 and V3) are located in the ac_captcha_recaptcha cartridge.

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 activation and configuration.

It defines the base and ensures that all possible CAPTCHA implementations are done in the same way using the API provided here to connect to Intershop Commerce Management.

Definition

A CAPTCHA protects web sites from bots by generating and scoring tests that humans can pass but current computer programs cannot. For example, humans are able to read distorted text or understand 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

• Cookbook - Captcha Framework
• Concept - ReCaptcha v2
• Concept - ReCaptcha v3
• Cookbook - ReCaptcha v2
• Cookbook - ReCaptcha v3

High Level Overview

The following class diagram shows the major classes and interfaces of the captcha framework that are relevant for the protection of REST resources.

The overview diagram shows:

• ReCaptchServiceImpl is a concrete implementation of the RestCaptchaService interface and thus also of the CaptchaService interface.
• The AuthenticationProvider provides a method to authenticate the corresponding REST Resource.
• CaptchaAuthenticationProvider 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 method invokes the verify method of the class ReCaptchaVerificationService.
• The verify method of the ReCaptchaVerificationService interacts with Google reCAPTCHA backend and returns a CaptchaResponse object.
• The CaptchaResponse contains a method isVaild, which is used by the CaptchaAuthenticationProvider to accept or reject the request.

CAPTCHA Authentication for REST Resource

The CaptchaAuthenticationProvider is already wired and available via the component framework. However, it needs to be added to the resource by adding the following to your component files:

<implementation name="MyNewResource" ...>
    ...
    <requires name="authenticationProvider" contract="AuthenticationProvider" cardinality="0..1" />
</implementation>

<instance with="MyNewResource" name="...">
    ...
    <fulfill requirement="authenticationProvider" with="intershop.B2CWebShop.RESTAPI.CaptchaAuthProvider" />
</instance>

Now the resource knows of its authentication provider and can use it to protect certain calls:

public class MyNewResource extends AbstractRestResource
{
    ...
    @POST
    public Response addSomeItem(SomeItemRO someItem)
    {       
        if (authenticationProvider != null && authenticationProvider instanceof CaptchaAuthenticationProvider)
        {
            CaptchaAuthenticationProvider cap = (CaptchaAuthenticationProvider)authenticationProvider;
            if (cap.isCaptchaRequired("intershop.CaptchaPreferences.NewSomeItemPreference"))
            {
                cap.authenticate(currentRequest, currentResponse);
            }
        }
        ...
        // create the item
        ...
        return RestResponse.created(uriToNewItem);
    }
    ...
}

If a REST Resource is protected by the CaptchaAuthenticationProvider, the client has to add a corresponding authorization header to the request:

Authorization: CAPTCHA recaptcha_token=<captcha token> action=<ICM captcha feature>

The CAPTCHA token will always be provided by the Google reCAPTCHA framework. The determination of the token depends on the CAPTCHA version used and must be implemented by the client, see CAPTCHA in the PWA @GitHub. The action corresponds to the selectable CAPTCHA channel preferences in ICM. If these preferences are disabled in ICM, then the CAPTCHA validation for this topic is also disabled in the REST resource.

Webform CAPTCHA protection

For more information on implementing CAPTCHA functionality in the PWA, see CAPTCHA in the PWA @GitHub.

The PWA uses the Angular Formly framework to handle web forms. The framework allows you to define types that can be used by the fields of the form.

For the integration of the CAPTCHA functionality, a special type has been implemented. You can bind a field of this type to any Formly form, so that this form is validated according to CAPTCHA.

This field is declared in src.app.shared.formly.types.captcha-field.captcha-field.component.ts and registered in the src.app.shared.formly.types.types.module.ts.

This makes it very easy to protect any web form by using the CAPTCHA functionality. The following example shows how to add a CAPTCHA field of type ‘ish-captcha-field’ to any Formly form.

First the TypeScript file of the component:

export class ExamplePageComponent implements OnInit {
  ...
  fields: FormlyFieldConfig[];
  exampleFormGroup = new UntypedFormGroup({});
  ...
  ngOnInit() {
    ...
    this.fields = [
        {
          type: 'ish-captcha-field',
          props: {
            topic: 'forgotPassword',
          },
        },
      ];
  }
 ...
}

The type ‘ish-captcha-field’ is registered at src.app.shared.formly.types.types.module.ts. Additionally, the module binds the corresponding field component to this type. The topic which is to be set corresponds to the selectable CAPTCHA channel preferences in ICM. If the respective preference is disabled in ICM, the CAPTCHA validation for this topic is disabled in the PWA as well.

The following table shows the mapping between the existing PWA CAPTCHA topic names and the CAPTCHA channel preferences in the ICM:

The following code block shows an example of the HTML syntax of the component:

<form name="ExampleForm" [formGroup]="exampleFormGroup" (ngSubmit)="submitForm()">
  <formly-form [form]="exampleFormGroup" [fields]="fields"></formly-form>

  <div class="row form-group">
    <div class="offset-md-4 col-md-8">
      <button
        type="submit"
        value="exampleButtonValue"
        name="exampleButtonName"
        class="btn btn-primary"
        [disabled]="buttonDisabled"
      >
        {{ 'example.form.send.button.label' | translate }}
      </button>
    </div>
  </div>
</form>

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