DocumentationAEM 6.5User Guide

Using CAPTCHA in adaptive forms using-captcha-in-adaptive-forms

Last update: Tue Dec 12 2023 00:00:00 GMT+0000 (Coordinated Universal Time)
Version
Article link
AEM as a Cloud Service
Click here
AEM 6.5
This article

Adobe recommends using the modern and extensible data capture Core Componentsfor creating new Adaptive Formsor adding Adaptive Forms to AEM Sites pages. These components represent a significant advancement in Adaptive Forms creation, ensuring impressive user experiences. This article describes older approach to author Adaptive Forms using foundation components.

CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) is a program commonly used in online transactions to distinguish between humans and automated programs or bots. It poses a challenge and evaluates user response to determine if it’s a human or a bot interacting with the site. It prevents the user to proceed if the test fails and helps make online transactions secure by keeping bots from posting spam or malicious purposes.

AEM Forms support CAPTCHA in adaptive forms. You can use reCAPTCHA service by Google to implement CAPTCHA.

NOTE
  • AEM Forms support reCAPTCHA v2 and enterprise. Any other version is not supported.
  • CAPTCHA in adaptive forms is not supported in offline mode on AEM Forms app.

Configure reCAPTCHA service by Google for Adaptive Forms google-reCAPTCHA

AEM Forms users can use the reCAPTCHA service by Google to implement CAPTCHA in adaptive forms. It offers advanced CAPTCHA capabilities to protect your site. For more information on how reCAPTCHA works, see Google reCAPTCHA. reCAPTCHA service including reCAPTCHA v2 and reCAPTCHA Enterprise is integrated into AEM Forms. Based on your requirement you can configure reCAPTCHA service to enable:

reCAPTCHA

Configure reCAPTCHA Enterprise steps-to-implement-reCAPTCHA-enterprise-in-forms

  1. Create a reCAPTCHA Enterprise project enabled with reCAPTCHA Enterprise API.

  2. Obtain the Project ID.

  3. Create an API key and a site key for websites.

  4. Create configuration container for cloud services.

    1. Go to Tools > General > Configuration Browser. See the Configuration Browser documentation for more information.

    2. Do the following to enable the global folder for cloud configurations or skip this step to create and configure another folder for cloud service configurations.

      1. In the Configuration Browser, select the global folder and select Properties.
      2. In the Configuration Properties dialog, enable Cloud Configurations.
      3. Select Save & Close to save the configuration and exit the dialog.

    3. In the Configuration Browser, select Create.

    4. In the Create Configuration dialog, specify a title for the folder and enable Cloud Configurations.

    5. Select Create to create the folder enabled for cloud service configurations.

  5. Configure the cloud service for reCAPTCHA Enterprise.

    1. On your Experience Manager author instance, go to tools-1 > Cloud Services.

    2. Select reCAPTCHA. The Configurations page opens. Select the configuration container created in the previous step and select Create.

    3. Select version as reCAPTCHA Enterprise and specify Name; Project ID, Site Key, and API key(Obtained in Step 2 and 3) for reCAPTCHA Enterprise service.

    4. Select key type, the key type should be same as the site key configured in the google cloud project, for example, Checkbox site key or Score-based site key.

    5. Specify a threshold score in the range 0–1 (Click to know more about score). Scores greater than or equal to the threshold scores identify human interaction, otherwise considered bot interaction.

      Note:

      • Form authors can specify a score in the range suitable for uninterrupted form submission.

    6. Select Create to create the cloud service configuration.

    7. In the Edit Component dialog, specify the name, project ID, site key, API key (obtained in steps 2 and 3), select the key type, and enter the threshold score. Select Save Settings  and then select  OK  to complete the configuration.

Once the reCAPTCHA Enterprise service is enabled, it is available for use in adaptive forms. See using CAPTCHA in adaptive forms.

reCAPTCHA Enterprise

