Django reCAPTCHA form field/widget integration app.

Django reCAPTCHA uses a modified version of the Python reCAPTCHA client which is included in the package as client.py.

Tested with:

• Python: 2.7, 3.5
• Django: 1.8, 1.9, 1.10, 1.11

1. Sign up for reCAPTCHA.

2. Install with pip install django-recaptcha.

3. Add 'captcha' to your INSTALLED_APPS setting.

4. Add the keys reCAPTCHA have given you to your Django production settings (leave development settings blank to use the default test keys) as RECAPTCHA_PUBLIC_KEY and RECAPTCHA_PRIVATE_KEY. For example:

   RECAPTCHA_PUBLIC_KEY = 'MyRecaptchaKey123'
   RECAPTCHA_PRIVATE_KEY = 'MyRecaptchaPrivateKey456'

   These can also be specificied per field by passing the public_key or private_key parameters to ReCaptchaField - see field usage below.

5. If you would like to use the new Invisible reCaptcha add the setting INVISIBLE_RECAPTCHA = True. For example:

   INVISIBLE_RECAPTCHA = True

6. If you would like to use the No Captcha reCaptcha add the setting NOCAPTCHA = True. For example:

   NOCAPTCHA = True

7. If you require a proxy, add a RECAPTCHA_PROXY setting, for example:

   RECAPTCHA_PROXY = 'https://127.0.0.1:8000'

The quickest way to add reCAPTCHA to a form is to use the included ReCaptchaField field class. A ReCaptcha widget will be rendered with the field validating itself without any further action required. For example:

from django import forms
from captcha.fields import ReCaptchaField

class FormWithCaptcha(forms.Form):
    captcha = ReCaptchaField()

To allow for runtime specification of keys you can optionally pass the private_key or public_key parameters to the constructor. For example:

captcha = ReCaptchaField(
    public_key='76wtgdfsjhsydt7r5FFGFhgsdfytd656sad75fgh',
    private_key='98dfg6df7g56df6gdfgdfg65JHJH656565GFGFGs',
)

If specified these parameters will be used instead of your reCAPTCHA project settings.

The reCAPTCHA widget supports several Javascript options variables that customize the behaviour of the widget, such as theme and lang. You can forward these options to the widget by passing an attr parameter to the field, containing a dictionary of options. For example:

captcha = ReCaptchaField(attrs={
  'theme' : 'clean',
})

The client takes the key/value pairs and writes out the RecaptchaOptions value in JavaScript.

Google provides test keys which are set as the default for RECAPTCHA_PUBLIC_KEY and RECAPTCHA_PRIVATE_KEY. These cannot be used in production since they always validate to true and a warning will be shown on the reCAPTCHA.

Django reCAPTCHA introduces an environment variable RECAPTCHA_TESTING which helps facilitate tests. The environment variable should be set to "True", and cleared, using the setUp() and tearDown() methods in your test classes.

Setting RECAPTCHA_TESTING to True causes Django reCAPTCHA to accept "PASSED" as the recaptcha_response_field value. Note that if you are using the new No Captcha reCaptcha (ie. with NOCAPTCHA = True in your settings) the response field is called g-recaptcha-response.

Example:

import os
os.environ['RECAPTCHA_TESTING'] = 'True'

form_params = {'recaptcha_response_field': 'PASSED'} # use 'g-recaptcha-response' param name if using NOCAPTCHA
form = RegistrationForm(form_params) # assuming only one ReCaptchaField
form.is_valid() # True

os.environ['RECAPTCHA_TESTING'] = 'False'
form.is_valid() # False

Passing any other values will cause Django reCAPTCHA to continue normal processing and return a form error.

Check tests.py for a full example.

To make reCAPTCHA work in ajax-loaded forms:

1. Import recaptcha_ajax.js on your page (not in the loaded template):

   <script type="text/javascript" src="https://www.google.com/recaptcha/api/js/recaptcha_ajax.js"></script>

2. Add to your Django settings:

   CAPTCHA_AJAX = True

This library used to not use SSL by default, but now it does. You can disable this if required, but you should think long and hard about it before you do so!

You can disable it by setting RECAPTCHA_USE_SSL = False in your Django settings, or by passing use_ssl=False to the constructor of ReCaptchaField.

Currently (2017-04-12), Invisible reCAPTCHA is really invisble (no action required for the user) only with Google Chrome. With other web-browsers, use will have to answer a picture challenge.

To avoid users having to click on an element (link, checkbox...) to execute the captcha, it's executed when the form is submited. If you have already registered listeners on the submit event, it should be okay, unless with really specific javascript: you might encounter some compatibility problems. If this is the case, you just have to overwrite the`widget_invisible.html` template and modify the javascript to be compatible with you existing code.

For old browsers which don't support "addEventListener" (see https://caniuse.com/#search=addEventListener), captcha is executed when the form is displayed. If you want a better degradation, be free to overwrite the template and add some thirdparty dependencies to have a woking javascript for all browsers (jQuery for eg.).

Inspired Marco Fucci's blogpost titled Integrating reCAPTCHA with Django

client.py taken from recaptcha-client licenced MIT/X11 by Mike Crawford.

reCAPTCHA copyright 2012 Google.