MFA using an Authenticator app

.github/workflows/tests.yaml

@@ -21,6 +21,8 @@ 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
+
             - name: Lint
               run: ./scripts/lint.sh
 
@@ -59,6 +61,7 @@ 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
             - name: Test with pytest, Postgres
               run: ./scripts/test-postgres.sh
               env:
@@ -86,6 +89,7 @@ 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
             - 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/index.rst

@@ -35,6 +35,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/index.rst

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

docs/source/mfa/introduction.rst

@@ -0,0 +1,13 @@
+Introduction
+============
+
+What is Multi-Factor Authentication (MFA)?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+MFA provides additional security to :ref:`SessionAuth`.
+
+As well as needing a username and password to login, the user must provide an
+additional piece of information.
+
+One of the most popular ways of doing this is by providing a code generated by
+an authenticator app on the user's phone.

docs/source/mfa/providers.rst

@@ -0,0 +1,23 @@
+Providers
+=========
+
+Most of the MFA code is fairly generic, but ``Providers`` implement the logic
+which is specific to its particular authentication mechanism.
+
+For example, ``AuthenticatorProvider`` knows how to authenticate tokens which
+come from an authenticator app on a user's phone, and knows how to generate new
+secrets which allow users to enable MFA.
+
+.. currentmodule:: piccolo_api.mfa.provider
+
+``MFAProvider``
+---------------
+
+.. autoclass:: MFAProvider
+
+.. currentmodule:: piccolo_api.mfa.authenticator.provider
+
+``AuthenticatorProvider``
+-------------------------
+
+.. autoclass:: AuthenticatorProvider

docs/source/mfa/tables.rst

@@ -0,0 +1,35 @@
+Tables
+======
+
+``AuthenticatorSecret``
+-----------------------
+
+This is required by :class:`AuthenticatorProvider <piccolo_api.mfa.authenticator.provider.AuthenticatorProvider>`.
+
+To create this table, you can using Piccolo's migrations.
+
+Add ``piccolo_api.mfa.authenticator.piccolo_app`` to ``APP_REGISTRY`` in
+``piccolo_conf.py``:
+
+.. code-block:: python
+
+    APP_REGISTRY = AppRegistry(
+        apps=[
+            "piccolo_api.mfa.authenticator.piccolo_app",
+            ...
+        ]
+    )
+
+Then run the migrations:
+
+.. code-block:: bash
+
+    piccolo migrations forwards mfa_authenticator
+
+Alternatively, if not using Piccolo migrations, you can create the table
+manually:
+
+.. code-block:: pycon
+
+    >>> from piccolo_api.mfa.authenticator.table import AuthenticatorProvider
+    >>> AuthenticatorProvider.create_table().run_sync()

e2e/conftest.py

@@ -0,0 +1,62 @@
+import os
+import time
+from http.client import HTTPConnection
+from subprocess import Popen
+
+import pytest
+
+HOST = "localhost"
+PORT = 8000
+BASE_URL = f"http://{HOST}:{PORT}"
+
+
+@pytest.fixture
+def browser_context_args():
+    return {"record_video_dir": "videos/"}
+
+
+@pytest.fixture
+def context(context):
+    # We don't need a really long timeout.
+    # The timeout determines how long Playwright waits for a HTML element to
+    # become available.
+    # By default it's 30 seconds, which is way too long when testing an app
+    # locally.
+    context.set_default_timeout(10000)
+    yield context
+
+
+@pytest.fixture
+def mfa_app():
+    """
+    Running dev server and Playwright test in parallel.
+    More info https://til.simonwillison.net/pytest/playwright-pytest
+    """
+    path = os.path.join(
+        os.path.dirname(os.path.dirname(__file__)),
+        "example_projects",
+        "mfa_demo",
+    )
+
+    process = Popen(
+        ["python", "-m", "main", "--reset-db"],
+        cwd=path,
+    )
+    retries = 5
+    while retries > 0:
+        conn = HTTPConnection(f"{HOST}:{PORT}")
+        try:
+            conn.request("HEAD", "/")
+            response = conn.getresponse()
+            if response is not None:
+                yield process
+                break
+        except ConnectionRefusedError:
+            time.sleep(1)
+            retries -= 1
+
+    if not retries:
+        raise RuntimeError("Failed to start http server")
+    else:
+        process.terminate()
+        process.wait()

