Skip to content

Latest commit

 

History

History
75 lines (59 loc) · 6.29 KB

recaptcha.md

File metadata and controls

75 lines (59 loc) · 6.29 KB

Set up Google reCAPTCHA in a Django app

Google's reCAPTCHA protects public-facing forms from the bots (like a sign up form). This guide will walk you through how to set up a production-ready reCAPTCHA in a Django/Docker/Heroku application. See the reCAPTCHA documentation for more details about reCAPTCHA itself.

There are two ways you can implement a reCAPTCHA in a Django app:

  1. Use the django-recaptcha plugin. This is the recommended approach for use cases.
  2. Implement the reCAPTCHA in your view and template.

This guide assumes that you have an existing form, or have created a new form prior to starting. You'll first implement a test reCAPTCHA. Once this is setup, it will be easy to reconfigure your application to use a real reCAPTCHA.

How it works

  • A user fills out a form with the reCAPTCHA, then submits the form. Google provides some JavaScript to help with this.
  • The view validates the form and the reCAPTCHA, separately.
    • The form fields are validated like any regular Django form.
    • To validate the reCAPTCHA, the view POSTs the user's reCAPTCHA response to Google's reCAPTCHA API.
    • Depending on Google's response, the reCAPTCHA is valid or invalid.

Set up the test reCAPTCHA

Google provides a test reCAPTCHA that you can use for automated testing and local development. You'll need to setup the test reCAPTCHA within your application. The test reCAPTCHA should never be used in a production environment, because the validation always evaluates to true (aka not a bot).

Configure the keys

  1. Get the public key and secret key for Google's test reCAPTCHA. You can get the keys from their site.

  2. Add the public and private keys to your local environment.

    • Create an .env.example file in your root directory. This will give you a file that can be commited to version control and shared with other developers, so they know what environment variables to set for their own local development. Here is an example from one of our projects, with the keys for Google's test reCAPTCHA.
    • Once you have your .env.example file, copy it to a local .env file so that your application can use the environment variables.

  3. Configure docker-compose.yml to use the environment file.

    • Reference the .env file in the project's root docker-compose.yml file. This will enable the app to run locally and use your local environment variables. Here is an example.
    • If your automated tests interact with the reCAPTCHA, then add the environment variables to ~/tests/docker-compose.yml.

Now you can use the public key and private key in your code. Whenever you deploy your app, you must change these keys to use a production reCAPTCHA (see Add a production reCAPTCHA).

Implement your code

Test the implementation with a live reCATPCHA

So far, you've been using Google's test reCAPTCHA, which always evaluates to true. If you want to test with a real, live reCAPTCHA, you can use one of the existing local development reCAPTCHAs.

  1. Visit the admin dashboard: https://www.google.com/recaptcha/admin
  2. Get the keys you need.
    • Use local_development_v2 if you're using V2 of reCAPTCHA.
    • Use local_development_v3 if you're using V3.
  3. Change the public and private keys you set in the Configure the keys section.

Add a production reCAPTCHA

Get with your project lead to create a new, official reCAPTCHA for your app. This one should be used for staging and production environments.

  1. Visit the admin dashboard: https://www.google.com/recaptcha/admin
  2. Create a new reCAPTCHA. Be sure to whitelist the proper domains.
  3. Get the public and private keys for the new reCAPTCHA.
  4. Set Heroku environment variables with those keys.
  5. Deploy to Heroku with environment variables.
  6. Test that it works.
  7. Bye Bye Bots.

Resources