From 2589d3bf7661d0499f89921bf99f81bbe985c7e9 Mon Sep 17 00:00:00 2001 From: Mohamed El-Kalioby Date: Fri, 18 Jan 2019 11:10:41 +0300 Subject: [PATCH 1/5] Update README.md --- README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 67 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index fb2e70f..7bbd9fc 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,68 @@ # django-mfa2 -A Django app that handles MFA, it support OTOP, U2F, FIDO2 U2F, & Trusted Devices +A Django app that handles MFA, it supports OTOP, U2F, FIDO2 U2F, and Trusted Devices + + +For FIDO2, both security keys and android-safetynet are supported. + +Trusted device is a mode for the user to add a device that doesn't support security keys like iOS and andriod without fingerprints or NFC. + +`*Note*: U2F and FIDO2 can only be served under secure context (https)` + +Depends on + +* pyotp +* python-u2flib-server +* ua-parser +* user-agents +* python-jose +* fido2==0.5 + + +# Installation +1. `pip install django-mfa2` +1. in your settings.py add the application to your installed apps + ```python + INSTALLED_APPS=( + '......', + 'mfa', + '......') + ``` +1. Add the following settings to your file + + ```python + MFA_UNALLOWED_METHODS=() # Methods that shouldn't be allowed for the user + MFA_CALLBACK="" # A function that should be called by username to login the user in session + MFA_RECHECK=True # Allow random rechecking of the user + MFA_RECHECK_MIN=10 # Minimum interval in seconds + MFA_RECHECK_MAX=30 # Maximum in seconds + MFA_QUICKLOGIN=True # Allow quick login for returning users by provide only their 2FA + + TOKEN_ISSUER_NAME="MDL" #TOTP Issuer name + + U2F_APPID="https://localhost" #URL For U2F + FIDO_SERVER_ID=u"localhost" # Server rp id for FIDO2 + FIDO_SERVER_NAME=u"MDL" + FIDO_LOGIN_URL=BASE_URL + ``` +1. 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 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 + + ```python + def login(request): # this function handles the login form POST + user = auth.authenticate(username=username, password=password) + if user is not None: # if the user object exist + from mfa.helpers import has_mfa + res = has_mfa(username = username,request=request) # has_mfa returns false or HttpResponseRedirect + if res: + return res + return log_user_in(request,username=user.username) + #log_user_in is a function that handles creatung user session, it should be in the setting file as MFA_CALLBACK + ``` +1. Provide `mfa_auth_base.html` in your templaes + The template will be included for the user login From 4e99d2b45a0bb9fc1e4973da6ffdc0eb39270cf1 Mon Sep 17 00:00:00 2001 From: Mohamed El-Kalioby Date: Fri, 18 Jan 2019 14:44:42 +0300 Subject: [PATCH 2/5] URLS --- README.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7bbd9fc..566286f 100644 --- a/README.md +++ b/README.md @@ -64,5 +64,14 @@ Depends on return log_user_in(request,username=user.username) #log_user_in is a function that handles creatung user session, it should be in the setting file as MFA_CALLBACK ``` -1. Provide `mfa_auth_base.html` in your templaes - The template will be included for the user login +1. Add mfa to urls.py + ```python + import mfa + urls_patterns= [ + '...', + url(r'^mfa/', include(mfa.urls)), + '....', + ] + ``` +1. Provide `mfa_auth_base.html` in your templaes with block called 'head' and 'content' + The template will be included during the user login From 6c5a6604ae3475732149135c654c8ad271570c98 Mon Sep 17 00:00:00 2001 From: Mohamed El-Kalioby Date: Fri, 18 Jan 2019 14:57:46 +0300 Subject: [PATCH 3/5] Update README.md --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 566286f..b186def 100644 --- a/README.md +++ b/README.md @@ -74,4 +74,7 @@ Depends on ] ``` 1. Provide `mfa_auth_base.html` in your templaes with block called 'head' and 'content' - The template will be included during the user login + The template will be included during the user login. +1. To match the look and feel of your project, MFA includes base.html but it need a block named content to added its content in it. +1. Somewhere in your app, add a link to 'mfa_home' +```Security ``` From e60928a4578090c0d704de2cce30d08cc7b06154 Mon Sep 17 00:00:00 2001 From: Mohamed El-Kalioby Date: Fri, 18 Jan 2019 15:42:02 +0300 Subject: [PATCH 4/5] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b186def..41543fc 100644 --- a/README.md +++ b/README.md @@ -31,7 +31,7 @@ Depends on ```python MFA_UNALLOWED_METHODS=() # Methods that shouldn't be allowed for the user - MFA_CALLBACK="" # A function that should be called by username to login the user in session + MFA_LOGIN_CALLBACK="" # A function that should be called by username to login the user in session MFA_RECHECK=True # Allow random rechecking of the user MFA_RECHECK_MIN=10 # Minimum interval in seconds MFA_RECHECK_MAX=30 # Maximum in seconds From 3dc78d96fa1f2fd86ef31461d46bc27466e278e5 Mon Sep 17 00:00:00 2001 From: Mohamed El-Kalioby Date: Fri, 18 Jan 2019 16:00:30 +0300 Subject: [PATCH 5/5] Update README.md --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 41543fc..05bf294 100644 --- a/README.md +++ b/README.md @@ -67,9 +67,11 @@ Depends on 1. Add mfa to urls.py ```python 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"), # This short link to add new trusted device '....', ] ```