django-altcha 0.4.0

Django field and widget for Altcha CAPTCHA.

Django Altcha

Django Altcha is a Django library that provides easy integration of Altcha CAPTCHA into your Django forms, enhancing user verification with configurable options.

By default, CAPTCHA validation operates in a fully self-hosted mode, eliminating the need for external services while ensuring privacy and control over the verification process.

Django Altcha is secure by default, featuring built-in protection against replay attacks to ensure each challenge is validated only once. This helps safeguard your forms from repeated or spoofed submissions without requiring additional configuration.

Installation

1. Install the package:

   pip install django-altcha
   

2. Add to INSTALLED_APPS:

   Update your Django project's settings.py:

   INSTALLED_APPS = [
       # Other installed apps
       "django_altcha",
   ]
   

3. Set your secret HMAC key:

   This key is used to HMAC-sign ALTCHA challenges and must be kept secret. Treat it like a password: use a secure, 64-character hex string.

   Update your Django project's settings.py:

   ALTCHA_HMAC_KEY="your_secret_hmac_key"
   

[!NOTE] You can generate a new secured HMAC key using: python -c "import secrets; print(secrets.token_hex(64))"

Usage

Adding the CAPTCHA Field to Your Form

To add the Altcha CAPTCHA field to a Django form, import AltchaField and add it to your form definition:

from django import forms
from django_altcha import AltchaField

class MyForm(forms.Form):
    captcha = AltchaField()

Configuration Options

You can pass configuration options to AltchaField that are supported by Altcha. These options are documented at Altcha's website integration guide.

Example with additional options:

from django import forms
from django_altcha import AltchaField

class MyForm(forms.Form):
    captcha = AltchaField(
        floating=True,   # Enables floating behavior
        debug=True,      # Enables debug mode (for development)
        # Additional options supported by Altcha
    )

Register a URL to Provide the Challenge

By default, challenge data is generated by the AltchaField and embedded directly into the rendered HTML using the challengejson option.

Alternatively, you can provide a URL that the Altcha widget’s JavaScript will fetch to retrieve the challenge, using the challengeurl option.

This approach is especially useful for enabling features like refetchonexpire, which only work when using a challengeurl (not challengejson).

A ready-to-use AltchaChallengeView is available in django_altcha. To enable it, register the view in your urlpatterns, for example:

from django.urls import path
from django_altcha import AltchaChallengeView

urlpatterns += [
    path("altcha/challenge/", AltchaChallengeView.as_view(), name="altcha_challenge"),
]

Once the URL is registered, you can configure your AltchaField to use it via the challengeurl option:

from django.urls import reverse_lazy
from django import forms
from django_altcha import AltchaField

class MyForm(forms.Form):
    captcha = AltchaField(
        challengeurl=reverse_lazy("altcha_challenge"),
    )

[!NOTE] You can customize the challenge generation by passing options directly when registering the view. For example: AltchaChallengeView.as_view(max_number=2000000)

Settings

ALTCHA_HMAC_KEY

Required. This key is used to HMAC-sign ALTCHA challenges and must be kept secret.

ALTCHA_JS_URL

URL location of the Altcha JavaScript file. Default to the django-altcha embedded file.

ALTCHA_VERIFICATION_ENABLED

Set to False to skip Altcha validation altogether.

ALTCHA_CHALLENGE_EXPIRE

Challenge expiration duration in milliseconds. Default to 20 minutes as per Altcha security recommendations. See https://altcha.org/docs/v2/security-recommendations/

Contributing

We welcome contributions to improve this library. Feel free to submit issues or pull requests!

License

This project is licensed under the MIT License. See the LICENSE file for details.