django-mfa2
A Django app that handles MFA, it supports TOTP, U2F, FIDO2 U2F (Web Authn), Email Tokens , Trusted Devices and backup codes.
Pip Stats
Conda Stats
Web Authencation API (WebAuthn) is state-of-the art techology that is expected to replace passwords.
For FIDO2, the following are supported
- security keys (Firefox 60+, Chrome 67+, Edge 18+, Safari 13 on Mac OS, Chrome on Andriod, Safari on iOS 13.3+),
- Windows Hello (Firefox 67+, Chrome 72+ , Edge),
- Apple's Touch ID/Face ID (Chrome 70+ on Mac OS X, Safari on macOS Big Sur, Safari on iOS 14.0+ ),
- android-safetynet (Chrome 70+, Firefox 68+)
- NFC devices using PCSC (Not Tested, but as supported in fido2)
- Soft Tokens
krypt.co: Login by a notification on your phone.
Update: Dec 2022, krypt.co has been killed by Google for Passkeys.
In English :), It allows you to verify the user by security keys on PC, Laptops or Mobiles, Windows Hello (Fingerprint, PIN) on Windows 10 Build 1903+ (May 2019 Update) Touch/Face ID on Macbooks (Chrome, Safari), Touch/Face ID on iPhone and iPad and Fingerprint/Face/Iris/PIN on Android Phones.
Trusted device is a mode for the user to add a device that doesn't support security keys like Android without fingerprints or NFC.
Note: U2F and FIDO2 can only be served under secure context (https)
Package tested with Django 1.8, Django 2.2 on Python 2.7 and Python 3.5+ but it was not checked with any version in between but open for issues.
If you just need WebAuthn and Passkeys, you can use django-passkeys, which is a slim-down of this app and much easier to integrate.
Depends on
- pyotp
- python-u2flib-server
- ua-parser
- user-agents
- python-jose
- fido2==1.0.0
Installation
-
using pip
-
Using Conda forge
conda config --add channels conda-forge
conda install django-mfa2
For more info, see the conda-forge repo (https://github.com/conda-forge/django-mfa2-feedstock)
Thanks for swainn for adding package to conda-forge
Usage
-
in your settings.py add the application to your installed apps
INSTALLED_APPS=(
'......',
'mfa',
'......')
-
Collect Static Files
python manage.py collectstatic
-
Add the following settings to your file
from django.conf.global_settings import PASSWORD_HASHERS as DEFAULT_PASSWORD_HASHERS
MFA_UNALLOWED_METHODS=()
MFA_LOGIN_CALLBACK=""
MFA_RECHECK=True
MFA_REDIRECT_AFTER_REGISTRATION="mfa_home"
MFA_SUCCESS_REGISTRATION_MSG = "Go to Security Home"
MFA_RECHECK_MIN=10
MFA_RECHECK_MAX=30
MFA_QUICKLOGIN=True
MFA_ALWAYS_GO_TO_LAST_METHOD = False
MFA_RENAME_METHODS={}
MFA_HIDE_DISABLE=('FIDO2',)
MFA_OWNED_BY_ENTERPRISE = False
PASSWORD_HASHERS = DEFAULT_PASSWORD_HASHERS
PASSWORD_HASHERS += ['mfa.recovery.Hash']
RECOVERY_ITERATION = 350000
TOKEN_ISSUER_NAME="PROJECT_NAME"
U2F_APPID="https://localhost"
FIDO_SERVER_ID=u"localehost"
FIDO_SERVER_NAME=u"PROJECT_NAME"
import mfa
MFA_FIDO2_RESIDENT_KEY = mfa.ResidentKey.DISCOURAGED
MFA_FIDO2_AUTHENTICATOR_ATTACHMENT = None
MFA_FIDO2_USER_VERIFICATION = None
MFA_FIDO2_ATTESTATION_PREFERENCE = mfa.AttestationPreference.NONE
MFA_ENFORCE_EMAIL_TOKEN = False
MFA_SHOW_OTP_IN_EMAIL_SUBJECT = False
MFA_OTP_EMAIL_SUBJECT= "OTP"
Method Names
- U2F
- FIDO2
- TOTP
- Trusted_Devices
- Email
- RECOVERY
Notes:
- Starting version 1.1,
FIDO_LOGIN_URL isn't required for FIDO2 anymore. - Starting version 1.7.0, Key owners can be specified.
- Starting version 2.2.0
- Added:
MFA_SUCCESS_REGISTRATION_MSG
& MFA_REDIRECT_AFTER_REGISTRATION
- Starting version 2.6.0
- Added:
MFA_ALWAYS_GO_TO_LAST_METHOD
, MFA_RENAME_METHODS
, MFA_ENFORCE_RECOVERY_METHOD
& RECOVERY_ITERATION
- Starting version 3.0
- Added:
MFA_FIDO2_RESIDENT_KEY
, MFA_FIDO2_AUTHENTICATOR_ATTACHMENT
, MFA_FIDO2_USER_VERIFICATION
, MFA_FIDO2_ATTESTATION_PREFERENCE
- Added:
MFA_ENFORCE_EMAIL_TOKEN
, MFA_SHOW_OTP_IN_EMAIL_SUBJECT
, MFA_OTP_EMAIL_SUBJECT
-
Break your login function
Usually your login function will check for username and password, log the user in if the username and password are correct and create the user session, to support mfa, this has to change
- authenticate the user
- if username and password are correct , check if the user has mfa or not
- if user has mfa then redirect to mfa page
- if user doesn't have mfa then call your function to create the user session
def login(request):
user = auth.authenticate(username=username, password=password)
if user is not None:
from mfa.helpers import has_mfa
res = has_mfa(username = username,request=request)
if res:
return res
return log_user_in(request,username=user.username)
-
Add mfa to urls.py
import mfa
import mfa.TrustedDevice
urls_patterns= [
'...',
url(r'^mfa/', include('mfa.urls')),
url(r'devices/add$', mfa.TrustedDevice.add,name="mfa_add_new_trusted_device"),
'....',
]
-
Provide mfa_auth_base.html
in your templates with block called 'head' and 'content', The template will be included during the user login, the template shall be close to the login template.
If you will use Email Token method, then you have to provide template named mfa_email_token_template.html
that will content the format of the email with parameter named user
and otp
.
-
To match the look and feel of your project, MFA includes base.html
but it needs blocks named head
& content
to added its content to it.
Note: Starting v2.3.0, a new template mfa_base.html
is introduced, this template is used by MFA.html
so you can control the styling better and current mfa_base.html
extends base.html
-
Somewhere in your app, add a link to 'mfa_home'
<li><a href="{% url 'mfa_home' %}">Security</a> </li>
For Example, See 'example' app and look at EXAMPLE.md to see how to set it up.
Going Passwordless
To be able to go passwordless for returning users, create a cookie named 'base_username' containing username as shown in snippet below
response = render(request, 'Dashboard.html', context))
if request.session.get("mfa",{}).get("verified",False) and getattr(settings,"MFA_QUICKLOGIN",False):
if request.session["mfa"]["method"]!="Trusted Device":
response.set_cookie("base_username", request.user.username, path="/",max_age = 15*24*60*60)
return response
Second, update the GET part of your login view
if "mfa" in settings.INSTALLED_APPS and getattr(settings,"MFA_QUICKLOGIN",False) and request.COOKIES.get('base_username'):
username=request.COOKIES.get('base_username')
from mfa.helpers import has_mfa
res = has_mfa(username = username,request=request,)
if res: return res
Checking MFA on Client Side
Sometimes you like to verify that the user is still there so simple you can ask django-mfa2 to check that for you
{% include 'mfa_check.html' %}
function success_func() {
}
function fail_func() {
}
function some_func() {
recheck_mfa(success_func,fail_func,MUST_BE_MFA)
}
Contributors
Security contact information
To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.