Document Properties
Last Modified
Added to KB
Public Access
Doc Type
  • ICM 7.10
  • ICM 11
  • ICM 12
Concept - Captcha Framework



This concept is valid from 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.


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.





Functionality to protect against spam or bots


The audio/video task to solve


Create an audio/a video challenge


Check the given solution for a challenge


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" />
<instance with="MyNewResource" name="...">
    <fulfill requirement="authenticationProvider" with="intershop.B2CWebShop.RESTAPI.CaptchaAuthProvider" />

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

Example REST Resource
public class MyNewResource extends AbstractRestResource
    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 and registered in the


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 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

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">
        class="btn btn-primary"
        {{ 'example.form.send.button.label' | translate }}

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.


Defined Artifacts Diagram

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

Defined Artifacts Description


This interface must be implemented by each CAPTCHA service that should be developed. The implementation must be done using the Managed Service framework.



This interface defines the core capabilities for the CAPTCHA services.


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



This class defines a data container used to hand over the CAPTCHA check output data (method verifyCaptcha in CaptchaService) back to the 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;



Contains the reference to the CaptchaValidator.



Encapsulates the functionality to display and validate a CAPTCHA implementation.



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



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


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.
The Intershop Knowledge Portal uses only technically necessary cookies. We do not track visitors or have visitors tracked by 3rd parties. Please find further information on privacy in the Intershop Privacy Policy and Legal Notice.
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 if you experience login issues,
or if you want to register as customer.