A comprehensive API security strategy requires protection from fraud and abuse. To better protect our publicly-facing APIs from malicious software that engages in abusive activities, we can deploy CAPTCHAs to disrupt abuse patterns. Developers can prevent attacks, reduce their API security surface area, and minimize disruption to users by implementing Google Cloud’s reCAPTCHA Enterprise and Apigee X solutions. 

As Google Cloud’s API management platform, Apigee X can help protect APIs using a reverse-proxy approach to HTTP requests and responses. One important feature of Apigee X is the ability to include a reCAPTCHA Enterprise challenge in the authentication (AuthN) stage of the request. 

This post shows how to provision a reCAPTCHA proxy flow to protect your APIs. Complete code samples are available in this Github repo.

When and why to use Apigee X for implementing CAPTCHAs

The initial way to use reCAPTCHA Enterprise as part of a Web Application and API Protection (WAAP) solution is through Cloud Armor. For developers who want a purely API-based solution, Apigee X allows developers to define the reCAPTCHA process as a set of Apigee X proxy flows. As a dedicated solution, it moves as much API security code as possible into Apigee. 

This method can also make code maintenance easier and can allow API business rules to be managed in code. The reCAPTCHA process can be included directly in Apigee proxies, either individually or as shared flows. This code can then be added to the same source control as all the Apigee proxy code, in line with the API business rules.

Let’s first review a few implementations of reCAPTCHA Enterprise, and then contrast those with an Apigee X implementation example to see which might be best for you.

An introduction to reCAPTCHA Enterprise

A reCAPTCHA challenge page can redirect incoming HTTP requests to reCAPTCHA Enterprise, which can help stop possible malicious attacks. When reCAPTCHA Enterprise is integrated with Cloud Armor, and the Challenge Page option is selected, a reCAPTCHA will trigger when the policy rule of Cloud Armor matches the incoming URL/traffic pattern.

To avoid CAPTCHA fatigue (mouse-click fatigue due to too many CAPTCHA challenges), developers should consider using reCAPTCHA session-tokens, which we explain in more detail below. A challenge page is most useful for dealing with a bot making repeated programmatic HTTP requests. The challenge page redirect and possible reCAPTCHA challenge can stop malicious bots. However, the challenge page can also interrupt a legitimate user’s activity — a reCAPTCHA challenge page is less desirable for a well-intended human user.

To protect important user interactions, reCAPTCHA Enterprise uses an object called an action-token. These can help protect human users and their legitimate interactions, such as shopping cart checkouts or sensitive knowledge base requests that you want to safeguard.

As an alternative to action-tokens, session-tokens protect the whole user session on the site’s domain. This can help developers reuse an existing reCAPTCHA Enterprise assessment, which is analogous to a session key, but for authentication not encryption. It is recommended to use a reCAPTCHA session-token on all the web pages of your site. This enables reCAPTCHA Enterprise to secure your entire site and recognize deviations in human browsing patterns, such as a bot crawling your site.

Using Apigee X and reCAPTCHA Enterprise

All of the above can also be accomplished in Apigee X, without the need for Cloud Armor. Code for an Apigee X flow that initiates a reCAPTCHA Enterprise challenge is below, and is also available in our Github repo file SC-AccessReCaptchaEnterprise.xml.

<ServiceCallout name="SC-AccessReCaptchaEnterprise">
    <Request>
        <Set>
            <Payload contentType="application/json">{
  "event": {
    "token": "{flow.recaptcha.token}",
    "siteKey": "{flow.recaptcha.sitekey}"
  }
}</Payload>
            <Verb>POST</Verb>
        </Set>
    </Request>
    <Response>recaptchaAssessmentResponse</Response>
    <HTTPTargetConnection>
        <Authentication>
            <GoogleAccessToken>
                <Scopes>
                    <Scope>https://www.googleapis.com/auth/cloud-platform</Scope>
                </Scopes>
            </GoogleAccessToken>
        </Authentication>
        <URL>https://recaptchaenterprise.googleapis.com/v1/projects/{flow.recaptcha.gcp-projectid}/assessments</URL>
    </HTTPTargetConnection>
</ServiceCallout>

The most important line is the initiation of the reCAPTCHA handshake (shown in the above diagrams), with a POST request. The POST request includes both the reCAPTCHA token (either action-token or session-token, discussed above) and the reCAPTCHA sitekey (how reCAPTCHA Enterprise protects your API endpoint).

<Request>
        <Set>
            <Payload contentType="application/json">{
  "event": {
    "token": "{flow.recaptcha.token}",
    "siteKey": "{flow.recaptcha.sitekey}"
  }
}</Payload>
            <Verb>POST</Verb>
        </Set>
    </Request>

Here is an explanation of all the proxy definitions included in the Github repo. A reCAPTCHA token is silently and periodically retrieved by a client app and transmitted to an Apigee runtime when an API is invoked.

The shared flow configuration in this example is able to get a reCAPTCHA token validation status and a risk score from the Google reCAPTCHA Enterprise assessment endpoint. The sf-recaptcha-enterprise-v1 Apigee X shared flow gets a reCAPTCHA token validation status and a risk score from the Google reCAPTCHA Enterprise assessment endpoint. The risk score is a decimal value between 0.0 and 1.0.The score 1.0 indicates that the interaction poses low risk and is very likely legitimate, whereas 0.0 indicates that the interaction poses high risk and might be fraudulent. Between both extremes, the shared flow’s processing decides if an API invocation must be rejected or not. For the purpose of this reference, we consider a minimum score of 0.6: This value is configurable and can be set to a higher or lower value depending on the risk profile of the client application.

The pipeline script deploys a shared flow on Apigee X, containing the full configuration of the reCAPTCHA Enterprise reference as well as the following artifacts:

  • recaptcha-data-proxy-v1: a data proxy, which calls the reCAPTCHA Enterprise shared flow. The target endpoint of this proxy is httpbin.org
  • recaptcha-deliver-token-v1: an API proxy used to deliver an HTML page that includes a valid reCAPTCHA token. This proxy is not intended to be used in production but only during test phases.
  • The reCAPTCHA Enterprise API product
  • A developer (Jane Doe)
  • app-recaptcha-enterprise: a single developer app when Option 1 has been selected
  • 2 developer apps with real app credentials and reCAPTCHA Enterprise sitekeys when Option 2 has been selected:
    • app-recaptcha-enterprise-always0
    • App-recaptcha-enterprise-always1

Google Cloud’s Web App and API Protection (WAAP) solution

This implementation is a part of Google Cloud’s WAAP solution. Google’s WAAP security solution stack is a comprehensive solution which is an integration of web application firewall (WAF), DDoS prevention, bot mitigation, content delivery network, Zero Trust, and API protection. The Google Cloud WAAP solution consists of Cloud Armor (for DDoS and web app defense), reCAPTACHA Enterprise (for bot defense) and Apigee (for API defense). This solution is a set of tools and controls designed to protect web applications, APIs, and associated assets.

Google’s WAAP Security solution is driven by the following principles:

Safe by default 

  • Build on tested and proven components and code

Detect risky functionality

  • New code should be reviewed 
  • Bypassing safe patterns should also be justified 
  • High-risk activities should be scrutinized 

Automate 

  • If you do it more than once, automate