Strengthen your website security using Google’s reCAPTCHA Enterprise and Cloud Armor

Using Google's reCAPTCHA Enterprise, you can prevent spam and abuse on your website. Action tokens are one of the features of reCAPTCHA Enterprise, which allows you to control how reCAPTCHA is used.

The purpose of this article is to explain how Action Tokens can be used with Cloud Armor. Additionally, we will show you how to configure reCAPTCHA Enterprise with Terraform.
Comparison between reCAPTCHA Enterprise Action Tokens and other features

reCAPTCHA action-tokens

• Use Case: Specifically designed to safeguard distinct user actions, such as login attempts or comment submissions.

• Supported Platforms: Works seamlessly on both websites and mobile applications.

• Integration Complexity: Classified as a medium. For successful deployment:

The reCAPTCHA JavaScript needs to be incorporated into the respective pages of your website or by using the reCAPTCHA Enterprise mobile SDK for mobile applications.

1. The action token must be attached to each individual request header.

2. Configurations must be made either on Google Cloud Armor security policy rules or through reCAPTCHA firewall policies when working with third-party WAF service providers.

• Detection Accuracy: Positioned at the pinnacle with the highest accuracy due to its focus on individual user actions.

reCAPTCHA session-tokens

Use Case: Unlike action tokens, which protect specific user actions, session tokens cover an entire user session on a domain.

• Supported Platforms: Session-tokens are limited to websites, while action-tokens also support mobile applications.

• Integration Complexity: Both are medium, but session-tokens don’t require attaching an action token to request headers.

• Detection Accuracy: While action-tokens offer the highest level of accuracy by focusing on individual actions, session-tokens have high accuracy, as they monitor the entire user session.

• Supported Version: Both utilize reCAPTCHA Enterprise score-based site keys, but action-tokens also support checkbox site keys.

reCAPTCHA challenge page:

Use Case: Contrary to the action tokens that work in the background, the challenge page interrupts user activities and forces them to complete a CAPTCHA challenge when suspicious activity is detected.

• Supported Platforms: Both are designed for websites.

• Integration Complexity: Challenge page integration is low and more straightforward than action-tokens. It does away with JavaScript installations on individual pages.

• Detection Accuracy: The challenge page has medium accuracy, a step down from the action tokens, primarily because it may miss some page-specific signals.

• Supported Version: The challenge page uses an optimized version of reCAPTCHA, different from the Enterprise score-based or checkbox site keys supported by action tokens.

reCAPTCHA WAF express protection:

Use Case: It’s a go-to when your environment isn’t friendly with reCAPTCHA JavaScript or mobile SDKs, unlike action tokens that require these integrations.

• Supported Platforms: WAF express protection is the most versatile, catering to APIs, IoT devices, websites, and mobile apps. Action-tokens cover just websites and mobile apps.

• Integration Complexity: Both have low complexity, but the integration methods differ. Action-tokens require JavaScript or SDK installations, while WAF express can be set up with third-party WAFs or server requests.

• Detection Accuracy: WAF express has the lowest detection accuracy since it lacks client-side signals. In contrast, action tokens boast the highest accuracy.

• Supported Version: Both utilize reCAPTCHA Enterprise score-based site keys.

Steps to implement the solution

First let's create a reCAPTCHA v3 key on Google Cloud console. Security -> reCAPTCHA Enterprise -> Create Key

After defining the reCAPTCHA key basic parameters we should define some key behavior of the key.

To ensure the utmost security, enabling domain verification is highly recommended. However, it’s essential to note that if you’re integrating the key with Cloud Armor, direct support isn’t available at this moment (Issue Tracker for details). To address this, you’ll need to specify this behavior manually in your rules, which I will guide you through in the subsequent sections.

After setting up the key, we dive into the coding phase.

The mechanism we’ll implement is straightforward. When an action token reaches the load balancer, the designated Cloud Armor service will evaluate it. We primarily work with two parameters:

