Upgrade to FIDO2 (0.6) and Supporting Windows Hello

Fixed A bug While Sending Emails Without MFA

README.md

@@ -7,9 +7,9 @@ Web Authencation API (WebAuthn) is state-of-the art techology that is expected t
 
 ![Andriod Fingerprint](https://cdn-images-1.medium.com/max/800/1*1FWkRE8D7NTA2Kn1DrPjPA.png)
 
-For FIDO2, both security keys and android-safetynet are supported.
+For FIDO2, **security keys**, **Windows Hello**, **Apple's Touch ID (Chrome)** and **android-safetynet** are supported.
 
-In English :), It allows you to verify the user by security keys on PC, Laptops and Fingerprint/PIN on Andriod Phones.
+In English :), It allows you to verify the user by security keys on PC, Laptops, Windows Hello (Fingerprint, PIN) on Windows 10 Build 1903 (May 2019 Update) Touch ID on Macbooks (Chrome) and Fingerprint/PIN on Andriod Phones.
 
 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.
 
@@ -36,6 +36,8 @@ Depends on
    'mfa',
    '......')
    ```
+1. Collect Static Files
+`python manage.py collectstatic`
 1. Add the following settings to your file
 
    ```python 
@@ -45,6 +47,7 @@ Depends on
    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
+   MFA_HIDE_DISABLE=('FIDO2',)     # Can the user disable his key (Added in 1.2.0).   
 
    TOKEN_ISSUER_NAME="PROJECT_NAME"      #TOTP Issuer name
 
@@ -60,6 +63,8 @@ Depends on
    * Trusted_Devices
    * Email
    
+   **Note**: Starting version 1.1, ~~FIDO_LOGIN_URL~~ isn't required for FIDO2 anymore.
+   
 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
@@ -99,3 +104,44 @@ Depends on
 ```<li><a href="{% url 'mfa_home' %}">Security</a> </li>```
 
 For Example, See https://github.com/mkalioby/AutoDeploy/commit/5f1d94b1804e0aa33c79e9e8530ce849d9eb78cc in AutDeploy Project
+
+# Going Passwordless
+
+To be able to go passwordless for returning users, create a cookie  named 'base_username' containing username as shown in snippet below
+```python
+    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
+```python
+    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
+        ## continue and return the form.
+```
+# 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
+
+```html
+    {% include 'mfa_check.html' %}
+```
+````js
+function success_func() {
+  //logic if mfa check succeeds
+}
+function fail_func() {
+  //logic if mfa check fails
+}
+function some_func() {
+    recheck_mfa(success_func,fail_func,MUST_BE_MFA)
+    //MUST_BE_MFA true or false, if the user must has with MFA
+  }
+
+````

docs/change_login.md

@@ -0,0 +1,23 @@
+# Change of login function
+
+## 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
+
+<code>
+    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
+</code>
+

docs/index.md

@@ -0,0 +1,36 @@
+# django-mfa2
+A Django app that handles MFA, it supports TOTP, U2F, FIDO2 U2F (Web Authn), Email Tokens , and Trusted Devices
+
+[![PyPI version](https://badge.fury.io/py/django-mfa2.svg)](https://badge.fury.io/py/django-mfa2)
+
+Web Authencation API (WebAuthn) is state-of-the art techology that is expected to replace passwords.
+
+![Andriod Fingerprint](https://cdn-images-1.medium.com/max/800/1*1FWkRE8D7NTA2Kn1DrPjPA.png)
+
+For FIDO2, both security keys and android-safetynet are supported.
+
+In English :), It allows you to verify the user by security keys on PC, Laptops and Fingerprint/PIN on Andriod Phones.
+
+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)`
+
+Package tested with Django 1.8, Django 2.1 on Python 2.7 and Python 3.5+ but it was not checked with any version in between but open for issues.
+
+Depends on
+
+* pyotp
+* python-u2flib-server
+* ua-parser
+* user-agents
+* python-jose
+* fido2==0.5
+
+# Example
+
+For Example, See https://github.com/mkalioby/AutoDeploy/commit/5f1d94b1804e0aa33c79e9e8530ce849d9eb78cc in AutDeploy Project
+
+# Table of Contents
+* [Installation](installation.md)
+* [Change Login Code](change_login.md)
+

