Document Properties
Kbid
29X281
Last Modified
04-Dec-2023
Added to KB
04-Nov-2019
Public Access
Everyone
Status
Online
Doc Type
Concepts
Product
ICM 7.10
Concept - ReCaptcha v3 (valid to 7.10)

Introduction


The reCAPTCHA v3 feature is available by default with ICM 7.10.15 or later.

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

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.

ParameterDefault ValueDescription
Site Key-Site key that is used to render the widget.
Secret Key-Secret key used to authorize communication between the application and the reCAPTCHA server.
Score Threshold0.5Score from which the request is considered a valid interaction (1.0 is very likely a good interaction, 0.0 is very likely a bot).
Verification URLhttps://www.google.com/recaptcha/api/siteverifyURL that is called to verify a users response to a reCAPTCHA challenge.
Proxy URL-URL of the proxy the application server should use when connecting to reCAPTCHA service.
Proxy Username-Username for proxy authentication.
Proxy Password-Password for proxy authentication.

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.

ParameterDemo Value
Site Key6LeIxAcTAAAAAJcZVRqyHh71UMIEGNQ_MXjiZKhI
Secret Key6LeIxAcTAAAAAGG-vFI1TnRWxMZNFuojJ4WifJWe

A warning will be displayed on the CAPTCHA widget when using these keys. Do not use them in a production environment.

Displaying the Widget

To include reCAPTCHA v3 into a web form, see Cookbook - Captcha Framework (valid to 7.10). Alternatively, a REST request is available which allows to retrieve a code snippet that can be used to protect a form with a CAPTCHA, see Cookbook - WebShop REST API.

For version 3, a new captchaaction parameter has been added to the ISML module which renders the widget:

<ISCaptchaFormField fieldname="ForgotPasswordFormStep1:recaptcharesponsefield"
                    enablepreference="intershop.CaptchaPreferences.ForgotPassword"
                    captchaaction="forgot_password">

This parameter defines the action identifier that is associated with the form and which is displayed in the statistics in the reCAPTCHA administration console. If no action is passed, then the name of the form field's form is used as fallback.

When rendering the template, the following code snippet is inserted into web forms which contain a CAPTCHA form field:

<input type="hidden" name="{FORM_FIELD}" value="placeholder" />
<input type="hidden" name="action" value="{CAPTCHA_ACTION}" />

<script src="https://www.google.com/recaptcha/api.js?onload=reCaptchaV3OnloadCallback&render={SITE_KEY}" async defer></script>
<script>
    var setRecaptchaV3TokenToForm = function setRecaptchaV3TokenToForm() {
        grecaptcha.execute('{SITE_KEY}', {action: '{CAPTCHA_ACTION}'}).then(function(token) {
                var inputToken = document.querySelector('input[name="{FORM_FIELD}"]');
                if (inputToken && token) {
                    inputToken.value = token;
                }
            });
        };
    var reCaptchaV3OnloadCallback = function reCaptchaV3OnloadCallback() {
        grecaptcha.ready(function() {
            setRecaptchaV3TokenToForm();
        });
        setInterval(function() {
            setRecaptchaV3TokenToForm();
        }, 1900 * 60);
    };
</script>

The configured site key and parameters from the ISML module are then included automatically as well. The script assures that the generated reCAPTCHA token is inserted into the associated form field, so it can be submitted to Google for verification when the form is submitted.

Note

A given token is only valid for two minutes, which is the reason why the script includes a function that re-triggers the verification every 1.9 minutes.

If the CAPTCHA widget is not to be included automatically, the following template needs to be overridden to provide custom functionality:

  • ac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha\recaptcha\v3\ReCaptcha.isml

If the CAPTCHA recognizes the user as a bot, an error is displayed:

The error is part of the ReCaptcha.isml template in the implementation cartridge (see above). To customize the error message, override the localization property recaptcha.v3.incorrect.error.

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:

Template NamePathDescription
ReCaptcha.ismlac_captcha_recaptcha\staticfiles\cartridge\templates\default\captcha\recaptcha\v3Contains the JavaScript to display the widget and the form fields for the reCAPTCHA token and action.
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.
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.
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.