e2e/pages.py

@@ -0,0 +1,66 @@
+"""
+By using pages we can make out test more scalable.
+
+https://playwright.dev/docs/pom
+"""
+
+from playwright.sync_api import Page
+
+USERNAME = "piccolo"
+PASSWORD = "piccolo123"
+
+
+class LoginPage:
+    url = "http://localhost:8000/login/"
+
+    def __init__(self, page: Page):
+        self.page = page
+        self.username_input = page.locator('input[name="username"]')
+        self.password_input = page.locator('input[name="password"]')
+        self.button = page.locator("button")
+
+    def reset(self):
+        self.page.goto(self.url)
+
+    def login(self, username: str = USERNAME, password: str = PASSWORD):
+        self.username_input.fill(username)
+        self.password_input.fill(password)
+        self.button.click()
+
+
+class RegisterPage:
+    url = "http://localhost:8000/register/"
+
+    def __init__(self, page: Page):
+        self.page = page
+        self.username_input = page.locator("[name=username]")
+        self.email_input = page.locator("[name=email]")
+        self.password_input = page.locator("[name=password]")
+        self.confirm_password_input = page.locator("[name=confirm_password]")
+        self.button = page.locator("button")
+
+    def reset(self):
+        self.page.goto(self.url)
+
+    def login(self, username: str = USERNAME, password: str = PASSWORD):
+        self.username_input.fill(username)
+        self.email_input.fill("[email protected]")
+        self.password_input.fill(password)
+        self.confirm_password_input.fill(password)
+        self.button.click()
+
+
+class MFASetupPage:
+    url = "http://localhost:8000/private/mfa-setup/"
+
+    def __init__(self, page: Page):
+        self.page = page
+        self.password_input = page.locator("[name=password]")
+        self.button = page.locator("button")
+
+    def reset(self):
+        self.page.goto(self.url)
+
+    def register(self, password: str = PASSWORD):
+        self.password_input.fill(password)
+        self.button.click()

e2e/test_mfa.py

@@ -0,0 +1,29 @@
+from playwright.async_api import Page
+
+from .pages import LoginPage, MFASetupPage, RegisterPage
+
+
+def test_mfa_signup(page: Page, mfa_app):
+    """
+    Make sure we create an account and sign up for MFA.
+    """
+    register_page = RegisterPage(page=page)
+    register_page.reset()
+    register_page.login()
+
+    login_page = LoginPage(page=page)
+    login_page.reset()
+    login_page.login()
+
+    mfa_setup_page = MFASetupPage(page=page)
+    mfa_setup_page.reset()
+
+    # Test an incorrect password
+    # TODO - assert response code is correct
+    mfa_setup_page.register(password="fake_password_123")
+
+    # Test the correct password
+    # TODO - make sure it navigated to the right page
+    mfa_setup_page.register()
+
+    mfa_setup_page.reset()

example_projects/mfa_demo/README.md

@@ -0,0 +1,28 @@
+# MFA demo
+
+This project demos how to use the MFA with the `session_login` endpoint.
+
+## Setup
+
+### Install requirements
+
+```bash
+pip install -r requirements.txt
+```
+
+### Create database
+
+Make sure a Postgres database exists, called 'piccolo_api_mfa'. See
+`piccolo_conf.py` for the full details.
+
+### Run migrations
+
+```
+piccolo migrations forwards all
+```
+
+## Run the app
+
+```bash
+python main.py
+```