docs/installation.md

@@ -0,0 +1,58 @@
+# Installation & Configuration
+1. Install the package 
+  ```sh
+   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_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
+    MFA_QUICKLOGIN=True        # Allow quick login for returning users by provide only their 2FA 
+    
+    TOKEN_ISSUER_NAME="PROJECT_NAME"      #TOTP Issuer name
+    
+    U2F_APPID="https://localhost"    #URL For U2
+    FIDO_SERVER_ID=u"localehost"      # Server rp id for FIDO2, it the full domain of your project
+    FIDO_SERVER_NAME=u"PROJECT_NAME"
+    FIDO_LOGIN_URL=BASE_URL
+   ```
+   
+   **Method Names**
+   * U2F
+   * FIDO2
+   * TOTP
+   * Trusted_Devices
+   * Email
+   
+   **Note**: Starting version 1.1, ~~FIDO_LOGIN_URL~~ isn't required for FIDO2 anymore.
+   
+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
+    '....',
+    ]
+    ```
+1. Provide `mfa_auth_base.html` in your templaes with block called 'head' and 'content'
+    The template will be included during the user login.
+    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`.
+1. 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.
+1. Somewhere in your app, add a link to 'mfa_home'
+```<li><a href="{% url 'mfa_home' %}">Security</a> </li>```
+
+Next, you need to [change your login code](change_login.md)

mfa/CHANGELOG.md

@@ -0,0 +1,4 @@
+# Change Log
+
+## v1.2.0
+ * Added:  MFA_HIDE_DISABLE setting option to disable users from deactivating their keys.

mfa/Email.py

@@ -9,7 +9,9 @@ from .Common import send
 def sendEmail(request,username,secret):
     from django.contrib.auth import get_user_model
     User = get_user_model()
-    user=User.objects.get(username=username)
+    key = getattr(User, 'USERNAME_FIELD', 'username')
+    kwargs = {key: username}
+    user = User.objects.get(**kwargs)
     res=render_to_response("mfa_email_token_template.html",{"request":request,"user":user,'otp':secret})
     return  send([user.email],"OTP", res.content)
 
@@ -28,7 +30,7 @@ def start(request):
         context["invalid"] = True
     else:
         request.session["email_secret"] = str(randint(0,100000))
-        if sendEmail(request, request.session["base_username"], request.session["email_secret"]):
+        if sendEmail(request, request.user.username, request.session["email_secret"]):
             context["sent"] = True
     return render_to_response("Email/Add.html", context, context_instance=RequestContext(request))
 def auth(request):

mfa/FIDO2.py

@@ -34,11 +34,11 @@ def begin_registeration(request):
     }, getUserCredentials(request.user.username))
     request.session['fido_state'] = state
 
-    return HttpResponse(cbor.dumps(registration_data),content_type='application/octet-stream')
+    return HttpResponse(cbor.encode(registration_data),content_type='application/octet-stream')
 @csrf_exempt
 def complete_reg(request):
     try:
-        data = cbor.loads(request.body)[0]
+        data = cbor.decode(request.body)
 
         client_data = ClientData(data['clientDataJSON'])
         att_obj = AttestationObject((data['attestationObject']))
@@ -79,7 +79,7 @@ def authenticate_begin(request):
     credentials=getUserCredentials(request.session.get("base_username",request.user.username))
     auth_data, state = server.authenticate_begin(credentials)
     request.session['fido_state'] = state
-    return HttpResponse(cbor.dumps(auth_data),content_type="application/octet-stream")
+    return HttpResponse(cbor.encode(auth_data),content_type="application/octet-stream")
 
 @csrf_exempt
 def authenticate_complete(request):
@@ -87,7 +87,7 @@ def authenticate_complete(request):
     username=request.session.get("base_username",request.user.username)
     server=getServer()
     credentials=getUserCredentials(username)
