django-allauth-webauthn 0.2.3

Webauthn-based two-factor authentication for Django allauth

Welcome to django-allauth-webauthn!

django-allauth-webauthn adds two-factor authentication by using the webauthn standard to django-allauth. django-allauth is a set of Django applications which help with authentication, registration, and other account management tasks.

Using the webauthn standard for the second authentication factor allows for a variety of authentication schemes on the client side. The user may authenticate by using a roaming hardware token (e.g. a USB key or Bluetooth Low Energy device) or the operating system may provide the authentication functionality (e.g. Windows Hello).

django-allauth-webauthn does not implement the webauthn standard to allow for password-less logins. It allows to authenticate a user after the usual login scheme against a pre-registered security token. The user may pre-register an arbitrary amount of tokens.

Source code

http://github.com/cyberdeck/django-allauth-webauthn

Documentation

https://django-allauth-webauthn.readthedocs.io/

Main Feature

Adds webauthn-based two-factor authentication views and workflow to django-allauth.

Compatibility

django-allauth-webauthn was actively developed against django-allauth 0.45 using Django 3.2 and Python 3.8.

However, it includes exceptional testing aiming for 100% coverage and thus, you may test it easily against your version requirements. If you need to patch it due to compatibility reasons I would love to see you contributing a pull request.

Where does it come from?

django-allauth-webauthn was created from scratch but it borrows a lot of ingredients from django-allauth-2fa and django-webauthin. Both packages are exceptionally useful but does not included the feature to allow for a webauthn-based two-factor authentication out of the box.

Contributing

django-allauth-webauthn was initially developed by H. Gregor Molter due to the lack of other suitable webauthn-based two-factor authentication packages. Please feel free to contribute if you find django-allauth-webauthn useful!

1. Check for open issues or open a new issue to start a discussion around a bug or your special feature request.

2. For the repository on GitHub and start to develop on the master branch or a custom branch derived from the master branch.

3. Write one or multiple test(s) to allow for validation that the bug was fixed or that your special feature works as expected without any negative impact on the behavior of the other functionality.

4. Before submitting your patch please thoroughly check your contribution by executing the pre-commit script.

5. Send a pull request to get your changes merged and published.

Developing

django-allauth-webauthn make heavy use of the poetry Python packaging and dependency manager and the pre-commit framework.

After you forked (and branched) django-allauth-webauthn please install all development dependencies with poetry:

$ poetry install

poetry will install all needed development dependencies in a virtual environment for you. Afterwards install the pre-commit hooks by running:

$ poetry run pre-commit install

The pre-commit hooks will be executed automatically prior committing to the Git repository. There are hooks for source code styling (e.g. import reordering) and it is ensured that all tests may be executed successfully and that no obvious type checking issues are included.

To execute these hooks manually (i.e. without performing a commit) execute the following:

$ poetry run pre-commit run --all-files

Testing

Tests can be run using the standard Django testing facility by executing:

$ poetry run python manage.py test

Coverage

During test execution a coverage report can be created with:

$ poetry run coverage run manage.py test

To view the coverage report on the command line you have to execute:

$ poetry run coverage report -m

or you can generate an HTML report for more eye candy:

$ poetry run coverage html

The resulting HTML report will be stored in the coverage_html folder.

Demo Project

A simple demo Django project is included within the demo folder and may be run by:

$ cd demo
# Migrate the demo database first (only needed once)
$ poetry run python manage.py migrate
# Run the SSL demo server (a self-signed certificate and private key is created during first run)
$ poetry run python manage.py runserver_plus --cert test.crt

Note

The webauthn technology requires you to run your test server over https. Otherwise the registration of security tokens or authentication cannot be executed successfully. Some browser are a little bit piggy about self-signed certificates on 127.0.0.1. Please use at least https://localhost:8000/ to access the demo server and consult the web about your browser’s behavior before submitting an issue!

The demo app allows you to register security tokens to a logged in user. If a user has at least a single security token registered, she will be asked to authenticate with this token during sign in. Security tokens may be renamed or deleted. All in one, it demonstrates the basic workflow for webauthn-based two-factor authentication.

Note

If you do not have a security token at hand or if you hesitate to use your super-secret token during development, you may emulate authenticators with the Chrome browser.