https://github.com/zmh-program/django-turnstile

🛡 Add Cloudflare Turnstile widget to the forms of your django project. 🛡 添加 Cloudflare Turnstile 无感验证码小组件到你的 django 项目的表单中
https://github.com/zmh-program/django-turnstile

cloudflare-turnstile django form validator

Last synced: 3 months ago
JSON representation

🛡 Add Cloudflare Turnstile widget to the forms of your django project. 🛡 添加 Cloudflare Turnstile 无感验证码小组件到你的 django 项目的表单中

• Host: GitHub
• URL: https://github.com/zmh-program/django-turnstile
• Owner: zmh-program
• License: mit
• Created: 2022-12-24T14:25:41.000Z (almost 3 years ago)
• Default Branch: main
• Last Pushed: 2024-10-17T12:25:04.000Z (12 months ago)
• Last Synced: 2025-04-05T14:22:18.048Z (6 months ago)
• Topics: cloudflare-turnstile, django, form, validator
• Language: Python
• Homepage: https://deeptrain.net/login
• Size: 7.81 KB
• Stars: 54
• Watchers: 2
• Forks: 7
• Open Issues: 2
• Metadata Files:
  • Readme: README.rst
  • License: LICENSE

Awesome Lists containing this project

README

          
================

Django Turnstile

================

Add Cloudflare Turnstile validator widget to the forms of your django project.

This project refers to github project django-hcaptcha (author: AndrejZbin)

Configuration

-------------

Add "turnstile" to your INSTALLED_APPS setting like this::

    INSTALLED_APPS = [

        ...

        'turnstile',

    ]

For development purposes no further configuration is required. By default, django-Turnstile will use dummy keys.

For production, you'll need to obtain your Turnstile site key and secret key and add them to you settings::

    TURNSTILE_SITEKEY = ''

    TURNSTILE_SECRET = ''

You can also configure your Turnstile widget globally (`see all options `_)::

    TURNSTILE_DEFAULT_CONFIG = {

        'onload': 'name_of_js_function',

        'render': 'explicit',

        'theme': 'dark',  # do not use data- prefix

        'size': 'compact',  # do not use data- prefix

        ...

    }

If you need to, you can also override default turnstile endpoints::

    TURNSTILE_JS_API_URL = 'https://challenges.cloudflare.com/turnstile/v0/api.js'

    TURNSTILE_VERIFY_URL = 'https://challenges.cloudflare.com/turnstile/v0/siteverify'

Use proxies::

     TURNSTILE_PROXIES = {

        'http': 'http://127.0.0.1:8000',

     }

Change default verification timeout::

    TURNSTILE_TIMEOUT = 5

Usage

-----------

Simply add TurnstileField to your forms::

    from turnstile.fields import TurnstileField

    class Forms(forms.Form):

        ....

        turnstile = TurnstileField()

        ....

In your template, if you need to, you can then use `{{ form.turnstile }}` to access the field. 

You can override default config by passing additional arguments::

    class Forms(forms.Form):

        ....

        turnstile = TurnstileField(theme='dark', size='compact')

        ....

How it Works

------------------

When a form is submitted by a user, Turnstile's JavaScript will send one POST parameter to your backend: `cf-turnstile-response`. It will be received by your app and will be used to complete the `turnstile` form field in your backend code.

When your app receives these two values, the following will happen:

 

 - Your backend will send these values to the Cloudflare Turnstile servers

 - Their servers will indicate whether the values in the fields are correct

 - If so, your `turnstile` form field will validate correctly

 

Unit Tests

--------------

You will need to disable the Turnstile field in your unit tests, since your tests obviously cannot complete the Turnstile successfully. One way to do so might be something like:

.. code-block:: python

    from unittest.mock import MagicMock, patch

    from django.test import TestCase

    @patch("turnstile.fields.TurnstileField.validate", return_value=True)

    class ContactTest(TestCase):

        test_msg = {

            "name": "pandora",

            "message": "xyz",

            "turnstile": "xxx",  # Any truthy value is fine

        }

        def test_something(self, mock: MagicMock) -> None:

            response = self.client.post("/contact/", self.test_msg)

            self.assertEqual(response.status_code, HTTP_302_FOUND)