Configure bot management

This page contains information about configuring Google Cloud Armor security policy rules for bot management. Before you configure bot management, make sure that you're familiar with the information in the bot management overview.

Before you begin

The following sections explain all of the Identity and Access Management (IAM) roles and permissions required to configure Google Cloud Armor security policies. For the use cases in this document, you only need the compute.securityPolicies.create and compute.securityPolicies.update permissions.

Set up IAM permissions for Google Cloud Armor security policies

The following operations require the Identity and Access Management (IAM) Compute Security Admin role (roles/compute.securityAdmin):

  • Configuring, modifying, updating, and deleting a Google Cloud Armor security policy
  • Using the following API methods:
    • SecurityPolicies insert
    • SecurityPolicies delete
    • SecurityPolicies patch
    • SecurityPolicies addRule
    • SecurityPolicies patchRule
    • SecurityPolicies removeRule

A user with the Compute Network Admin role (roles/compute.networkAdmin) can perform the following operations:

  • Setting a Google Cloud Armor security policy for a backend service
  • Using the following API methods:
    • BackendServices setSecurityPolicy
    • BackendServices list (gcloud only)

Users with the Security Admin role (roles/iam.securityAdmin) and the Compute Network Admin role can view Google Cloud Armor security policies by using the SecurityPolicies API methods get, list, and getRule.

Set up IAM permissions for custom roles

The following table lists the IAM roles' base permissions and their associated API methods.

IAM permission API methods
compute.securityPolicies.create SecurityPolicies insert
compute.securityPolicies.delete SecurityPolicies delete
compute.securityPolicies.get SecurityPolicies get
SecurityPolicies getRule
compute.securityPolicies.list SecurityPolicies list
compute.securityPolicies.use BackendServices setSecurityPolicy
compute.securityPolicies.update SecurityPolicies patch
SecurityPolicies addRule
SecurityPolicies patchRule
SecurityPolicies removeRule
compute.backendServices.setSecurityPolicy BackendServices setSecurityPolicy

Use a reCAPTCHA manual challenge to distinguish between human or automated clients

To use reCAPTCHA with Google Cloud Armor, you must associate your reCAPTCHA WAF site key (reCAPTCHA key) of type CHALLENGEPAGE with a security policy. For more information about reCAPTCHA keys, see the reCAPTCHA keys overview.

To associate or disassociate your own reCAPTCHA key with a security policy, use the following command:

gcloud compute security-policies update SECURITY_POLICY \
    --recaptcha-redirect-site-key SITE_KEY

Replace the following:

  • SECURITY_POLICY: the name of the security policy
  • SITE_KEY: your reCAPTCHA CHALLENGEPAGE key

Associate a reCAPTCHA key

The following example associates a reCAPTCHA key with a security policy. The associated reCAPTCHA key applies to all the rules that use the manual challenge feature under the given security policy.

gcloud compute security-policies update SECURITY_POLICY \
    --recaptcha-redirect-site-key "SITE_KEY"

Disassociate a reCAPTCHA key

To disassociate a reCAPTCHA key with a security policy, use this command:

gcloud compute security-policies update SECURITY_POLICY \
    --recaptcha-redirect-site-key ""

Redirect traffic for reCAPTCHA assessment

When you have associated your reCAPTCHA key with your security policy, you can create a rule within that policy to internally redirect traffic for reCAPTCHA assessment. Use the following format in the gcloud CLI to redirect traffic:

gcloud compute security-policies rules create PRIORITY \
  --security-policy SECURITY_POLICY \
  {--expression EXPRESSION | --src-ip-ranges SRC_IP_RANGE} \
  --action redirect \
  --redirect-type google-recaptcha

Replace the following:

  • PRIORITY: the priority at which you want to create the rule
  • SECURITY_POLICY: the name of the security policy
  • EXPRESSION: the custom rules language expression that matches the traffic on which you want to enforce reCAPTCHA assessment
  • SRC_IP_RANGE: an IP address range. Use this to enforce reCAPTCHA assessment on all requests from this range.

The following example creates a rule that redirects traffic attempting to reach /login.html for a reCAPTCHA manual challenge:

gcloud compute security-policies rules create 1000 \
    --security-policy SECURITY_POLICY \
    --expression "request.path.matches(\"/login.html\")" \
    --action redirect \
    --redirect-type google-recaptcha

Enforce reCAPTCHA frictionless assessment

Before you proceed, see the bot management overview for prerequisites on using reCAPTCHA action-tokens or session-tokens.