Configure Google reCAPTCHA v2 steps-to-implement-reCAPTCHA-v2-in-forms

  1. Obtain reCAPTCHA API key pair from Google. It includes a site key and a secret key.

  2. Create configuration container for cloud services.

    1. Go to Tools > General > Configuration Browser. See the Configuration Browser documentation for more information.

    2. Do the following to enable the global folder for cloud configurations or skip this step to create and configure another folder for cloud service configurations.

      1. In the Configuration Browser, select the global folder and select Properties.

      2. In the Configuration Properties dialog, enable Cloud Configurations.

      3. Select Save & Close to save the configuration and exit the dialog.

    3. In the Configuration Browser, select Create.

    4. In the Create Configuration dialog, specify a title for the folder and enable Cloud Configurations.

    5. Select Create to create the folder enabled for cloud service configurations.

  3. Configure the cloud service for reCAPTCHA v2.

    1. On your AEM author instance, go to tools-1 > Cloud Services.
    2. Select reCAPTCHA. The Configurations page opens. Select the configuration container created in the previous step and select Create.
    3. Select version as reCAPTCHA v2, specify Name; Site key, and Secret Key for reCAPTCHA service(Obtained in Step 1) and select Create to create the cloud service configuration.
    4. In the Edit Component dialog, specify the site and secret keys obtained in step 1. Select Save Settings and then select OK to complete the configuration.

    Once the reCAPTCHA service is configured, it is available for use in adaptive forms. For more information, see using CAPTCHA in adaptive forms.

reCAPTCHA v2

Use reCAPTCHA in adaptive forms using-reCAPTCHA

To use reCAPTCHA in adaptive forms:

  1. Open an adaptive form in edit mode.

    note note
    NOTE
    Ensure that the configuration container selected when creating the adaptive form contains the reCAPTCHA cloud service. You can also edit adaptive form properties to change the configuration container associated with the form.

  2. From the component browser, drag-drop the Captcha component onto the adaptive form.

    note note
    NOTE
    Using more than one Captcha component in an adaptive form is not supported. Also, it is not recommended to use CAPTCHA in a panel marked for lazy loading or in a fragment.
    note note
    NOTE
    Captcha is time-sensitive and expires in about a minute. Therefore, it is recommended to place the Captcha component just before the Submit button in the adaptive form.

  3. Select the Captcha component that you added and select cmppr to edit its properties.

  4. Specify a title for the CAPTCHA widget. The default value is Captcha. Select Hide title if you do not want title to appear.

  5. From the Captcha service drop-down, select reCAPTCHA to enable reCAPTCHA service if you configured it as described in reCAPTCHA service by Google.

  6. Select a configuration from the Settings drop-down.

  7. If the selected configuration has version reCAPTCHA Enterprise:

    1. You can select reCAPTCHA cloud configuration with key type as checkbox. In checkbox key type the customized error message appears as an inline message if the captcha validation fails. You can select size as Normal and Compact.

    2. You can select reCAPTCHA cloud configuration with key type as score based. In score based key type the customized error message shows as a pop-up message if the captcha validation fails.

    3. When you select a Bind Reference the data submitted is a bound data, otherwise it is unbound data. Below are XML examples of unbound data and bound data (with bind reference as SSN) respectively, when a form is submitted.

      code language-xml 
      
    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <afData>
    <afUnboundData>
        <data>
            <captcha16820607953761>
                <captchaType>reCAPTCHAEnterprise</captchaType>
                <captchaScore>0.9</captchaScore>
            </captcha16820607953761>
        </data>
    </afUnboundData>
    <afBoundData>
        <Root
            xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <PersonalDetails>
                <SSN>371237912</SSN>
                <FirstName>Sarah </FirstName>
                <LastName>Smith</LastName>
            </PersonalDetails>
            <OtherInfo>
                <City>California</City>
                <Address>54 Residency</Address>
                <State>USA</State>
                <Zip>123112</Zip>
            </OtherInfo>
        </Root>
    </afBoundData>
    <afSubmissionInfo>
        <stateOverrides/>
        <signers/>
        <afPath>/content/dam/formsanddocuments/captcha-form</afPath>
        <afSubmissionTime>20230608034928</afSubmissionTime>
    </afSubmissionInfo>
    </afData>
      code language-xml 
      
    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <afData>
    <afUnboundData>
        <data/>
    </afUnboundData>
    <afBoundData>
        <Root
            xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
            <PersonalDetails>
                <SSN>
                    <captchaType>reCAPTCHAEnterprise</captchaType>
                    <captchaScore>0.9</captchaScore>
                </SSN>
                <FirstName>Sarah</FirstName>
                <LastName>Smith</LastName>
            </PersonalDetails>
            <OtherInfo>
                <City>California</City>
                <Address>54 Residency</Address>
                <State>USA</State>
                <Zip>123112</Zip>
            </OtherInfo>
        </Root>
    </afBoundData>
    <afSubmissionInfo>
        <stateOverrides/>
        <signers/>
        <afPath>/content/dam/formsanddocuments/captcha-form</afPath>
        <afSubmissionTime>20230608035111</afSubmissionTime>
    </afSubmissionInfo>
    </afData>

    If the selected configuration has version reCAPTCHA v2:

    1. Select the size as Normal or Compact for the reCAPTCHA widget. You can also select the Invisible option to show the CAPTCHA challenge only if there is suspicious activity. The protected by reCAPTCHA badge, displayed below, is displayed on the protected forms.

      Google protected by reCAPTCHA badge

    The reCAPTCHA service is enabled on the adaptive form. You can preview the form and see the CAPTCHA working.

  8. Save the properties.