-    data = cbor.loads(request.body)[0]
+    data = cbor.decode(request.body)
     credential_id = data['credentialId']
     client_data = ClientData(data['clientDataJSON'])
     auth_data = AuthenticatorData(data['authenticatorData'])
@@ -112,6 +112,6 @@ def authenticate_complete(request):
                 mfa["next_check"] = int((datetime.datetime.now()+ datetime.timedelta(
                 seconds=random.randint(settings.MFA_RECHECK_MIN, settings.MFA_RECHECK_MAX))).strftime("%s"))
             request.session["mfa"] = mfa
-            login(request)
-            return HttpResponse(simplejson.dumps({'status':"OK","redirect":settings.FIDO_LOGIN_URL}),content_type="application/json")
+            res=login(request)
+            return HttpResponse(simplejson.dumps({'status':"OK","redirect":res["location"]}),content_type="application/json")
     return HttpResponse(simplejson.dumps({'status': "err"}),content_type="application/json")

mfa/TrustedDevice.py

@@ -106,7 +106,12 @@ def start(request):
 def send_email(request):
     body=render(request,"TrustedDevices/email.html",{}).content
     from .Common import send
-    if send([request.user.email],"Add Trusted Device Link",body):
+    e=request.user.email
+    if e=="":
+        e=request.session.get("user",{}).get("email","")
+    if e=="":
+        res = "User has no email on the system."
+    elif send([e],"Add Trusted Device Link",body):
         res="Sent Successfully"
     else:
         res="Error occured, please try again later."

mfa/models.py

@@ -17,6 +17,9 @@ class User_Keys(models.Model):
         if self.key_type == "Trusted Device" and self.properties.get("signature","") == "":
             self.properties["signature"]= jwt.encode({"username": self.username, "key": self.properties["key"]}, settings.SECRET_KEY)
         super(User_Keys, self).save(force_insert=force_insert, force_update=force_update, using=using, update_fields=update_fields)
-
+    def __unicode__(self):
+        return "%s -- %s"%(self.username,self.key_type)
+    def __str__(self):
+        return self.__unicode__()
     class Meta:
         app_label='mfa'

mfa/templates/MFA.html

@@ -20,6 +20,7 @@
         $("#modal-footer").prepend("<button id='actionBtn' class='btn btn-danger' onclick='confirmDel("+id+")'>Confirm Deletion</button>")
         $("#popUpModal").modal()
     }
+    {% if not HIDE_DISABLE %}
     function toggleKey(id) {
         $.ajax({
             url:"{% url 'toggle_key' %}?id="+id,
@@ -33,6 +34,7 @@
             }
         })
     }
+    {% endif %}
     </script>
     <link href="{% static  'mfa/css/bootstrap-toggle.min.css' %}" rel="stylesheet">
     <script src="{% static 'mfa/js/bootstrap-toggle.min.js'%}"></script>
@@ -87,8 +89,16 @@
                <td>{{ key.expires }}</td>
                <td>{% if key.device %}{{ key.device }}{% endif %}</td>
                <td>{{ key.last_used }}</td>
-               <td><input type="checkbox" id="toggle_{{ key.id }}" {% if key.enabled %}checked{% endif %} data-onstyle="success" data-offstyle="danger"  onchange="toggleKey({{ key.id }})" data-toggle="toggle"></td>
-               <td><a href="javascript:void(0)" onclick="deleteKey({{ key.id }},'{{ key.key_type }}')"> <span class="fa fa-trash"></span></a></td>
+                {% if key.key_type in HIDE_DISABLE %}
+                    <td>{% if key.enabled %}On{% else %} Off{% endif %}</td>
+                {% else %}
+                    <td><input type="checkbox" id="toggle_{{ key.id }}" {% if key.enabled %}checked{% endif %} data-onstyle="success" data-offstyle="danger"  onchange="toggleKey({{ key.id }})" data-toggle="toggle" class="status_chk"></td>
+                {% endif %}
+               <td>{% if key.key_type in HIDE_DISABLE %}
+                   ----
+                   {% else %}
+                    <a href="javascript:void(0)" onclick="deleteKey({{ key.id }},'{{ key.key_type }}')"> <span class="fa fa-trash"></span></a></td>
+                    {% endif %}
            </tr>
        {% empty %}
            <tr><td colspan="7" align="center">You didn't have any keys yet.</td> </tr>

