MFA using an Authenticator app (#292)

* MFA prototype

* add mfa_providers abstract property

* flesh out email provider a bit more

* wip

* flesh out email some more, and add authenticator

* flesh out `AuthenticatorSeed` some more

* add method for fetching pyotp

* add `pyotp` to requirements

* add proper auth methods for pyotp

* start adding tests

* bump minimum Piccolo version

* test `create_new` method

* add qrcode logic from @sinisaos PR

* flesh out auth methods

* lazy load `qrcode`

* fleshing out logic some more in session login endpoint

* change imports

* make error messages consistent

* add TODO

* adding example app for testing

* add `AuthenticatorProvider` to example app

* added `get_registration_html` to provider

* rename `seed_table` to `secret_table`

* change params in `send_code` for authenticator

* Create README.md

* add `issuer_name` to `AuthenticatorProvider`

* fix typo in docstring

* add `get_registration_json`

* add `get_registration_json` to base class

* try embedding QR code image in HTML response

* flesh out `MFARegisterEndpoint` endpoint

* add todo about primary key

* fix bugs in register endpoint

* fix error - was returning html instead of json

* show MFA code input on login page

* Update README.md

* Update tests.yaml

* fix some linter errors

* add `device_name` column to `AuthenticatorSecret`

* make sure each provider has a custom token name

* make each MFA Provider have a unique token name

This means we can potentially put several MFA providers on the login page

* If the user reused a code make sure auth fails (could be a replay attack)

* add auth test for replay attacks

* add `generate_recovery_code`

* store recovery codes, and return recovery codes in endpoints (taken from @sinisaos example)

* make sure recovery codes can be used to login

* ignore mypy warnings for now

* install pyotp in CI

* endpoint test WIP

* update `TestMFARegisterEndpoint`

* remove todo

* encrypt secret in db

* use a proper template for MFA sign up

* add links for where to download the authenticator app, and add JS for copying to clipboard

* also test HTML register endpoint

* add playwright tests

* require a password to enable MFA

* fix test

* create separate template for cancelling MFA

* initial docs

* improve docs for AuthenticatorProvider  params

* add docs for tables

* rename `mfa_register_endpoint` to `mfa_setup`

So the name is more consistent with other endpoints in `piccolo_api`

* improve docs, and rename from register to setup

* remove debugging

* improve template when MFA is disabled

* add re-enabled link on disabled template

* fix linter errors

* use `self._auth_table`

* render cancel template in GET endpoint if user is already enrolled

* remove email for now

* remove email from README

* start moving encryption into its own file

* update code to use encryption provider

* improve the docstring for `mfa_setup` - mention rate limiting

* improve docstrings

* add params to docstrings

* remove `device_name` - not currently used

* change `revoke_all` to `revoke`

The current design assumes a single device per user

* add `XChaCha20Provider`

* make sure pynacl is installed in tests

* make sure pynacl is installed in tests (continued)

* improve coverage

* add `TestRevoke`

* add a test to make sure auth works

* remove unused import

* add tests for recovery codes

* remove breakpoint

* fix bug with prefix

* simplify encoding

* changed login logic for multiple MFA providers

* make `mfa_provider_name` param optional if there's only a single MFA provider

* add `help_text` to `revoked_at`

* add `valid_window` argument to `AuthenticatorProvider`

* tell the user whether we sent them a code

* increase coverage for `AuthenticatorSecret`

* remove TODO in endpoint test

* add tests for generating recovery codes

* fix path to `AuthenticatorProvider` in docstring

* add docs for encryption

* remove imports

* add docstring and type annotations to `get_b64encoded_qr_image`

Author: dantownsend

.github/workflows/tests.yaml

@@ -21,6 +21,9 @@ jobs:
                   pip install -r requirements/requirements.txt
                   pip install -r requirements/dev-requirements.txt
                   pip install -r requirements/test-requirements.txt
+                  pip install -r requirements/extras/authenticator.txt
+                  pip install -r requirements/extras/pynacl.txt
+
             - name: Lint
               run: ./scripts/lint.sh
 
@@ -59,6 +62,8 @@ jobs:
                   python -m pip install --upgrade pip
                   pip install -r requirements/requirements.txt
                   pip install -r requirements/test-requirements.txt
+                  pip install -r requirements/extras/authenticator.txt
+                  pip install -r requirements/extras/pynacl.txt
             - name: Test with pytest, Postgres
               run: ./scripts/test-postgres.sh
               env:
@@ -86,6 +91,8 @@ jobs:
                   python -m pip install --upgrade pip
                   pip install -r requirements/requirements.txt
                   pip install -r requirements/test-requirements.txt
+                  pip install -r requirements/extras/authenticator.txt
+                  pip install -r requirements/extras/pynacl.txt
             - name: Test with pytest, SQLite
               run: ./scripts/test-sqlite.sh
             - name: Upload coverage

.gitignore

@@ -14,3 +14,6 @@ docs/source/_build/
 example_projects/token_auth/
 .env/
 .venv/
+
+# Playwright
+videos/

docs/source/encryption/index.rst

@@ -0,0 +1,8 @@
+Encryption
+==========
+
+.. toctree::
+    :maxdepth: 1
+
+    ./introduction
+    ./providers

docs/source/encryption/introduction.rst

@@ -0,0 +1,6 @@
+Introduction
+============
+
+Piccolo API provides some wrappers around popular encryption libraries.
+
+These are current used by :ref:`Multifactor Authentication <MFA>`.

docs/source/encryption/providers.rst

@@ -0,0 +1,69 @@
+Providers
+=========
+
+.. currentmodule:: piccolo_api.encryption.providers
+
+``EncryptionProvider``
+----------------------
+
+.. autoclass:: EncryptionProvider
+
+``FernetProvider``
+------------------
+
+.. autoclass:: FernetProvider
+
+``PlainTextProvider``
+---------------------
+
+.. autoclass:: PlainTextProvider
+
+``XChaCha20Provider``
+---------------------
+
+.. autoclass:: XChaCha20Provider
+
+-------------------------------------------------------------------------------
+
+Dependencies
+------------
+
+When first using some of the providers, you will be prompted to install the
+underlying encryption library.
+
+For example, with ``XChaCha20Provider``, you need to install ``pynacl`` as
+follows:
+
+.. code-block:: bash
+
+    pip install piccolo_api[pynacl]
+
+-------------------------------------------------------------------------------
+
+Example usage
+-------------
+
+All of the providers work the same (except their parameters may be different).
+
+Here's an example using ``XChaCha20Provider``:
+
+.. code-block:: python
+
+    >>> from piccolo_api.encryption.providers import XChaCha20Provider
+
+    >>> encryption_key = XChaCha20Provider.get_new_key()
+    >>> provider = XChaCha20Provider(encryption_key=encryption_key)
+
+    >>> encrypted = provider.encrypt("hello world")
+    >>> print(provider.decrypt(encrypted))
+    "hello world"
+
+-------------------------------------------------------------------------------
+
+Which provider to use?
+----------------------
+
+``XChaCha20Provider`` is the most secure.
+
+You may decide to use ``FernetProvider`` if you already have the Python
+``cryptography`` library as a dependency in your project.

docs/source/index.rst

@@ -26,6 +26,7 @@ ASGI app, covering authentication, security, and more.
 
    ./csp/index
    ./csrf/index
+   ./encryption/index
    ./rate_limiting/index
 
 .. toctree::
@@ -35,6 +36,7 @@ ASGI app, covering authentication, security, and more.
    ./which_authentication/index
    ./jwt/index
    ./session_auth/index
+   ./mfa/index
    ./token_auth/index
    ./register/index
    ./change_password/index

docs/source/mfa/endpoints.rst

@@ -0,0 +1,21 @@
+Endpoints
+=========
+
+You must mount these ASGI endpoints in your app.
+
+.. currentmodule:: piccolo_api.mfa.endpoints
+
+``mfa_setup``
+-------------------------
+
+.. autofunction:: mfa_setup
+
+.. image:: images/mfa_register_endpoint.jpg
+
+
+``session_login``
+-----------------
+
+Make sure you pass the ``mfa_providers`` argument to
+:func:`session_login <piccolo_api.session_auth.endpoints.session_login>`,
+so it knows to look for an MFA token.

docs/source/mfa/example.rst

@@ -0,0 +1,13 @@
+Full Example
+============
+
+Let's look at what an entire app looks like, which uses session auth, along
+with MFA (using the Authenticator provider).
+
+-------------------------------------------------------------------------------
+
+Starlette
+---------
+
+.. include:: ../../../example_projects/mfa_demo/app.py
+    :code: python

docs/source/mfa/images/mfa_register_endpoint.jpg

@@ -0,0 +1,13 @@
+..  _MFA:
+
+Multi-Factor Authentication
+===========================
+
+.. toctree::
+    :maxdepth: 1
+
+    ./introduction
+    ./endpoints
+    ./providers
+    ./tables
+    ./example