Introduction

reCAPTCHA v3 is an implementation of Google's CAPTCHA service. It provides website protection against automated bots and spam by adding an additional widget to web forms that verifies that the user accessing the page is a real human. Unlike the first and second versions, users are no longer required to manually solve CAPTCHA challenges each time they submit a form. Instead, the verification takes place in the background without any user interaction. If the Google service recognizes the user as a human, the protected form is submitted.

A typical reCAPTCHA v3 challenge workflow is very simple:

1. A user loads a reCAPTCHA-protected web form. The reCAPTCHA widget is displayed in the lower-right corner of the page.
   
2. When the form is submitted, if the user is considered trustworthy by Google's backend, the service will recognize this and the web form will be submitted successfully. If not, an error message is displayed and the user has to try again (although the recognition is usually pretty good and humans should always be registered as such).

New to reCAPTCHA v3 is that the service will now return a score between 0.0 and 1.0 based on the user's interaction with the site, with 1.0 being very likely a good interaction and 0.0 being very likely a bot. The site administrator can then decide which scores are considered trustworthy. Additionally, a new action concept has been introduced: An action can be assigned to each individual CAPTCHA in the web shop which can then be used to get detailed breakdowns and statistics in the reCAPTCHA administration console.

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. For details on the CAPTCHA framework and about how to include CAPTCHA fields into web forms and ISML templates, refer to 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
• Official reCAPTCHA administration console: https://www.google.com/recaptcha/admin/
• 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/create

For testing purposes, the following keys can be used, which will allow all verification requests to pass successfully. Alternatively, the score threshold can be set to "0.0" which will achieve the same result.

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 script is executed, a token will be generated and inserted into a form field. Upon submitting the form, this token together with the configured site-specific secret key and the remote IP address of the user is transferred to the configured verification URL. The token will be validated and a JSON response is returned here:

{
  "success": true|false,      // whether this request was a valid reCAPTCHA token for your site
  "score": number,            // the score for this request (0.0 - 1.0)
  "action": string,           // the action name for this request (important to verify)
  "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
}

If the received score is greater than or equal to the configured score threshold and the action matches the action identifier of the submitted form, the request is considered valid. The 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 the cartridge ac_captcha_recaptcha (component set p_platform).

Java Classes

Templates

The service implementation includes the following ISML template: