/django-two-factor-auth

Complete Two-Factor Authentication for Django providing the easiest integration into most Django projects.

Primary LanguagePythonMIT LicenseMIT

Django Two-Factor Authentication

Build Status Build Status Test Coverage PyPI

Complete Two-Factor Authentication for Django. Built on top of the one-time password framework django-otp and Django's built-in authentication framework django.contrib.auth for providing the easiest integration into most Django projects. Inspired by the user experience of Google's Two-Step Authentication, allowing users to authenticate through call, text messages (SMS), by using a token generator app like Google Authenticator or a YubiKey hardware token generator (optional).

If you run into problems, please file an issue on GitHub, or contribute to the project by forking the repository and sending some pull requests. The package is translated into English, Dutch and other languages. Please contribute your own language using Transifex.

Test drive this app through the online example app, hosted by Heroku. It demos most features except the Twilio integration. The example also includes django-user-sessions for providing Django sessions with a foreign key to the user. Although the package is optional, it improves account security control over django.contrib.sessions.

Compatible with modern Django versions. At the moment of writing that's including 2.2, 3.0, and 3.1 on Python 3.5, 3.6, 3.7 and 3.8. Documentation is available at readthedocs.org.

Installation

Refer to the installation instructions in the documentation.

Getting help

For general questions regarding this package, please hop over to Stack Overflow. If you think there is an issue with this package; check if the issue is already listed (either open or closed), and file an issue if it's not.

Contribute

  • Submit issues to the issue tracker on Github.
  • Fork the source code at Github.
  • Write some code and make sure it is covered with unit tests.
  • Send a pull request with your changes.
  • Provide a translation using Transifex.

Running tests

This project aims for full code-coverage, this means that your code should be well-tested. Also test branches for hardened code. You can run the full test suite with:

make test

Or run a specific test with:

make test TARGET=tests.tests.TwilioGatewayTest

For Python compatibility, tox is used. You can run the full test suite, covering all supported Python and Django version with:

tox

Releasing

The following actions are required to push a new version:

  • Update release notes

  • If any new translations strings were added, push the new source language to Transifex. Make sure translators have sufficient time to translate those new strings:

    make tx-push
    
  • Add migrations:

    python example/manage.py makemigrations two_factor
    git commit two_factor/migrations -m "Added migrations"
    
  • Update translations:

    make tx-pull
    
  • Package and upload:

    bumpversion [major|minor|patch]
    git push && git push --tags
    python setup.py sdist bdist_wheel
    twine upload dist/*
    

See Also

Have a look at django-user-sessions for Django sessions with a foreign key to the user. This package is also included in the online example app.

License

The project is licensed under the MIT license.