mfa/templates/TrustedDevices/Add.html

@@ -62,7 +62,6 @@
       <fieldset>
       <div class="row">
       <div class="col-sm-12 col-md-12">
-{#      <img class="profile-img" src="{{ STATIC_URL }}img/users.png" alt="">#}
       </div>
       </div>
       <div class="row">

mfa/templates/U2F/Add.html

@@ -1,4 +1,5 @@
 {% extends "base.html" %}
+{% load static %}
 {% block head %}
     <style>
     #two-factor-steps {
@@ -10,7 +11,7 @@
         margin: 0px;
     }
     </style>
-    <script src="{{ STATIC_URL }}js/u2f-api.js" type="text/javascript"></script>
+    <script src="{% static 'mfa/js/u2f-api.js' %}" type="text/javascript"></script>
     <script type="text/javascript">
     $(document).ready(function addToken() {
                 data=JSON.parse('{{ token|safe }}')

mfa/templates/U2F/recheck.html

@@ -1,3 +1,4 @@
+{% load static %}
 <div class="row">
 
 <div class="col-sm-10 col-sm-offset-1 col-xs-12 col-md-10 col-md-offset-1 col-lg-8 col-lg-offset-2">
@@ -34,7 +35,7 @@
 </div>
 </div>
 </div>
-    <script src="{{ STATIC_URL }}js/u2f-api.js" type="text/javascript"></script>
+    <script src="{% static 'mfa/js/u2f-api.js' %}" type="text/javascript"></script>
 
     <script type="text/javascript">
     $(document).ready(function () {

mfa/views.py

@@ -12,14 +12,15 @@ from . import TrustedDevice
 from user_agents import parse
 def index(request):
     keys=[]
-    context={"keys":User_Keys.objects.filter(username=request.user.username),"UNALLOWED_AUTHEN_METHODS":settings.MFA_UNALLOWED_METHODS}
+    context={"keys":User_Keys.objects.filter(username=request.user.username),"UNALLOWED_AUTHEN_METHODS":settings.MFA_UNALLOWED_METHODS
+             ,"HIDE_DISABLE":getattr(settings,"MFA_HIDE_DISABLE",[])}
     for k in context["keys"]:
         if k.key_type =="Trusted Device" :
             setattr(k,"device",parse(k.properties.get("user_agent","-----")))
         elif k.key_type == "FIDO2":
             setattr(k,"device",k.properties.get("type","----"))
         keys.append(k)
-        context["keys"]=keys
+    context["keys"]=keys
     return render_to_response("MFA.html",context,context_instance=RequestContext(request))
 
 def verify(request,username):

mkdocs.yml

@@ -0,0 +1,8 @@
+site_name: MkLorum
+nav:
+    - Home: index.md
+    - Installation: installation.md
+    - Code Changes: change_login.md 
+theme: readthedocs
+markdown_extensions:
+    - fenced_code

setup.py

@@ -4,7 +4,7 @@ from setuptools import find_packages, setup
 
 setup(
     name='django-mfa2',
-    version='1.0.4',
+    version='1.3.0',
     description='Allows user to add 2FA to their accounts',
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",
@@ -12,7 +12,6 @@ setup(
     author='Mohamed El-Kalioby',
     author_email = 'mkalioby@mkalioby.com',
     url = 'https://github.com/mkalioby/django-mfa2/',
-    long_description=open('README.md').read(),
     download_url='https://github.com/mkalioby/django-mfa2/',
     license='MIT',
     packages=find_packages(),
@@ -25,7 +24,7 @@ setup(
         'ua-parser',
         'user-agents',
         'python-jose',
-        'fido2 == 0.5',
+        'fido2 == 0.6',
         'jsonLookup'
       ],
     python_requires=">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*",
@@ -52,5 +51,5 @@ setup(
         "Programming Language :: Python :: 3.5",
         "Programming Language :: Python :: 3.6",
         "Topic :: Software Development :: Libraries :: Python Modules",
-],
+]
 )