Captcha
*******

.. highlight:: python

- For documentation, see
  https://github.com/praekelt/django-recaptcha

.. warning:: ``django-recaptcha`` does not support *Enterprise reCAPTCHA* (yet)
             For more information, see `recaptcha enterprise issue 234`_

Sign Up
=======

Sign up to reCAPTCHA on
https://console.cloud.google.com/security/recaptcha

- You will want to *Create key* (*Classic keys* should be replaced).
- If you want to use the Captcha on your laptop from
  http://localhost:8000/, then add ``localhost`` to the list of domains.

.. image:: ./misc/google/2025-07-26-recaptcha-create-key.png

- You will receive a site key.
- You will need to request a secret key using the options under
  *Integrating with a third party*.

.. image:: ./misc/google/2025-07-28-recaptcha-third-party.png

.. tip:: *Integrating with a third party* will only be until
         ``django-recaptcha`` supports *Enterprise reCAPTCHA*.
         (for more information, see `recaptcha enterprise issue 234`_)

Salt
====

In the salt ``sls`` file for your site, add the ``norecaptcha_site_key`` and
the ``norecaptcha_secret_key`` e.g:

.. code-block:: yaml

  norecaptcha_site_key: <your site key>
  norecaptcha_secret_key: <your secret key>

.. note:: Replace ``<your site key>`` and ``<your secret key>`` with the
          actual reCAPTCHA keys.

Django
======

Add the following to ``requirements/base.txt``::

  django-recaptcha

.. tip: See :doc:`requirements` for the current version.

Add the following to ``settings/base.py``::

  THIRD_PARTY_APPS = (
      "django_recaptcha",
      # ...
  )

Add the following to ``settings/production.py``::

  # https://github.com/praekelt/django-recaptcha
  RECAPTCHA_PRIVATE_KEY = get_env_variable('NORECAPTCHA_SECRET_KEY')
  RECAPTCHA_PUBLIC_KEY = get_env_variable('NORECAPTCHA_SITE_KEY')
  # https://github.com/torchbox/django-recaptcha#recaptcha-v3-score
  RECAPTCHA_REQUIRED_SCORE = 0.85

.. tip:: We are using reCAPTCHA version 3, but if you are testing reCAPTCHA
         version 2, do **not** set
         ``RECAPTCHA_PRIVATE_KEY`` or ``RECAPTCHA_PUBLIC_KEY``.
         Google provides test keys which are set as the default.

To add a captcha field to your form::

  from django_recaptcha.fields import ReCaptchaField
  from django_recaptcha.widgets import ReCaptchaV3

  class EnquiryForm(RequiredFieldForm):
      captcha = ReCaptchaField(widget=ReCaptchaV3)

Testing
=======

We are using reCAPTCHA version 3, but if you are using reCAPTCHA version 2
then add the following to your local settings file
e.g. ``settings/dev_patrick.py``::

  SILENCED_SYSTEM_CHECKS = ["django_recaptcha.recaptcha_test_key_error"]

From `Django reCAPTCHA, Unit Testing`_::

  data = {
      "name": "Patrick",
      "captcha": "123",
      "g-recaptcha-response": "PASSED",
  }
  response = client.post(reverse("example.enquiry.create"), data)

.. tip:: Make sure to add ``captcha`` to the ``data``.

.. note:: No need to use ``os.environ["RECAPTCHA_TESTING"] = "True"`` in tests
          any more!

.. note:: ``g-recaptcha-response`` has replaced ``recaptcha_response_field``.

.. note:: We are using reCAPTCHA version 3, but if you are testing reCAPTCHA
          version 2, do **not** set
          ``RECAPTCHA_PRIVATE_KEY`` or ``RECAPTCHA_PUBLIC_KEY``.
          Google provides test keys which are set as the default.


.. _`Django reCAPTCHA, Unit Testing`: https://pypi.org/project/django-recaptcha/#unit-testing
.. _`recaptcha enterprise issue 234`: https://github.com/django-recaptcha/django-recaptcha/issues/234