# django-mfa2
A Django app that handles MFA, it supports TOTP, U2F, FIDO2 U2F (Web Authn), Email Tokens , Trusted Devices and backup codes.
[](https://fidoalliance.org/passkeys/)
[](https://github.com/psf/black)
[](https://pyre-check.org/)
### Pip Stats
[](https://badge.fury.io/py/django-mfa2)
[](https://pepy.tech/project/django-mfa2)
### Conda Stats
[](https://anaconda.org/conda-forge/django-mfa2)
[](https://anaconda.org/conda-forge/django-mfa2)
[](https://anaconda.org/conda-forge/django-mfa2)
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](https://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](https://github.com/mkalioby/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
1. using pip
* For Django >= 4.0
`pip install django-mfa2`
* For Django < 4.0
`pip install django-mfa2 jsonfield`
2. 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](https://github.com/swainn) for adding package to conda-forge
# Usage
1. in your settings.py add the application to your installed apps
```python
INSTALLED_APPS=(
'......',
'mfa',
'......')
```
2. Collect Static Files
`python manage.py collectstatic`
3. Add the following settings to your file
```python
from django.conf.global_settings import PASSWORD_HASHERS as DEFAULT_PASSWORD_HASHERS #Preferably at the same place where you import your other modules
MFA_UNALLOWED_METHODS=() # Methods that shouldn't be allowed for the user e.g ('TOTP','U2F',)
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_REDIRECT_AFTER_REGISTRATION="mfa_home" # Allows Changing the page after successful registeration
MFA_SUCCESS_REGISTRATION_MSG = "Go to Security Home" # The text of the link
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_ALWAYS_GO_TO_LAST_METHOD = False # Always redirect the user to the last method used to save a click (Added in 2.6.0).
MFA_RENAME_METHODS={} #Rename the methods in a more user-friendly way e.g {"RECOVERY":"Backup Codes"} (Added in 2.6.0)
MFA_HIDE_DISABLE=('FIDO2',) # Can the user disable his key (Added in 1.2.0).
MFA_OWNED_BY_ENTERPRISE = FALSE # Who owns security keys
PASSWORD_HASHERS = DEFAULT_PASSWORD_HASHERS # Comment if PASSWORD_HASHER already set in your settings.py
PASSWORD_HASHERS += ['mfa.recovery.Hash']
RECOVERY_ITERATION = 350000 #Number of iteration for recovery code, higher is more secure, but uses more resources for generation and check...
TOKEN_ISSUER_NAME="PROJECT_NAME" #TOTP Issuer name
U2F_APPID="https://localhost" #URL For U2F
FIDO_SERVER_ID=u"localehost" # Server rp id for FIDO2, it is the full domain of your project
FIDO_SERVER_NAME=u"PROJECT_NAME"
```
**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`
Start version 2.6.0
* Added: `MFA_ALWAYS_GO_TO_LAST_METHOD`, `MFA_RENAME_METHODS`, `MFA_ENFORCE_RECOVERY_METHOD` & `RECOVERY_ITERATION`
4. 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
```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
```
5. 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
'....',
]
```
6. 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`.
7. 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`
8. 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
```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
}
````
# Contributors
* [mahmoodnasr](https://github.com/mahmoodnasr)
* [d3cline](https://github.com/d3cline)
* [swainn](https://github.com/swainn)
* [unramk](https://github.com/unramk)
* [willingham](https://github.com/willingham)
* [AndreasDickow](https://github.com/AndreasDickow)
* [mnelson4](https://github.com/mnelson4)
* [ezrajrice](https://github.com/ezrajrice)
* [Spitfireap](https://github.com/Spitfireap)
* [peterthomassen](https://github.com/peterthomassen)
# Security contact information
To report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.
Raw data
{
"_id": null,
"home_page": "https://github.com/mkalioby/django-mfa2/",
"name": "django-mfa2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": null,
"author": "Mohamed El-Kalioby",
"author_email": "mkalioby@mkalioby.com",
"download_url": "https://files.pythonhosted.org/packages/66/8b/fec4a96cdca7a04a923fe69ce953167cb167af245ba4c5aa61059ee78739/django-mfa2-2.9.0.tar.gz",
"platform": null,
"description": "# django-mfa2\nA Django app that handles MFA, it supports TOTP, U2F, FIDO2 U2F (Web Authn), Email Tokens , Trusted Devices and backup codes.\n\n[](https://fidoalliance.org/passkeys/)\n\n[](https://github.com/psf/black)\n[](https://pyre-check.org/)\n### Pip Stats\n[](https://badge.fury.io/py/django-mfa2)\n[](https://pepy.tech/project/django-mfa2)\n\n### Conda Stats\n[](https://anaconda.org/conda-forge/django-mfa2) \n[](https://anaconda.org/conda-forge/django-mfa2) \n[](https://anaconda.org/conda-forge/django-mfa2) \n\nWeb Authencation API (WebAuthn) is state-of-the art techology that is expected to replace passwords.\n\n\n\nFor FIDO2, the following are supported\n * **security keys** (Firefox 60+, Chrome 67+, Edge 18+, Safari 13 on Mac OS, Chrome on Andriod, Safari on iOS 13.3+),\n * **Windows Hello** (Firefox 67+, Chrome 72+ , Edge),\n * **Apple's Touch ID/Face ID** (Chrome 70+ on Mac OS X, Safari on macOS Big Sur, Safari on iOS 14.0+ ),\n * **android-safetynet** (Chrome 70+, Firefox 68+)\n * **NFC devices using PCSC** (Not Tested, but as supported in fido2)\n * **Soft Tokens** \n * ~~[krypt.co](https://krypt.co/): Login by a notification on your phone.~~\n\n**Update**: Dec 2022, krypt.co has been killed by Google for Passkeys.\n\nIn 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.\n\nTrusted device is a mode for the user to add a device that doesn't support security keys like Android without fingerprints or NFC.\n\n**Note**: `U2F and FIDO2 can only be served under secure context (https)`\n\nPackage 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.\n\nIf you just need WebAuthn and Passkeys, you can use **[django-passkeys](https://github.com/mkalioby/django-passkeys)**, which is a slim-down of this app and much easier to integrate.\n\nDepends on\n\n* pyotp\n* python-u2flib-server\n* ua-parser\n* user-agents\n* python-jose\n* fido2==1.0.0\n\n# Installation\n1. using pip \n * For Django >= 4.0\n \n `pip install django-mfa2`\n * For Django < 4.0\n \n `pip install django-mfa2 jsonfield`\n2. Using Conda forge \n \n `conda config --add channels conda-forge`\n \n `conda install django-mfa2`\n \n For more info, see the conda-forge repo (https://github.com/conda-forge/django-mfa2-feedstock)\n \n Thanks for [swainn](https://github.com/swainn) for adding package to conda-forge\n\n# Usage\n1. in your settings.py add the application to your installed apps\n ```python\n INSTALLED_APPS=(\n '......',\n 'mfa',\n '......')\n ```\n2. Collect Static Files\n`python manage.py collectstatic`\n3. Add the following settings to your file\n\n ```python\n from django.conf.global_settings import PASSWORD_HASHERS as DEFAULT_PASSWORD_HASHERS #Preferably at the same place where you import your other modules\n MFA_UNALLOWED_METHODS=() # Methods that shouldn't be allowed for the user e.g ('TOTP','U2F',)\n MFA_LOGIN_CALLBACK=\"\" # A function that should be called by username to login the user in session\n MFA_RECHECK=True # Allow random rechecking of the user\n MFA_REDIRECT_AFTER_REGISTRATION=\"mfa_home\" # Allows Changing the page after successful registeration\n MFA_SUCCESS_REGISTRATION_MSG = \"Go to Security Home\" # The text of the link\n MFA_RECHECK_MIN=10 # Minimum interval in seconds\n MFA_RECHECK_MAX=30 # Maximum in seconds\n MFA_QUICKLOGIN=True # Allow quick login for returning users by provide only their 2FA\n MFA_ALWAYS_GO_TO_LAST_METHOD = False # Always redirect the user to the last method used to save a click (Added in 2.6.0).\n MFA_RENAME_METHODS={} #Rename the methods in a more user-friendly way e.g {\"RECOVERY\":\"Backup Codes\"} (Added in 2.6.0)\n MFA_HIDE_DISABLE=('FIDO2',) # Can the user disable his key (Added in 1.2.0).\n MFA_OWNED_BY_ENTERPRISE = FALSE # Who owns security keys \n PASSWORD_HASHERS = DEFAULT_PASSWORD_HASHERS # Comment if PASSWORD_HASHER already set in your settings.py\n PASSWORD_HASHERS += ['mfa.recovery.Hash'] \n RECOVERY_ITERATION = 350000 #Number of iteration for recovery code, higher is more secure, but uses more resources for generation and check...\n\n TOKEN_ISSUER_NAME=\"PROJECT_NAME\" #TOTP Issuer name\n\n U2F_APPID=\"https://localhost\" #URL For U2F\n FIDO_SERVER_ID=u\"localehost\" # Server rp id for FIDO2, it is the full domain of your project\n FIDO_SERVER_NAME=u\"PROJECT_NAME\"\n ```\n **Method Names**\n * U2F\n * FIDO2\n * TOTP\n * Trusted_Devices\n * Email\n * RECOVERY\n \n **Notes**:\n * Starting version 1.1, ~~FIDO_LOGIN_URL~~ isn't required for FIDO2 anymore.\n * Starting version 1.7.0, Key owners can be specified.\n * Starting version 2.2.0\n * Added: `MFA_SUCCESS_REGISTRATION_MSG` & `MFA_REDIRECT_AFTER_REGISTRATION`\n Start version 2.6.0\n * Added: `MFA_ALWAYS_GO_TO_LAST_METHOD`, `MFA_RENAME_METHODS`, `MFA_ENFORCE_RECOVERY_METHOD` & `RECOVERY_ITERATION`\n4. Break your login function\n\n 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\n \n * authenticate the user\n * if username and password are correct , check if the user has mfa or not\n * if user has mfa then redirect to mfa page\n * if user doesn't have mfa then call your function to create the user session\n\n ```python\n def login(request): # this function handles the login form POST\n user = auth.authenticate(username=username, password=password) \n if user is not None: # if the user object exist\n from mfa.helpers import has_mfa\n res = has_mfa(username = username,request=request) # has_mfa returns false or HttpResponseRedirect\n if res:\n return res\n return log_user_in(request,username=user.username) \n #log_user_in is a function that handles creatung user session, it should be in the setting file as MFA_CALLBACK\n ```\n5. Add mfa to urls.py\n ```python \n import mfa\n import mfa.TrustedDevice\n urls_patterns= [\n '...',\n url(r'^mfa/', include('mfa.urls')),\n url(r'devices/add$', mfa.TrustedDevice.add,name=\"mfa_add_new_trusted_device\"), # This short link to add new trusted device\n '....',\n ]\n ```\n6. 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.\n 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`.\n7. 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.\n **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`\n8. Somewhere in your app, add a link to 'mfa_home'\n```<li><a href=\"{% url 'mfa_home' %}\">Security</a> </li>```\n\n\nFor Example, See 'example' app and look at EXAMPLE.md to see how to set it up.\n\n# Going Passwordless\n\nTo be able to go passwordless for returning users, create a cookie named 'base_username' containing username as shown in snippet below\n```python\n response = render(request, 'Dashboard.html', context))\n if request.session.get(\"mfa\",{}).get(\"verified\",False) and getattr(settings,\"MFA_QUICKLOGIN\",False):\n if request.session[\"mfa\"][\"method\"]!=\"Trusted Device\":\n response.set_cookie(\"base_username\", request.user.username, path=\"/\",max_age = 15*24*60*60)\n return response\n```\n\nSecond, update the GET part of your login view\n```python\n if \"mfa\" in settings.INSTALLED_APPS and getattr(settings,\"MFA_QUICKLOGIN\",False) and request.COOKIES.get('base_username'):\n username=request.COOKIES.get('base_username')\n from mfa.helpers import has_mfa\n res = has_mfa(username = username,request=request,)\n if res: return res\n ## continue and return the form.\n```\n# Checking MFA on Client Side\n\nSometimes you like to verify that the user is still there so simple you can ask django-mfa2 to check that for you\n\n```html\n {% include 'mfa_check.html' %}\n```\n````js\nfunction success_func() {\n //logic if mfa check succeeds\n}\nfunction fail_func() {\n //logic if mfa check fails\n}\nfunction some_func() {\n recheck_mfa(success_func,fail_func,MUST_BE_MFA)\n //MUST_BE_MFA true or false, if the user must has with MFA\n }\n\n````\n\n# Contributors\n* [mahmoodnasr](https://github.com/mahmoodnasr)\n* [d3cline](https://github.com/d3cline)\n* [swainn](https://github.com/swainn)\n* [unramk](https://github.com/unramk)\n* [willingham](https://github.com/willingham)\n* [AndreasDickow](https://github.com/AndreasDickow)\n* [mnelson4](https://github.com/mnelson4)\n* [ezrajrice](https://github.com/ezrajrice)\n* [Spitfireap](https://github.com/Spitfireap)\n* [peterthomassen](https://github.com/peterthomassen)\n\n\n # Security contact information\nTo report a security vulnerability, please use the [Tidelift security contact](https://tidelift.com/security). Tidelift will coordinate the fix and disclosure.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Allows user to add 2FA to their accounts",
"version": "2.9.0",
"project_urls": {
"Download": "https://github.com/mkalioby/django-mfa2/",
"Homepage": "https://github.com/mkalioby/django-mfa2/"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "668bfec4a96cdca7a04a923fe69ce953167cb167af245ba4c5aa61059ee78739",
"md5": "18601267fe12c2235866580adf3db17c",
"sha256": "39745afc81f1ab696ae4890b1d626d3b0c4580526c722aca5d1c11ab6d07bf33"
},
"downloads": -1,
"filename": "django-mfa2-2.9.0.tar.gz",
"has_sig": false,
"md5_digest": "18601267fe12c2235866580adf3db17c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 83359,
"upload_time": "2024-05-27T05:54:00",
"upload_time_iso_8601": "2024-05-27T05:54:00.921307Z",
"url": "https://files.pythonhosted.org/packages/66/8b/fec4a96cdca7a04a923fe69ce953167cb167af245ba4c5aa61059ee78739/django-mfa2-2.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-27 05:54:00",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mkalioby",
"github_project": "django-mfa2",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "django",
"specs": [
[
">=",
"2.2"
]
]
},
{
"name": "simplejson",
"specs": []
},
{
"name": "pyotp",
"specs": []
},
{
"name": "python-u2flib-server",
"specs": []
},
{
"name": "ua-parser",
"specs": []
},
{
"name": "user-agents",
"specs": []
},
{
"name": "python-jose",
"specs": []
},
{
"name": "fido2",
"specs": [
[
"<",
"2.0"
],
[
">",
"1.1.0"
]
]
},
{
"name": "jsonLookup",
"specs": []
},
{
"name": "raven",
"specs": []
},
{
"name": "pyre-check",
"specs": []
}
],
"lcname": "django-mfa2"
}
JSON
