An implementation of basic multi-factor authentication (MFA) functions in Django (phone, text and email)
MIT License
An easy-to-integrate implementation of essential Multi-Factor Authentication (MFA) functionality for Django applications.
Available on PyPI (pip install django-simplemfa
)
The intent of this project is to:
Upon evaluating various other Django MFA applications, most appeared to be one or more of the following:
Twilio is the current integration for phone and text message MFA, but more are planned. Email MFA leverages the built-in Django email utilities.
Download or clone the simplemfa
package here into your Django application or install from PyPi with pip install django-simplemfa
.
templates/simplemfa
)Create a new directory called 'simplemfa' and in it place or create the following template:
simplemfa/auth.html
(the MFA login screen template)The following templates are optional if you want to override the default content for each:
simplemfa/mfa_email.html
(the MFA email message template)simplemfa/mfa_text.html
(the MFA text message template)simplemfa/mfa_voice.html
(plain text file with the message you want to say via phone call)Examples and defaults are provided in the package's templates
directory (simplemfa/templates
).
urls.py
)Add path('mfa/', include('simplemfa.urls', namespace="simplemfa"))
to your routes, making sure to include the namespace as shown.
settings.py
)REQUIRE_MFA = True
(global setting which activates MFA for all users)INSTALLED_APPS = [ ... 'simplemfa' ]
MIDDLEWARE = [ ... 'simplemfa.middleware.ValidateMFAMiddleware' ]
If using Twilio (text and voice):
MFA_USER_PHONE_ATTRIBUTE
(the attribute of request.user
that has the phone number for the user in the format +12345678900
, e.g. profile.phone
resolves to request.user.profile.phone
)APP_NAME = "My App Name"
(application name which is provided in the messages to the user)MFA_CODE_LENGTH
(default is 6)MFA_COOKIE_EXPIRATION_DAYS
(the default "remember me" period, default is 7)MFA_CODE_EXPIRATION
(default is 900 seconds (15 minutes))MFA_CODE_DELIVERY_DEFAULT
(default is "EMAIL")MFA_USER_MODE_ATTRIBUTE
(the attribute of request.user
that has the user's default way of receiving the MFA code, e.g. profile.mfa_mode
resolves to request.user.profile.mfa_mode
which must be one of the choices from simplemfa.models.AUTH_CODE_DELIVERY_CHOICES
- currently "EMAIL", "TEXT", and "PHONE")Once those items are complete, run makemigrations
and migrate
for your project, then run your project. That's it!
It should allow you to access all public (login exempt) pages. After you log in, however, it will automatically redirect you to the MFA verification page where you will request and then enter an MFA code. If the code passes, you will be allowed to proceed as any normal authenticated user would in your application.
A project example is coming shortly.
As of right now, MFA is applied globablly in the settings.py
file. We are working on changing that to track in a User's settings as part of an MFAProfile
model attached to the User object.
MFA codes sent to users are stored as one-way hashed objects using Django's built-in hashers. It is treated as a password field in the application. The hashes are created and verified using Django's own make_password()
and check_password()
functions, respectively. The ONLY time a plain-text MFA code is created in the application is during the sending of the user message to the Twilio API or via email.