Introduction

reCAPTCHA v2 is a CAPTCHA service implementation from Google. It provides website protection against automated bots and spam by adding an additional widget to web forms which verifies that the user accessing the page is a real human being. In contrast to the first version, users are now no longer required to solve hard to identify text CAPTCHA challenges each time they submit a form. They now only need to solve an image challenge once and afterwards only have to tick a box to successfully verify that they're indeed human.

A typical reCAPTCHA v2 challenge workflow looks as follows:

• If a user is considered trustworthy by Google's backend (e.g., because he has already solved a CAPTCHA challenge successfully before), the service will recognize this and mark the CAPTCHA as successfully solved. No further input is required.
  

• If the user has not solved a CAPTCHA before or the Google backend cannot confidently predict if the user is human, a visual CAPTCHA challenge will be presented and the user is required to solve it:

• Alternatively, the user may decide to solve an audio CAPTCHA challenge instead:

• Once the user has successfully solved the CAPTCHA (or was already automatically recognized as trustworthy), the protected form can be submitted.

Most of the time a user should not need to solve a CAPTCHA with reCAPTCHA v2. This makes it much more user friendly than the old implementation which required the user to identify sometimes hard-to-read text fragments. In addition to that, the new solution is much better suited for responsive storefronts.

In addition to protect websites against automated bots and spam, reCAPTCHA is also used to build machine learning data sets. For more information, visit the official website.

The reCAPTCHA service is integrated into Intershop Commerce Suite by using the Managed Service Framework. Please note that this document only contains information about the reCAPTCHA specific service implementation. Generic details on the CAPTCHA framework and about how to include CAPTCHA fields into web forms and ISML templates can be found in Concept - Captcha Framework (valid to 7.10).

References

• Official reCAPTCHA homepage: https://www.google.com/recaptcha/intro/index.html
• Official reCAPTCHA developer guide: https://developers.google.com/recaptcha/intro
• (Deprecated) reCAPTCHA v1 service implementation: Concept - ReCaptcha (valid to 7.7)
• Intershop Commerce Suite CAPTCHA framework: Concept - Captcha Framework (valid to 7.10)

Configuration

reCAPTCHA is implemented as a managed service. For activating the service for a given channel, please refer to Concept - Captcha Framework (valid to 7.10) (section Activation and Configuration).

The following managed service configuration parameters are available.

A (free) Google account is required to get the key pair for a given domain. Keys can be requested here: https://www.google.com/recaptcha/admin#createsite

For testing purposes, the following keys can be used, which will allow all verifications requests to pass successfully:

Displaying the Widget (PWA)

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>

Verifying the Response

When the CAPTCHA has been solved and the form is submitted, a new parameter (g-recaptcha-response) will be added to the following request. This parameter includes a token containing information about the solved CAPTCHA challenge. The parameter together with the configured site-specific secret key and the remote IP address of the user will be transferred to the configured verification URL. Here the token will be validated and a JSON response is returned:

{
  "success": true|false,
  "challenge_ts": timestamp,  // timestamp of the challenge load (ISO format yyyy-MM-dd'T'HH:mm:ssZZ)
  "hostname": string,         // the hostname of the site where the reCAPTCHA was solved
  "error-codes": [...]        // optional
}

This response is internally transformed into a CaptchaResponse which is then handled by the CAPTCHA framework. A list of possible error codes can be found in the official documentation: https://developers.google.com/recaptcha/docs/verify

Implementation Artifacts

All artifacts for the service implementation can be found in cartridge ac_captcha_recaptcha (component set p_platform).

Java Classes

Templates

The service implementation includes the following ISML templates: