Implementing Google reCaptcha
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:
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.
Frontend configuration in React
Use the following steps to implement reCaptcha in React:
- 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.
- Render the component in the following manner.
The component takes following props to customize rendering:
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.
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.
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:
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.
Github code
A sample node.js project is uploaded at: https://github.com/harshadajog/google-recaptcha-node