token.recaptcha_action.valid token.recaptcha_action.score

More about reCAPTCHA token attributes for Google Cloud Armor. If a request lacks the token, the valid parameter will automatically register as false. Under these circumstances, you have the discretion to determine the request's subsequent journey. In our implementation, we will append a MISSING value to our reCAPTCHA-Warning header. On the other hand, if the token is present, our focus shifts to the score parameter. This metric provides insights into the user, essentially estimating the likelihood of the requester being a bot or a genuine user. A score exceeding 0.8 will instruct the rule to dispatch the LOW value to the backend within the reCAPTCHA-Warning header. Should it fall below this threshold, a HIGH value gets transmitted instead.

Equipped with this data, our backend service can judiciously decipher the value and determine the subsequent course of action.

Setting up the security policy

This snippet initializes a Cloud Armor Edge security policy. Here, we’re defining a new Google Cloud Platform (GCP) security policy resource named “default-security-policy” for Cloud Armor at the edge. More about [google_compute_security_policy] (https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_security_policy)resource.

Configuring reCAPTCHA options

Within our security policy, we’re incorporating reCAPTCHA options. The redirect_site_key parameter is assigned the reCAPTCHA site key. Terraform resource documentation.

The rule for handling missing tokens

This rule targets requests that don’t contain a valid reCAPTCHA action token. If the token is absent or not valid, a new header named reCAPTCHA-Warning with the value MISSING is appended to the request.

The rule for handling low reCAPTCHA scores

This rule targets requests with reCAPTCHA scores greater than 0.8, which indicates probable genuine user interactions. As a result, the reCAPTCHA-Warning header is set to LOW, representing a low bot likelihood

Domain verification

If the domain doesn’t align with expectations, the rule could either reject or reroute the request. It’s advisable to trigger this undesired pattern rule prior to the reCAPTCHA check, thereby filtering out any undesirable requests before they undergo reCAPTCHA assessment. Once Google resolves the integration issue between reCAPTCHA and Cloud Armor related to the Domain Verification feature, it’s advisable to remove this anti-pattern from the rules.

The expression !request.headers['host'].matches('www.example.com') is used to detect requests that don't originate from the domain www.example.com.

