Google Cloud Armor bot management overview

Google Cloud Armor and reCAPTCHA Enterprise provide tools to help you evaluate and act on incoming requests that might be from automated clients.

reCAPTCHA Enterprise uses advanced risk analysis techniques to distinguish between human users and automated clients. reCAPTCHA Enterprise assesses the user based on the configuration of the reCAPTCHA WAF site keys. It then issues an encrypted token with attributes that represent the associated risk. Google Cloud Armor deciphers this token in-line, without an additional request/response to the reCAPTCHA Enterprise service. Based on the token attributes, Google Cloud Armor lets you allow, deny, rate-limit or redirect the incoming requests. For more information, see the Google Cloud Armor and reCAPTCHA Enterprise integration overview.

Google Cloud Armor's bot management includes the following integrated capabilities.

  • Manual challenge (reCAPTCHA challenge page)
    • You can permit only end-users who pass the reCAPTCHA Enterprise manual challenge by redirecting end-users for reCAPTCHA Enterprise assessment.
    • We recommend that you create your own reCAPTCHA WAF site key and associate it with your security policy. For more information, see Implement a reCAPTCHA challenge.
    • You must configure a security policy rule to redirect a request for reCAPTCHA Enterprise assessment.
  • Enforce reCAPTCHA Enterprise frictionless assessment
    • You can take different actions on incoming requests based on reCAPTCHA Enterprise's assessment of the risk that the request originates from a bot. You can write security policy rules to evaluate and filter traffic based on the token score and other token attributes.
    • Google Cloud Armor security policy evaluation happens at the edge of Google's network, so your backends are not involved in deciphering the token.
    • You must choose between using reCAPTCHA Enterprise action-tokens or session-tokens, and then create your own reCAPTCHA WAF site key, before you implement reCAPTCHA Enterprise. For more information, see Implementing reCAPTCHA action-tokens and Implementing reCAPTCHA session-tokens.
    • You must configure a security policy rule that evaluates reCAPTCHA Enterprise tokens.

Google Cloud Armor bot management also includes the following capabilities.

  • Redirect (302)
    • You can redirect requests to your configured alternative URL by configuring Google Cloud Armor to serve an HTTP 302 response to the client.
  • Decorate request
    • You can insert custom headers in requests, and static values into those headers, before proxying a requests to your backends.

Use cases

This section describes how you can use Google Cloud Armor bot management capabilities to mitigate bot risk and to control access from automated clients.

Use a manual challenge to distinguish between legitimate users and automated clients

You can redirect a request to reCAPTCHA Enterprise to assess the end-client and serve manual challenges if necessary, without any additional reCAPTCHA Enterprise implementation. When human users share the same signature (such as URL paths or other L7 signatures) as a bot or an abusive system, this action provides a way for them to prove that they are human. Only users who pass the assessment can gain access to your service.

The following diagram shows how a manual challenge distinguishes whether a request comes from a human or an automated client:

Example of redirecting to reCAPTCHA.
Example of redirecting to reCAPTCHA (click to enlarge)

Suppose a user Maya and a bot are both browsing the login page (/login.html) on your site. To allow access to Maya without granting access to the bot, you can configure a security policy rule with the advanced match expression request.path.matches("/login.html"), with a redirect action of type GOOGLE_RECAPTCHA. The end-to-end user experience is as follows:

  1. An end user visits your site for the first time.
  2. Google Cloud Armor evaluates the request, and determines to redirect it to reCAPTCHA Enterprise.
  3. reCAPTCHA Enterprise responds with an HTML page with the reCAPTCHA Enterprise JavaScript embedded.
  4. When the response is rendered, the embedded JavaScript runs to assess the user, and serves manual challenges if necessary.
    • If the user passes the assessment, reCAPTCHA Enterprise issues an exemption cookie, which is auto-attached by the browser to each of the subsequent requests to the same site until the cookie expires.
    • Otherwise, reCAPTCHA Enterprise does not issue an exemption cookie.

In this example, only Maya passes reCAPTCHA Enterprise assessment and receives an exemption cookie, gaining access to your site.

When you use manual challenges, we recommend that you create your own reCAPTCHA WAF site key and associate it with the security policy. This lets you view reCAPTCHA Enterprise metrics associated with the site key and train a security model specific to the site key. For more information, see Create reCAPTCHA WAF challenge site key.

If you do not create and associate a site key, reCAPTCHA Enterprise uses a Google-managed site key during assessment. You cannot view reCAPTCHA metrics associated with site keys that you don't own, including Google-managed site keys.

Enforce reCAPTCHA Enterprise assessment

When there is a reCAPTCHA Enterprise token attached to an incoming request, Google Cloud Armor evaluates the request and applies the configured action based on the individual attributes in the token.

reCAPTCHA Enterprise tokens

reCAPTCHA Enterprise issues two types of tokens: action-tokens and session-tokens. Both types of token return a score for each request based on the interactions with your site. Both types of token contain attributes, including a score that represents the risk associated with the user.

Before you configure security policy rules, you must decide whether to use action-tokens, session-tokens, or both. We recommend reading the reCAPTCHA Enterprise documentation to inform your decision. See the reCAPTCHA Enterprise use case comparison for more information.

