Django app for performing 2FA using Twilio Verify
Project description
Django 2FA using Twilio Verify
Prerequisites
- Python 3.6+
- Twilio account
django
2.29+twilio
7.8.2+phonenumbers
8.12.26+
Installation
Install using pip install django-twilio-2fa
.
If install fails, try pip install --upgrade pip
Add to your INSTALLED_APPS
:
INSTALLED_APPS = (
...
"django_twilio_2fa",
"django_widget_tweaks", # only required if using included templates
...
)
Add the project urls.py
:
urlpatterns = [
...
# View-based 2FA
path(
"2fa/", # Can be changed to any path
include("django_twilio_2fa.urls")
),
# API-based 2FA
path(
"2fa-api/", # Can be changed to any path
include("django_twilio_2fa.api.urls")
),
...
]
Other Pages
Signals
Signal names are prefixed twilio_2fa_
.
All signals are sent with at least the following arguments:
request
: CurrentRequest
instance orNone
user
:User
instance orNone
twilio_error
When the Twilio client throws an error, this signal is emitted -- whether the error was handled.
This is a special signal that only provides the exception instance as exc
and no other arguments.
set_user_data
When a user registers or changes their 2FA data, this signal is emitted the updated information and should be used to update the user's instance.
Additional arguments sent with this signal:
field
: field name (phone_number
is the only option)value
: updated value
verification_sent
This signal is triggered anytime a verification is sent.
Additional arguments sent with this signal:
method
: Verification methodverification_sid
: Twilio SID for verificationstart_timestamp
:DateTime
of the original sendlast_timestamp
:DateTime
of the last send attempt
verification_success
This signal is triggered when a user completes verification successfully.
The verification_status_changed
signal is also triggered during a successful verification.
Additional arguments sent with this signal:
verification_sid
: Twilio verification SID
verification_status_changed
This signal is triggered when the Twilio verification status is changed.
Options for status
: approved
and canceled
.
Additional arguments sent with this signal:
status
: Status verification was changed toverification_sid
: Twilio verification SID
verification_failed
This signal is triggered when the Twilio verification attempt has failed.
Additional arguments sent with this signal:
verification_sid
: Twilio verification SID
Customization
The presentation code uses Bootstrap 5, Font Awesome 5, and django-widget-tweaks. None are an absolute requirement and can be removed using custom templates or, in the case of Font Awesome, defining the METHOD_DISPLAY_CB
setting.
All templates are in the twilio_2fa
directory. To override these templates, you can put your version in your own twilio_2fa
directory anywhere your templates are stored.
_base.html
This is the primary template that all main templates extends.
It defines a single block for content: content
(outlined in yellow above). For django_widget_tweaks
, the content
block is wrapped by WIDGET_ERROR_CLASS
.
The header can also be changed using the header
block (outlined in red). Header icon classes changed using the header_icon_class
block (outlined in blue) and text changed using the header_text
block (outlined in green).
_messages.html
This template shows messages from django.contrib.messages
and is included in each of the main templates.
_form_errors.html
This template displays a form field's errors. field
should be passed in the context.
failed.html
This template is shown when the user's verification failed either from a timeout of the verification, maximum tries are exceeded, an API failure with Twilio, or other general error.
It conditionally allows users to retry verification based on the can_retry
session variable.
registration_form.html
This template shows the registration form to the user and serves as the base template for register.html
and change.html
.
register.html
This template shows the registration form to the user.
If ALLOW_REGISTRATION
is False
, the user is not shown this view and will be redirected to the failure page if no phone number is returned by PHONE_NUMBER_CB
.
It is based on registration_form.html
.
change.html
This template shows the change form to the user.
It is based on registration_form.html
.
start.html
This template allows the user to select the verification method.
If only one method exists, the user will not see this page.
success.html
This template is shown on a successful verification if VERIFY_SUCCESS_URL
is not set.
verify.html
This template shows the token form.
Development
Perform the following steps in the root directory:
- Create a virtual environment and activate.
- Install
django_twilio_2fa
:pip install -e .
Perform the following steps in the test_app
directory:
3. Update path to this package in the requirements.txt
4. Install requirements: pip install -r requirements.txt
.
5. Copy .env-sample
to .env
and update with your twilio settings.
6. Run migrations: python manage.py migrate
.
7. Run the server: python manage.py runserver
.
The test app should now be available at http://localtest.me:8000.
To run tests, run python manage.py test
from the test_app
directory.
To-Do
InternationalizationE-mail verification- WhatsApp integration
- TOTP integration
- Push for web integration
Abstraction for 2FA outside of web flow
Changelog
- 0.32 - bug fixes for lost users
- 0.31 - minor fix of
error_displays
setting - 0.30 - added more messages for user displays; updated view-based templates to use messages; added
display
key to API-based responses - 0.29 - downgraded requirements for inclusivity
- 0.28 - added better customization of user messaging
- 0.27 - allow sending verifications to different values; set default status code for errors to 400
- 0.26 - added handling of Twilio Error 60200
- 0.25 - bug fix for handling unauthenticated users
- 0.24 - refactored to abstract process; added API endpoints; allow for userless 2FA
- 0.23 - Twilio rate limiting error handling
- 0.22 - Added internationalization and e-mail verification (thanks to jgoodsell-summitgrp)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_twilio_2fa-0.32-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e2ffa231cd0ac1e5614311c0d867dea157e37790eb2ef731bf3525b7777a492d |
|
MD5 | 55312bb7756b213ebf2de6a2e26aab9c |
|
BLAKE2b-256 | 77e594748f897d87c521657ad66b37b9eaa207286ea6b05c8af433563c56b720 |