rule {
  action   = "allow"
  priority = "1001"
  match {
    expr {
      expression = "!request.headers['host']

Add verification on a user interaction

Once we are done with the infrastructure part, we are ready to integrate our apps. Here is a integration from an example frontend application provided by Google.

To load reCAPTCHA Enterprise on your webpage, add the JavaScript API with your score-based key within the <head></head> element of your web page.

<head>
    <script src="https://www.google.com/recaptcha/enterprise.js?render=KEY_ID"></script>
    ....
</head>

1. To ensure that grecaptcha.enterprise.execute() runs when the reCAPTCHA library loads, use grecaptcha.enterprise.ready().

2. Call grecaptcha.enterprise.execute() on each interaction, you want to protect with your score-based key. Specify a meaningful name for a user interaction in the action parameter. For more guidance, see Actions.

<script>
function onClick(e) {
  e.preventDefault();
  grecaptcha.enterprise.ready(async () => {
    const token = await grecaptcha.enterprise.execute('KEY_ID', {action: 'LOGIN'});
    // IMPORTANT: The 'token' that results from execute is an encrypted response sent by
    // reCAPTCHA Enterprise to the end user's browser.
    // This token must be validated by creating an assessment.
    // See https://cloud.google.com/recaptcha-enterprise/docs/create-assessment
  });
}
</script>

grecaptcha.enterprise.execute() generates a token as shown in the following example:

03AGdBq27tvcDrfiRuxQnyKs-SarXVzPODXLlpiwNsLqdm9BSQQRtxhkD-Wv6l2vBSnL_JQd80FZp3IeeF_TxNMrqhyQchk7hmg_ypDctt_F5RTr9zNO9TSDX3Fy0qHQTuaM9E3hrAkA1v1l7D-fCreg7uq8zoudfh1ZRmN49-2iAMAn4E8_ff-nmlLTNGVZmCSyeze-5xM24pM_JhhUVcCMIDKYtDUnr2imxg2ubIqMscCZGUtdXNUO_LRSzuwWDlLyAr3V2nVn29Z48PQa2QzbymEXzO9pCtoGQmY7kiZ8ILfD9DAJSSyUTMwJXVJptUeBmLM341fq_STYZBbPQJ0zYOEDvJoFsIwGMfuphkDet0nK56b0mkzaL8RCRy2oK31Mcx6n3PhGkCnQ6QIhiV5ZVmV1Hz9M3w99zYw6ekc3wPCNMZ6V6x1ApVpIk3reFfByRQ0C0_pRWwbKZHLXQ_oSTI1UI7kyH1VeXngsJAx2l7zcp0hQNipajC4YwL7Jb8X4cCD0NeiaY1YCrI5j87mK5axcMikq460I4niIFeDBlHGF-ndqu3CJstosAur-C_x827f-dPPjA9Vrw8MDb3x4KUb0vbA8xE9mJxPYGY0rPCR27vJ38Voa7DjEBGX9c-iufv5_wfj-yIfIAHy0iijnRLI0CVkWF2-iPdWv7LnkTwL3WKbF_MrEGZXmtyLX9dEZArfxmToeMuSdYkfikkgR2-k4Xzxlz15RbHJuWSAYqEyTTnpUXmOvDuTN92b0kYqbRelcLUI_Shm-8dq9e-L7K6YWQv32gV6NukZKY15dyrJaW10frBgTOGSTTpIyB7MNEL8S27WjWtOb-zWsgimIhoRNfS8BiJWkmK4gTj51m7Wur-qsDbHgV6gXlMvjJs_B7oXX-mKsKhY9ACtwukotBelGYQOvf1RDHjH3Yi1RDfELBY6AkwUK4tq8cACVGpCwa0gKUo-sbORTsGu_r7VTzYo1AaZD5HV4XUm8yoqszel6DmIfkJcI7PfzzvfUJuvMQ1itZSzpzuth3glbKBYsIjbKqG-q8cxtZ7u0l32j46ASo2zlCJWUjwP3W1P7MUenEoIZtjlyTB_tT6Fk8RxGgRv3oLP7NPFJGs9ZGOAl6tBHpZF8Y_FqEOCMKtBl2JYOE5h6_Es3buSdiMm7mtLr64pboGiEColF1vbVvYpyaaqGFPXBM6ekZSXEXLAI0_7rj_fCLgnB21KXfac95vZbM9vyJCASvDcWKwqajQwy5aGMNe9GtbMogYbZfz5UGWAIi24Vd8KSv3qKOOwvzbcw4H0HYdsBXA After the token is generated, send the reCAPTCHA token to the backend and create an assessment within two minutes.

Conclusion

As bot activities become increasingly sophisticated, website and application owners must stay a step ahead. While our journey through this integration has showcased its strengths and potential areas for improvement, the key takeaway remains: with the right tools and informed strategies, we can build more secure, efficient, and user-friendly digital platforms.

As Google continues to refine and enhance its services, we can expect even more streamlined integrations and functionalities. Until then, let’s make the best of what we have, always prioritizing user experience while ensuring top-notch security.

Sources

• https://cloud.google.com/recaptcha-enterprise

• https://cloud.google.com/recaptcha-enterprise/docs/token-attr-ca

• https://cloud.google.com/recaptcha-enterprise/docs/instrument-web-pages#user-action

• https://cloud.google.com/recaptcha-enterprise/docs/waf-features#features-overview

• https://issuetracker.google.com/issues/281859602

• https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/recaptcha_enterprise_key

• https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_security_policy

Author: Csaba Ujvári