django-altcha 0.9.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)

Replay Attack Protection

Django Altcha automatically protects against replay attacks by ensuring each challenge can only be used once. When a challenge is successfully validated, it is stored in a cache and any subsequent attempt to reuse the same challenge will be rejected.

This protection is enabled by default and requires no additional configuration for single-process deployments.

[!IMPORTANT] The default in-memory cache is not shared across workers. If you run multiple workers (e.g., with gunicorn or uwsgi), you must configure a shared cache backend using the ALTCHA_CACHE_ALIAS setting.

Settings

ALTCHA_HMAC_KEY

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

ALTCHA_CACHE_ALIAS

Cache alias used for replay attack protection.

By default, challenges are stored in a local in-memory cache to prevent reuse. This works well for single-process deployments, but does not protect against replay attacks in multi-worker setups (e.g., gunicorn or uwsgi with multiple workers).

For production deployments with multiple workers, configure a shared cache backend:

Using Redis or Memcached:

CACHES = {
    'default': {
        'BACKEND': 'django.core.cache.backends.redis.RedisCache',
        'LOCATION': 'redis://127.0.0.1:6379',
    }
}
ALTCHA_CACHE_ALIAS = 'default'

Using Database Caching:

If you prefer not to set up Redis or Memcached, Django's built-in database cache is a simple alternative:

CACHES = {
    'altcha': {
        'BACKEND': 'django.core.cache.backends.db.DatabaseCache',
        'LOCATION': 'altcha_cache',
    }
}
ALTCHA_CACHE_ALIAS = 'altcha'

Then create the cache table:

python manage.py createcachetable

ALTCHA_CHALLENGE_EXPIRE

Challenge expiration duration in milliseconds. Defaults to 20 minutes as per Altcha security recommendations.

ALTCHA_JS_URL

URL of the Altcha JavaScript file. Defaults to the bundled django-altcha file.

ALTCHA_INCLUDE_TRANSLATIONS

Whether to include Altcha translations. Defaults to False.

ALTCHA_JS_TRANSLATIONS_URL

URL of the Altcha translations JavaScript file. Defaults to the bundled django-altcha file.

Only loaded when ALTCHA_INCLUDE_TRANSLATIONS is True.

ALTCHA_VERIFICATION_ENABLED

Set to False to skip Altcha validation altogether. Defaults to True.

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.