This document provides an overview of the reCAPTCHA firewall policies.
A reCAPTCHA firewall policy is a set of rules that match on condition attributes to protect your site from spam and abuse. Each rule is evaluated for the incoming traffic. The rules are evaluated in the same order as they are added in the policy.
reCAPTCHA firewall policy components
A reCAPTCHA firewall policy rule consists of the following components:
path
: a URL path to which the firewall policy rule applies. For example,/login
.condition
: a policy condition. A policy condition is a CEL (Common Expression Language) expression that must resolve to a boolean value. For example,recaptcha.score >= 0.5
.action
: An action that your WAF service provider must execute when the policy condition is met. For more information, see policy actions.
When an incoming request matches a policy condition for the specified path, your WAF service provider allows, blocks, or redirects the request, based on the specified action. The default rule is to allow access.
A sample reCAPTCHA firewall policy
The following sample reCAPTCHA firewall policy contains a rule that is applied
to the login
action. It blocks the access if the score is less than 0.5.
policy {
path: login.php
condition: recaptcha.score < 0.5
action: block
}
reCAPTCHA firewall policy condition attributes
The following table lists reCAPTCHA token attributes that you can use to define conditions in your reCAPTCHA firewall policies.
Attribute name | Data type | Description |
---|---|---|
recaptcha.token.valid |
boolean | Whether the received token is valid. A token is valid if it is not malformed or expired, even if the score is low. |
recaptcha.token.action |
string | The action name provided at token generation.
Populated only for action-tokens. This is the action
parameter that is passed to
grecaptcha.enterprise.execute() when the token is created.
For more
information, see Action names.
|
recaptcha.score |
float | The score from a reCAPTCHA token. A valid score ranges from 0.0 to 1.0. The score 1.0 indicates that the interaction poses low risk and is likely legitimate, whereas 0.0 indicates that the interaction poses high risk and might be fraudulent. For more information, see Interpreting scores. |
recaptcha.assessment_type |
integer | The type of assessment that was done. assessment_type
is set according to the reCAPTCHA key for WAF that is passed with
the request.
To compare the value of
AssessmentType.ACTION .
|
http.ip |
string | The IP address of the incoming request. |
http.path |
string | The path of the request URI. |
http.domain |
string | The domain of the requested URI. |
reCAPTCHA firewall policy actions
The following table lists the various policy actions that you can specify in your reCAPTCHA firewall policy rules:
Policy action | Description | Result of the action |
---|---|---|
allow |
Allows access to the requested page. | The incoming user request is uninterrupted to your backend. |
block |
Denies access to the requested page. | A 403 (forbidden) HTTP error is returned to the user. |
redirect |
Redirects the incoming user request to the reCAPTCHA challenge page. | The reCAPTCHA challenge page evaluates the user request and attaches a cookie based on the assessment. Later, the user request is redirected again to the original page. |
substitute |
Serves a different page other than the requested page to a fraudulent user request. | The requested path is substituted with a different path, when sending the request to your backend. The user continues to see the original URL. |
set_header |
Sets a custom header and allows the incoming user request to continue to the backend. The backend then can trigger a custom protection. | A header is attached to the user request. Your backend uses this header to trigger a custom protection or analysis. |