Document Properties
Kbid
30H955
Last Modified
24-Jul-2023
Added to KB
24-Jul-2023
Public Access
Everyone
Status
Online
Doc Type
Concepts
Product
  • ICM 7.10
  • ICM 11
  • ICM 12
Concept - Captcha Framework

Introduction

Info

This concept is valid from 7.10.40.0 and ICM 11. For previous versions, refer to Concept - Captcha Framework (valid to 7.10).

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

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

References

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:

implementations.component
<implementation name="MyNewResource" ...>
    ...
    <requires name="authenticationProvider" contract="AuthenticationProvider" cardinality="0..1" />
</implementation>
instances.component
<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:

Example REST Resource
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 Header
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.

types.module.ts

Depending on which CAPTCHA service (V2 or V3) is used in ICM, the captcha-field.component.ts component acts as a provider and integrates the specific CAPTCHA components required for that version.

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:

Example page component syntax
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:

CaptchaTopicICM Settings
contactUsContact Us
emailShoppingCartE-mail Shopping Cart
forgotPasswordForgot password
redemptionOfGiftCardsAndCertificatesRedemption of Gift Cards & Certificates
registerRegistration


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

Example HTML syntax
<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

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.
Home
Knowledge Base
Product Releases
Log on to continue
This Knowledge Base document is reserved for registered customers.
Log on with your Intershop Entra ID to continue.
Write an email to supportadmin@intershop.de if you experience login issues,
or if you want to register as customer.