reCAPTCHA firewall policies overview

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 float The type of assessment that was done. assessment_type is set according to the reCAPTCHA WAF site key that is passed in with the request.

To compare the value of recaptcha.assessment_type in your CEL expression, use one of the following constants:

  • AssessmentType.ACTION
  • AssessmentType.SESSION
  • AssessmentType.CHALLENGEPAGE
For example, to compare an action-token assessment, use 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.

What's next