To extract attributes from a reCAPTCHA action-token, you can use token.recaptcha_action.ATTRIBUTE. Replace ATTRIBUTE with a valid token attribute in the Google Cloud Armor rules language. Similarly, use token.recaptcha_session.ATTRIBUTE to extract attributes from a reCAPTCHA session-token. For more information about the syntax of available reCAPTCHA token attributes, see the rules language reference.

An action-token can originate from a web application, an iOS application, or an Android application, while a session-token can only originate from a web application. Each platform requires a separate reCAPTCHA key. The expressions token.recaptcha_action.ATTRIBUTE and token.recaptcha_session.ATTRIBUTE apply to tokens from any of these platforms. To distinguish tokens from different platforms and to prevent token theft, we recommend that you associate reCAPTCHA keys when you configure rules that use these expressions.

Examples

The first example creates a rule that allows traffic targeting /login.html with a reCAPTCHA action-token whose score is no less than 0.8.

gcloud compute security-policies rules create 1000 \
    --security-policy SECURITY_POLICY \
    --expression "request.path.matches(\"/login.html\") && token.recaptcha_action.score >= 0.8" \
    --action allow

The second example is the same as the first example, but it also requires that the action-token be issued with a reCAPTCHA key of example-site-key-1 or example-site-key-2:

gcloud compute security-policies rules create 1000 \
    --security-policy SECURITY_POLICY \
    --expression "request.path.matches(\"/login.html\") && token.recaptcha_action.score >= 0.8" \
    --recaptcha-action-site-keys "example-site-key-1,example-site-key-2" \
    --action allow

The third example creates a rule that allows traffic targeting /login.html, with a reCAPTCHA session-token issued with a reCAPTCHA key of example-site-key-3, and with a score no less than 0.8.

gcloud compute security-policies rules create 1000 \
    --security-policy SECURITY_POLICY \
    --expression "request.path.matches(\"/login.html\") && token.recaptcha_session.score >= 0.8" \
    --recaptcha-session-site-keys "example-site-key-3" \
    --action allow

Redirect (302 response)

To create a rule to redirect traffic to a user-configured URL, use the following format in the Google Cloud CLI:

gcloud compute security-policies rules create PRIORITY \
    --security-policy SECURITY_POLICY \
    {--expression EXPRESSION | --src-ip-ranges SRC_IP_RANGE} \
    --action redirect \
    --redirect-type external-302 \
    --redirect-target REDIRECT_URL

Replace the following:

  • PRIORITY: the priority at which you want to create the rule
  • SECURITY_POLICY: the name of the security policy
  • EXPRESSION: the custom rules language expression that matches the traffic up which you want to enforce reCAPTCHA assessment
  • SRC_IP_RANGE: an IP address range. Use this to enforce reCAPTCHA assessment on all requests from this range.
  • REDIRECT_URL: the URL to which you want to redirect traffic

The following example creates a rule that redirects traffic coming from 10.10.10.0/24 to https://www.example.com.

gcloud compute security-policies rules create 1000 \
   --security-policy SECURITY_POLICY \
   --src-ip-ranges "10.10.10.0/24" \
   --action redirect \
   --redirect-type external-302 \
   --redirect-target "https://www.example.com"

Decorate request

To create a rule that allows traffic but adds custom headers and user-defined static values before sending them to protected backends, use the following format in the gcloud CLI:

gcloud compute security-policies rules create PRIORITY \
    --security-policy SECURITY_POLICY \
    {--expression EXPRESSION | --src-ip-ranges SRC_IP_RANGE} \
    --action allow \
    --request-headers-to-add HEADER_1=VALUE_1,HEADER_2=VALUE_2,...

Replace the following:

  • PRIORITY: the priority at which you want to create the rule
  • SECURITY_POLICY: the name of the security policy
  • EXPRESSION: the custom rules language expression that matches the traffic on which you want to enforce reCAPTCHA assessment
  • SRC_IP_RANGE: an IP address range. Use this to enforce reCAPTCHA assessment on all requests from this range.
  • HEADER_#: the name of the request header with which you want to decorate the request
  • VALUE_#: the value of the request header with which you want to decorate the request

The following example creates a rule that allows traffic targeting /login.html, as long as the request also has a reCAPTCHA action-token score lower than 0.2.

gcloud compute security-policies rules create 1000 \
    --security-policy SECURITY_POLICY \
    --expression "request.path.matches("/login.html") && token.recaptcha_action.score < 0.2" \
    --action allow \
    --request-headers-to-add "reCAPTCHA-Warning=high"

What's next