Google reCaptcha Image
Google reCaptcha Image

Implementing Google reCaptcha

harshada jog
4 min readOct 11, 2021

--

Integrating with third party APIs is an essential part of a developer’s job. I recently added Google reCAPTCHA v2 to the user registration feature. I am writing this article to refresh and share my learning.

· Documentation
· Design
· Implementation
One time Setup:
Frontend configuration in React
Backend configuration
Internationalization support
· Securing SECRET keys
· Github code
· References

Documentation

A well built API will always come with a thorough developer documentation for reference. The documentation provides an extensive set of instructions w.r.t pricing, usage, restrictions (if any).

https://developers.google.com/recaptcha/intro

Design

Before touching the code, it is always a good idea to chalk out the flow. A sequence diagram depicting various use cases and the interactions between the objects is very useful for this purpose.

Sequence diagram for general flow:

http://www.tictawf.com/blog

Implementation

One time Setup:

To use reCAPTCHA, sign up for an API key pair. The key pair consists of a public key and a secret key. The public key (or site key) is used by the frontend to display the widget. The secret key is used by the backend to communicate with the Google reCAPTCHA server. The secret needs to be kept safe for security purposes.

Frontend configuration

The widget can be automatically rendered, or explicitly rendered.

Automatic render:

Load the ‘https://www.google.com/recaptcha/api.js’ script to use the widget.

Explicit render:

We implement a callback function and use the grecaptcha.render to display the widget. We assign this function to onload parameter and set explicit render.

code snippet2

Frontend configuration in React

Use the following steps to implement reCaptcha in React:

  1. Install react-google-recaptcha library using npm install/yarn add. This will add the library in package.json and provide the ReCAPTCHA component for use.
  2. Render the component in the following manner.

The component takes following props to customize rendering:

props
https://github.com/dozoisch/react-google-recaptcha

onChange callback

Once the end user completes the challenge (clicks “I am not a robot” or verify images), a token is returned in the ‘g-recaptcha-response’. Once a valid token is received, the Frontend will call the Backend api with all details including the token.

onChange callback is expected to handle the cases where the token is null or invalid. For example, if the token expires, this value will be null. In this case, the user will be asked to re-submit the registration form.

code snippet

Backend configuration

The backend talks to the Google server and verifies the token before processing any data received from Frontend. This is done by making a POST request to https://www.google.com/recaptcha/api/siteverify and passing the SECRET_KEY and token value.

Backend API call

The response is a JSON object, with a boolean success property. If true, backend server processes data received from Frontend. If false, the data is not processed. An appropriate response should be sent to Frontend in each case.

(Note: A reCaptcha token is valid only for two minutes, and can only be verified once to prevent replay attacks.)

Internationalization support

For internationalization, use the parameter ‘hl’ provided by ReCAPTCHA component to set a specific language. The following example renders the widget in Vietnamese:

hl parameter example
widget in vietnamese

Securing SECRET keys

The secret keys should be secured and not be published to Git repository. We use the .env file to store the SECRET and add the .env to gitignore file.

secret key in .env file
secret key storage
adding .env to gitignore
adding .env to gitignore

Github code

A sample node.js project is uploaded at: https://github.com/harshadajog/google-recaptcha-node

References

https://github.com/dozoisch/react-google-recaptcha

--

--

harshada jog

Software engineer passionate about helping businesses build their online presence. I am always reinventing myself through constant learning and creativity.