NOTE
Do not select Default from the Captcha service drop-down as the default AEM CAPTCHA service is deprecated.

Show or hide CAPTCHA component based on rules show-hide-captcha

You can select to show or hide the CAPTCHA component based on rules that you apply on a component in an Adaptive Form. Select the component, select edit rules , and select Create to create a rule. For more information on creating rules, see Rule Editor.

For example, the CAPTCHA component must display in an Adaptive Form only if the Currency Value field in the form has a value of more than 25000.

Select the Currency Value field in the form and create the following rules:

Show or hide rules

NOTE
  • If you select reCAPTCHA v2 configuration with size as Invisible or reCAPTCHA Enterprise score based keys, then show/hide option is not applicable.

Validate CAPTCHA validate-captcha

You can validate CAPTCHA in an Adaptive Form either when you submit the form or base the CAPTCHA validation on user actions and conditions.

Validate CAPTCHA on form submission validation-form-submission

To validate a CAPTCHA automatically when you submit an Adaptive Form:

  1. Select the CAPTCHA component and select cmppr to view the component properties.
  2. In the Validate CAPTCHA section, select Validate CAPTCHA at form submission.
  3. Select Done to save the component properties.

Validate CAPTCHA on user actions and conditions validate-captcha-user-action

To validate a CAPTCHA based on conditions and user actions:

  1. Select the CAPTCHA component and select cmppr to view the component properties.

  2. In the Validate CAPTCHA section, select Validate CAPTCHA on a user action.

  3. Select Done to save the component properties.

    note note
    NOTE
    If you select reCAPTCHA v2 configuration with size as Invisible or reCAPTCHA Enterprise score based keys, then Valid Captcha on a user action is not applicable.

Experience Manager Forms provides ValidateCAPTCHA API to validate CAPTCHA using pre-defined conditions. You can invoke the API using a custom Submit Action or by defining rules on components in an Adaptive Form.

The following is an example of a ValidateCAPTCHA API to validate CAPTCHA using pre-defined conditions:

if (slingRequest.getParameter("numericbox1614079614831").length() >= 5) {
        GuideCaptchaValidatorProvider apiProvider = sling.getService(GuideCaptchaValidatorProvider.class);
        String formPath = slingRequest.getResource().getPath();
        String captchaData = slingRequest.getParameter(GuideConstants.GUIDE_CAPTCHA_DATA);
        if (!apiProvider.validateCAPTCHA(formPath, captchaData).isCaptchaValid()){
            response.setStatus(400);
            return;
        }
    }

The example signifies that the ValidateCAPTCHA API validates the CAPTCHA in the form only if number of digits in the numeric box specified by the user while filling the form is greater than 5.

Option 1: Use Experience Manager Forms ValidateCAPTCHA API to validate CAPTCHA using a custom Submit Action

Perform the following steps to use the ValidateCAPTCHA API to validate CAPTCHA using a custom Submit Action:

  1. Add the script that includes the ValidateCAPTCHA API to custom Submit Action. For more on custom Submit Actions, see Create a custom Submit Action for Adaptive Forms.
  2. Select the name of the custom Submit Action from the Submit Action drop-down list in Submission properties of an Adaptive Form.
  3. Select Submit. The CAPTCHA gets validated based on the conditions defined in ValidateCAPTCHA API of the custom Submit Action.

Option 2: Use Experience Manager Forms ValidateCAPTCHA API to validate CAPTCHA on a user action before submitting the form

You can also invoke ValidateCAPTCHA API by applying rules on a component in an Adaptive Form.

For example, you add a Validate CAPTCHA button in an Adaptive Form and create a rule to invoke a service on the click of a button.

The following figure illustrates how you can invoke a service on the click of a Validate CAPTCHA button:

Validate CAPTCHA

You can invoke the custom servlet that includes ValidateCAPTCHA API using the rule editor and enable or disable the submit button of the Adaptive Form based on the validation result.

Similarly, you can use rule editor to include a custom method to validate CAPTCHA in an Adaptive Form.

recommendation-more-help
19ffd973-7af2-44d0-84b5-d547b0dffee2