https://github.com/aboutcode-org/django-altcha
Django field and widget for Altcha CAPTCHA.
https://github.com/aboutcode-org/django-altcha
altcha captcha django open-source
Last synced: 3 months ago
JSON representation
Django field and widget for Altcha CAPTCHA.
- Host: GitHub
- URL: https://github.com/aboutcode-org/django-altcha
- Owner: aboutcode-org
- License: mit
- Created: 2025-03-27T08:37:40.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2025-07-25T07:25:37.000Z (6 months ago)
- Last Synced: 2025-09-27T17:02:27.375Z (3 months ago)
- Topics: altcha, captcha, django, open-source
- Language: Python
- Homepage: https://django-altcha.readthedocs.io
- Size: 72.3 KB
- Stars: 4
- Watchers: 5
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.rst
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.rst
Awesome Lists containing this project
README
# 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:**
```bash
pip install django-altcha
```
2. **Add to `INSTALLED_APPS`:**
Update your Django project's `settings.py`:
```python
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`:
```python
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:
```python
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](https://altcha.org/docs/website-integration/).
### Example with additional options:
```python
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:
```python
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:
```python
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](./LICENSE) file for details.