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 policySITE_KEY
: your reCAPTCHACHALLENGEPAGE
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 ruleSECURITY_POLICY
: the name of the security policyEXPRESSION
: the custom rules language expression that matches the traffic on which you want to enforce reCAPTCHA assessmentSRC_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 ruleSECURITY_POLICY
: the name of the security policyEXPRESSION
: the custom rules language expression that matches the traffic up which you want to enforce reCAPTCHA assessmentSRC_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 ruleSECURITY_POLICY
: the name of the security policyEXPRESSION
: the custom rules language expression that matches the traffic on which you want to enforce reCAPTCHA assessmentSRC_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 requestVALUE_#
: 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
- View the rate limiting overview.
- Learn about bot management.