Add Python Flask MFA example application (#7)

* Add factor list via session

* Add SMS MFA workflow and routing

* Update enroll factor flow to include totp

* Add totp auth flow

* Finalize UI for both MFA types

* Run black to reformat app.py

* Update README for mfa app

Co-authored-by: Adam Wolfman <[email protected]>

Author: awolfden

python-flask-mfa-example/.gitignore

@@ -0,0 +1,129 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/

python-flask-mfa-example/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 WorkOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

python-flask-mfa-example/README.md

@@ -0,0 +1,114 @@
+# python-flask-mfa-example
+An example Flask application demonstrating how to use the [WorkOS MFA API](https://workos.com/docs/mfa/guide) using the [Python SDK](https://github.com/workos-inc/workos-python) to authenticate users.
+
+## Prerequisites
+- Python 3.6+
+
+
+## Flask Project Setup
+
+1. Clone the main git repo for these Python example apps using your preferred secure method (HTTPS or SSH).
+   ```bash
+   # HTTPS
+   $ git clone https://github.com/workos/python-flask-example-applications.git
+   ```
+
+   or
+
+   ```bash
+   # SSH
+   $ git clone [email protected]:workos/python-flask-example-applications.git
+   ```
+
+2. Navigate to the sso app within the cloned repo.
+   ```bash
+   $ cd python-flask-example-applications/python-flask-mfa-example
+   ```
+
+3. Create and source a Python virtual environment. You should then see `(env)` at the beginning of your command-line prompt.
+   ```bash
+   $ python3 -m venv env
+   $ source env/bin/activate
+   (env) $
+   ```
+
+4. Install the cloned app's dependencies.
+   ```bash
+   (env) $ pip install -r requirements.txt
+   ```
+
+5. Obtain and make note of the following values. In the next step, these will be set as environment variables.
+   - Your [WorkOS API key](https://dashboard.workos.com/api-keys)
+   - Your [SSO-specific, WorkOS Client ID](https://dashboard.workos.com/configuration)
+
+6. Ensure you're in the root directory for the example app, `python-flask-sso-example/`. Create a `.env` file to securely store the environment variables. Open this file with the Nano text editor. (This file is listed in this repo's `.gitignore` file, so your sensitive information will not be checked into version control.)
+   ```bash
+   (env) $ touch .env
+   (env) $ nano .env
+   ```
+
+7. Once the Nano text editor opens, you can directly edit the `.env` file by listing the environment variables:
+   ```bash
+   WORKOS_API_KEY=<value found in step 6>
+   WORKOS_CLIENT_ID=<value found in step 6>
+   APP_SECRET_KEY=<any string value you\'d like>
+   ```
+
+   To exit the Nano text editor, type `CTRL + x`. When prompted to "Save modified buffer", type `Y`, then press the `Enter` or `Return` key.
+
+8. Source the environment variables so they are accessible to the operating system.
+   ```bash
+   (env) $ source .env
+   ```
+
+   You can ensure the environment variables were set correctly by running the following commands. The output should match the corresponding values.
+   ```bash
+   (env) $ echo $WORKOS_API_KEY
+   (env) $ echo $WORKOS_CLIENT_ID
+   (env) $ echo $APP_SECRET_KEY
+   ```
+
+
+9. The final setup step is to start the server.
+   ```bash
+   (env) $ flask run
+   ```
+
+   If you are using Mac OS Monterey, port 5000 is not available and you'll need to start the app on a different port with this slightly different command. 
+   ```bash
+   (env) $ flask run -p 5001
+   ```
+
+   You'll know the server is running when you see no errors in the CLI, and output similar to the following is displayed:
+
+   ```bash
+   * Tip: There are .env or .flaskenv files present. Do "pip install python-dotenv" to use them.
+   * Environment: production
+   WARNING: This is a development server. Do not use it in a production deployment.
+   Use a production WSGI server instead.
+   * Debug mode: off
+   * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
+   ```
+
+   Navigate to `localhost:5000`, or `localhost:5001` depending on which port you launched the server, in your web browser. You should see a "Login" button. If you click this link, you'll be redirected to an HTTP `404` page because we haven't set up SSO yet!
+
+   You can stop the local Flask server for now by entering `CTRL + c` on the command line.
+
+
+## Using the MFA application
+
+11. This application is meant to showcase the MFA API and how to interact with it using the WorkOS Python SDK. It is not meant to show a real-life example of how MFA should be implemented. 
+
+   The app supports two types of MFA flows, SMS and Time-based One Time Password (TOTP). 
+
+   SMS: The SMS flow requires you to send a code via text message. You can customize this message, but the message must include the string "{{code}}". This string of characters tells the WorkOS API to generate a random code that will be populated automatically. If "{{code}}" is not included in the message, the authentication cannot be completed. 
+
+   TOTP: This type of authentication requires the use of a 3rd party authentication app (1Password, Authy, Google Authenticator, Microsoft Authenticator, Duo, etc). Scan the QR code from the Factor Details page to create the corresponding factor in the 3rd party app, then enter the time-based password when prompted in this MFA application.  
+
+   
+
+## Need help?
+
+First, make sure to reference the MFA docs at https://workos.com/docs/mfa/guide. 
+
+If you get stuck and aren't able to resolve the issue by reading our API reference or tutorials, you can reach out to us at [email protected] and we'll lend a hand.

python-flask-mfa-example/app.py

@@ -0,0 +1,127 @@
+import os
+from flask import Flask, session, redirect, render_template, request, url_for
+import json
+import workos
+
+
+# Flask Setup
+DEBUG = False
+app = Flask(__name__)
+app.secret_key = os.getenv("APP_SECRET_KEY")
+
+# WorkOS Setup
+
+workos.api_key = os.getenv("WORKOS_API_KEY")
+workos.project_id = os.getenv("WORKOS_CLIENT_ID")
+workos.base_api_url = "http://localhost:7000/" if DEBUG else workos.base_api_url
+
+
+@app.route("/")
+def home():
+    if session["factor_list"]:
+        return render_template("list_factors.html", factors=session["factor_list"])
+    return render_template(
+        "list_factors.html",
+    )
+
+
+@app.route("/enroll_factor_details", methods=["GET"])
+def enroll_factor_details():
+    return render_template("enroll_factor.html")
+
+
+@app.route("/enroll_factor", methods=["POST"])
+def enroll_factor():
+    factor_type = request.form.get("type")
+    totp_issuer = request.form.get("totp_issuer")
+    totp_user = request.form.get("totp_user")
+    phone_number = request.form.get("phone_number")
+
+    if factor_type == "sms":
+        factor_type = "sms"
+        new_factor = workos.client.mfa.enroll_factor(
+            type=factor_type, phone_number=phone_number
+        )
+
+    if factor_type == "totp":
+        factor_type = "totp"
+        new_factor = workos.client.mfa.enroll_factor(
+            type=factor_type, totp_issuer=totp_issuer, totp_user=totp_user
+        )
+
+    session["factor_list"].append(new_factor)
+    session.modified = True
+    return redirect("/")
+
+
+@app.route("/factor_detail")
+def factor_detail():
+    factorId = request.args.get("id")
+    for factor in session["factor_list"]:
+        if factor["id"] == factorId:
+            fullFactor = factor
+
+        phone_number = "-"
+        if factor["type"] == "sms":
+            phone_number = factor["sms"]["phone_number"]
+
+        if factor["type"] == "totp":
+            session["current_factor_qr"] = factor["totp"]["qr_code"]
+
+    session["current_factor"] = fullFactor["id"]
+    session["current_factor_type"] = fullFactor["type"]
+    session.modified = True
+    return render_template(
+        "factor_detail.html",
+        factor=fullFactor,
+        phone_number=phone_number,
+        qr_code=session["current_factor_qr"],
+    )
+
+
+@app.route("/challenge_factor", methods=["POST"])
+def challenge_factor():
+    if session["current_factor_type"] == "sms":
+        message = request.form["sms_message"]
+        session["sms_message"] = message
+
+        challenge = workos.client.mfa.challenge_factor(
+            authentication_factor_id=session["current_factor"],
+            sms_template=message,
+        )
+
+    if session["current_factor_type"] == "totp":
+        authentication_factor_id = session["current_factor"]
+        challenge = workos.client.mfa.challenge_factor(
+            authentication_factor_id=authentication_factor_id,
+        )
+
+    session["challenge_id"] = challenge["id"]
+    session.modified = True
+    return render_template("challenge_factor.html")
+
+
+@app.route("/verify_factor", methods=["POST"])
+def verify_factor():
+    code = request.form["code"]
+    challenge_id = session["challenge_id"]
+    verify_factor = workos.client.mfa.verify_factor(
+        authentication_challenge_id=challenge_id,
+        code=code,
+    )
+
+    return render_template(
+        "challenge_success.html",
+        challenge=verify_factor["challenge"],
+        valid=verify_factor["valid"],
+        type=session["current_factor_type"],
+    )
+
+
+@app.route("/clear_session", methods=["GET"])
+def clear_session():
+    session["factor_list"] = []
+    session["challenge_id"] = ""
+    session["current_factor"] = ""
+    session["current_factor_type"] = ""
+    return redirect("/")

python-flask-mfa-example/requirements.txt

@@ -0,0 +1,3 @@
+Flask==2.0.0
+workos==1.11.0
+python-dotenv