After determining which type of token you want to use, you implement reCAPTCHA Enterprise for the token to be attached with a request. For information on implementing tokens in reCAPTCHA Enterprise, see Implementing reCAPTCHA Enterprise action-tokens and Implementing reCAPTCHA Enterprise session-tokens.

Finally, use the Google Cloud Armor rules language to configure security policy rules to evaluate reCAPTCHA Enterprise tokens that are attached with the request.

The following figure demonstrates the reCAPTCHA Enterprise token enforcement flow.

reCAPTCHA token enforcement flow.
reCAPTCHA token enforcement flow (click to enlarge)

Redirect (302 response)

You can use a URL-based redirect action to externally redirect requests to a different endpoint. You supply a redirect target in the form of a URL, and Google Cloud Armor redirects the request by serving an HTTP 302 response to the client.

Decorate request

Google Cloud Armor can insert custom request headers with static user-defined values before proxying the requests to your application. This option allows you to tag suspicious requests for alternative downstream processing, like serving a honey-pot, or for additional analysis and monitoring. Note that this action parameter must be added to an existing allow action.

In addition, if you choose a header name that already exists on the request, including standard HTTP headers, then the original value in that header will be overwritten by the user-defined value provided to the Google Cloud Armor rule.

Integrate with rate limiting

Google Cloud Armor rate limiting rules are compatible with bot management capabilities. For example, you can redirect a request for reCAPTCHA Enterprise assessment or redirect to a different URL when the number of requests exceeds the configured threshold. In addition, you can identify clients for rate limiting based on reCAPTCHA Enterprise exemption cookies or tokens, to throttle requests or ban clients that reuse or abuse the same cookie or token at a rate exceeding the user-configured threshold.

Rate limit reCAPTCHA Enterprise exemption cookies or tokens

For security, we recommend that you configure rate limiting rules to prevent token abuse through multiple uses per unique reCAPTCHA action-token, session-token, or exemption cookie. The following table illustrates how you can identify a reCAPTCHA Enterprise exemption cookie or token as the key in a rate limiting rule.

Resource enforce_on_key enforce_on_key_name
Exemption cookie HTTP-COOKIE recaptcha-ca-e
Action-token HTTP-HEADER X-Recaptcha-Token
Session-token HTTP-COOKIE recaptcha-ca-t

You can throttle requests or ban clients that depend on the same exemption cookie or token, and that exceed the configured threshold. For more information about rate limiting parameters, see Apply rate limiting.

Rate limiting examples

First, suppose that you only use manual challenges on selected URLs (/login.html, for example) on your site. To accomplish this, configure security policy rules as follows:

  • Rule 1: If there is a valid exemption cookie attached with the request and the number of uses for the exemption cookie is under your defined threshold, allow the request.
  • Rule 2: Redirect the request for reCAPTCHA Enterprise assessment.
reCAPTCHA Enterprise redirect example.
Enforce manual challenges (click to enlarge)

Second, suppose that you only use action-tokens and/or session-tokens on your site. For example, you might use action-tokens to protect high-profile user actions, like /login.html. To do this, take actions based on the score from the action-token as follows:

  • Rule 1: When the score from the action-token is higher than a predefined threshold (0.8, for example), allow the request if the number of uses for the action-token is under your defined threshold.
  • Rule 2: Deny the request.
reCAPTCHA Enterprise action example.
Enforce reCAPTCHA Enterprise action-token assessment (click to enlarge)

You can configure similar security policy rules to enforce reCAPTCHA Enterprise session-token assessment.

Third, suppose that you combine action-tokens or session-tokens with manual challenges on selected URLs (like /login.html) on your site, and you want to take actions based on the score from the action-token. And you want to give the user a second chance by solving challenges if the score is not satisfactory enough. To do this, configure security policy rules as follows:

  • Rule 1: When the score from the action-token is higher than a predefined threshold (0.8, for example), allow the request if the number of uses for the action-token is under your defined threshold.
  • Rules 2 and 3: When the score from the action-token is higher than a different predefined threshold (0.5, for example), redirect the request for reCAPTCHA Enterprise assessment unless there is a valid exemption cookie attached to the request and the number of uses for the exemption cookie is under your defined threshold.
  • Rule 4: Deny the request.
reCAPTCHA Enterprise action and redirect example.
Enforce reCAPTCHA Enterprise action-token assessment with manual challenges (click to enlarge)

You can configure similar security policy rules to enforce reCAPTCHA Enterprise session-token assessment with manual challenges.

If you do not configure the rate limiting rules as above, Google Cloud Armor imposes no limit on the number of uses for each reCAPTCHA exemption cookie, action-token, and session-token. For action-tokens, we recommend using a low threshold (1, for example) and a high time interval (30 minutes for example, since action-tokens are valid for 30 minutes). We recommend that you derive the threshold based on your traffic statistics.

Limitations

  • Google Cloud Armor bot management does not support the Global external HTTP(S) load balancer (Preview) mode of operation. To configure bot management with an HTTP(S) load balancer, use Global external HTTP(S) load balancer (classic). For more information, see Modes of operation.

What's next