In this tutorial, you’ll learn how to build a simple website screenshot generator using Python and Flask. The app will let users enter any website URL and instantly get a screenshot of that page – all powered by a screenshot API.

You’ll use Flask, a lightweight web framework, to create a simple web interface and handle requests. Then, you’ll integrate an external API to capture website screenshots programmatically.

By the end of this tutorial, you’ll have learned how to:

• Build a basic Flask web app

• Accept user input through an HTML form

• Make HTTP requests to an external API

• Display images dynamically on a web page

This project is a great way to learn how APIs can extend the capabilities of your web applications, and how Python can easily handle tasks like image generation and display.

What we’ll cover:

• Prerequisites

• Setting Up the Project

• Integrating the ScreenshotBase API

• Adding Customization Options

• Wrapping Up

Prerequisites

Before we start building the app, make sure you have a few basics covered:

1. Python Installed

You’ll need Python 3.9 or higher installed on your machine. You can check your version by running:

python --version

If you don’t have it, you can download it from python.org/downloads.

2. Basic Knowledge of Python and Flask

You don’t need to be a Flask expert. Just have some familiarity with how to create routes and templates, and how to handle form data in Flask.

If you’re new to Flask, don’t worry – we’ll go step-by-step.

3. Screenshot API Key

We’ll be using the ScreenshotBase API to capture website screenshots. It provides a simple REST endpoint that takes a URL and returns a screenshot image.

You can get a free API key by signing up on their website. Once you have the key, keep it handy, as we’ll use it when we integrate the API in the later steps.

4. A Code Editor and Terminal

You can use any editor you prefer, like VS Code, PyCharm, or even a simple text editor. Make sure your terminal or command prompt can run Python commands and install packages using pip.

Setting Up the Project

Let’s start by setting up a new Flask project from scratch.

Step 1: Create a New Folder

Create a new folder for your project. You can name it screenshot-generator:

mkdir screenshot-generator
cd screenshot-generator

Step 2: Create a Virtual Environment

A virtual environment helps keep your project dependencies isolated from other Python projects.

Run the following commands:

python -m venv venv

Then activate it:

• On macOS/Linux:

    source venv/bin/activate
  

• On Windows:

    venv\Scripts\activate
  

Once activated, you should see (venv) at the beginning of your terminal prompt.

Step 3: Install Dependencies

We’ll need two packages for this project:

• Flask for building the web app

• Requests for making API calls to ScreenshotBase

Install them using pip:

pip install flask requests

Step 4: Set Up the Project Structure

Inside your project folder, create the following files and folders:

screenshot-generator/
├── app.py
├── templates/
│   └── index.html
└── static/

Here’s what each part does:

• app.py: main Python file that runs your Flask app

• templates/: stores HTML templates

• static/: stores images, CSS, and JavaScript files

Step 5: Add a Basic Flask App

Open app.py and add the following starter code:

from flask import Flask, render_template, request
import requests
import os

app = Flask(__name__)
API_KEY = os.getenv("SCREENSHOTBASE_API_KEY")
SCREENSHOTBASE_BASE_ENDPOINT = "https://api.screenshotbase.com/v1/take"

@app.route('/', methods=['GET', 'POST'])
def home():
    if request.method == 'POST':
        url = request.form.get('url')
        # Placeholder: We’ll add the API call here in the next section
        return render_template('index.html', url=url)
    return render_template('index.html')

if __name__ == '__main__':
    app.run(debug=True)

This sets up a minimal Flask application with one route (/). We’ll add the ScreenshotBase API call in the next section.

Step 6: Create a Simple HTML Template

Now that we’ve written the Flask backend to handle the screenshot request, let’s create the frontend for our app.

Inside your project folder, create a new directory named templates, and within it, add a file called index.html. Flask will automatically look for templates in this folder.

Here’s how the template should look:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Website Screenshot Generator</title>
    <link
      href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.8/dist/css/bootstrap.min.css"
      rel="stylesheet"
      integrity="sha384-sRIl4kxILFvY47J16cr9ZwB07vP4J8+LH7qKQnuqkuIAvNWLzeN8tE5YBujZqJLB"
      crossorigin="anonymous"
    />
    <style>
        body {
            padding-top: 2rem;
        }
        .screenshot-container {
            max-height: 80vh;
            overflow-y: auto;
            border: 1px solid #ddd;
            border-radius: 8px;
            padding: 1rem;
            background: #f8f9fa;
        }
    </style>
</head>
<body>
    <div class="container text-center">
        <h1 class="mb-4">Website Screenshot Generator</h1>
        <form method="POST" class="d-flex justify-content-center mb-4">
            <input 
                type="text" 
                name="url" 
                placeholder="Enter website URL" 
                class="form-control w-50 me-2"
                required
            >
            <button type="submit" class="btn btn-primary">Capture Screenshot</button>
        </form>

        {% if screenshot %}
            <h4>Screenshot Preview:</h4>
            <div class="screenshot-container mx-auto">
                <img src="{{ screenshot }}" alt="Website Screenshot" class="img-fluid rounded shadow">
            </div>
        {% elif request.method == 'POST' %}
            <div class="alert alert-danger mt-3">
                Sorry, something went wrong while capturing the screenshot. Please try again.
            </div>
        {% endif %}
    </div>
</body>
</html>

This HTML template uses Bootstrap to keep the design clean and responsive without much custom styling. The form at the top allows users to enter any website URL and submit it to the Flask app using the POST method. Once the app retrieves the screenshot URL from the API, it dynamically renders the image on the page.

The img-fluid class from Bootstrap ensures the screenshot scales properly across all screen sizes while maintaining its aspect ratio. Also, the .screenshot-container provides a scrollable area, which helps display full-page screenshots without shrinking them too much or breaking the layout.

Now your project is set up and ready to capture real screenshots using the ScreenshotBase API.

In the next section, we’ll write the logic to call the ScreenshotBase API and display the resulting screenshot dynamically in the browser.

Integrating the ScreenshotBase API

Now that our Flask app is set up, let’s connect it to the ScreenshotBase API so we can generate real screenshots from any URL.

Step 1: Understanding the API Endpoint

The ScreenshotBase API provides a simple endpoint that takes a website URL and returns a screenshot image.

A typical API call looks like this:

GET https://api.screenshotbase.com/v1/take

You send the target website URL as a query parameter (url) and include your API key in the request header as apikey.

Here’s the cURL example from their documentation:

curl -G https://api.screenshotbase.com/v1/take?url=https%3A%2F%2Fbbc.com \
    -H "apikey: YOUR-API-KEY"

This request captures a screenshot of https://bbc.com and returns the screenshot image as the response.

Step 2: Add the API Call in Flask

Let’s update our home route in app.py to send a request to the ScreenshotBase API when a user submits a URL.

Here’s the updated version of app.py:

from flask import Flask, render_template, request
import requests
import os

app = Flask(__name__)
API_KEY = os.getenv("SCREENSHOTBASE_API_KEY")
SCREENSHOTBASE_BASE_ENDPOINT = "https://api.screenshotbase.com/v1/take"

@app.route('/', methods=['GET', 'POST'])
def home():
    screenshot_url = None

    if request.method == 'POST':
        target_url = request.form.get('url')

        params = {"url": target_url}
        headers = {"apikey": API_KEY}

        try:
            # Send GET request to ScreenshotBase API
            response = requests.get(SCREENSHOTBASE_BASE_ENDPOINT, params=params, headers=headers, timeout=30)
            response.raise_for_status()

            # Save the returned image
            image_path = os.path.join('static', 'screenshot.png')
            with open(image_path, 'wb') as f:
                f.write(response.content)

            screenshot_url = image_path

        except requests.exceptions.RequestException as e:
            print(f"Error capturing screenshot: {e}")

    return render_template('index.html', screenshot=screenshot_url)

if __name__ == '__main__':
    app.run(debug=True)

Here’s what this code does:

1. Captures the user input (URL).

2. Sends a GET request to the /v1/take endpoint.

3. Passes your API key in the request header (apikey).

4. Saves the returned image to the static folder.

5. Displays the screenshot on the page.

Step 3: Test Your App

Run the app again:

python app.py

Then open http://127.0.0.1:5000 in your browser.

Enter a URL like:

https://github.com/ashutoshkrris

After submitting, you should see the screenshot of that website displayed below the form.

Your Flask app is now fully functional! It takes a URL, sends it to the ScreenshotBase API, and displays the resulting screenshot.

In the next section, we’ll enhance the app by adding customization options like full-page screenshots, viewport settings, and delays. Later, we’ll explore the ScreenshotBase SDKs for popular languages like Python, Node.js, and PHP.

Adding Customization Options

Right now, our app simply takes a screenshot of the given website URL using the default settings. However, most screenshot APIs (including the one we’re using) allow you to customize the output by passing additional parameters in the request.

The ScreenshotBase API offers several powerful customization options to help you tailor each screenshot to your needs:

• Image format: Choose from png, jpg, gif, or webp, depending on your image quality or compression requirements.

• Full page capture: Capture the entire scrollable webpage (full_page=1) or just the visible viewport (full_page=0).

• Viewport dimensions: Set the browser window size with viewport_width and viewport_height to simulate screenshots from desktop, tablet, or mobile screens.

These options make ScreenshotBase ideal for building automation tools, thumbnail generators, testing dashboards, and visual documentation systems. Let’s add these options to make our screenshot generator more flexible.

Updating the Flask Code

Open your app.py file and update the route that handles form submissions to include these optional parameters:

from flask import Flask, render_template, request
import requests
import os

app = Flask(__name__)
API_KEY = os.getenv("SCREENSHOTBASE_API_KEY", "scr_live_9Qkn1gs01rivZqrFk7lusXPiqAUg85J86aU6bHvG")
SCREENSHOTBASE_BASE_ENDPOINT = "https://api.screenshotbase.com/v1/take"


@app.route('/', methods=['GET', 'POST'])
def home():
    screenshot_url = None

    if request.method == 'POST':
        target_url = request.form.get('url')
        format_ = request.form.get('format', 'png')
        full_page = request.form.get('full_page') == 'on'

        params = {
            "url": target_url,
            "format": format_,
            "full_page": int(full_page)
        }
        headers = {"apikey": API_KEY}

        try:
            # Send GET request to ScreenshotBase API
            response = requests.get(SCREENSHOTBASE_BASE_ENDPOINT, params=params, headers=headers, timeout=30)
            response.raise_for_status()

            # Save the returned image
            image_extension = format_ if format_ != 'jpeg' else 'jpg'
            image_path = os.path.join('static', f'screenshot.{image_extension}')
            with open(image_path, 'wb') as f:
                f.write(response.content)

            screenshot_url = image_path

        except requests.exceptions.RequestException as e:
            print(f"Error capturing screenshot: {e}")

    return render_template('index.html', screenshot=screenshot_url)


if __name__ == '__main__':
    app.run(debug=True)

Updating the HTML Template

Next, let’s modify the form in our index.html to include the customization options:

<form method="POST" class="d-flex flex-column justify-content-center mb-4">
  <!-- URL and Submit Button in One Row -->
  <div class="input-group mb-4">
    <input
      type="text"
      name="url"
      placeholder="Enter website URL"
      class="form-control w-50 me-2"
      required
    />
    <button type="submit" class="btn btn-primary">Capture Screenshot</button>
  </div>

  <!-- Options in Two Columns -->
  <div class="row g-3">
    <!-- Full Page Checkbox -->
    <div class="col-md-6">
      <div class="form-check">
        <input
          type="checkbox"
          name="full_page"
          id="full_page"
          class="form-check-input"
        />
        <label class="form-check-label" for="full_page">
          Capture Full Page Screenshot
        </label>
      </div>
    </div>

    <!-- Format Dropdown -->
    <div class="col-md-6">
      <label for="format" class="form-label">Screenshot Format</label>
      <select class="form-select" name="format" id="format" required>
        <option value="png">PNG</option>
        <option value="jpg">JPG</option>
        <option value="gif">GIF</option>
        <option value="webp">WEBP</option>
      </select>
    </div>

    <!-- Viewport Width -->
    <div class="col-md-6">
      <label for="viewport_width" class="form-label">Viewport Width</label>
      <input
        type="number"
        name="viewport_width"
        id="viewport_width"
        class="form-control"
        value="1280"
        min="320"
      />
    </div>

    <!-- Viewport Height -->
    <div class="col-md-6">
      <label for="viewport_height" class="form-label">Viewport Height</label>
      <input
        type="number"
        name="viewport_height"
        id="viewport_height"
        class="form-control"
        value="720"
        min="320"
      />
    </div>
  </div>
</form>

The updated form gives users control over how the screenshot is generated. The format dropdown lets them choose between PNG, JPG, GIF, or WEBP. The Full Page checkbox toggles whether the API captures the entire scrollable webpage or just the visible viewport. The viewport width and height fields define the browser window dimensions, which is useful if you want to simulate different device sizes or responsive layouts.

When the form is submitted, Flask reads these values and sends them as query parameters in the API request.

For example, a request to capture a full-page, 1920×1080 PNG screenshot of your site would look like this:

https://api.screenshotbase.com/v1/take?url=https%3A%2F%2Fgithub.com%2Fashutoshkrris&format=png&full_page=1&viewport_width=1920&viewport_height=1080

This flexibility makes it easy to fine-tune screenshots for different use cases – whether you’re generating thumbnails, testing responsiveness, or automating visual reports.

Note: If you prefer working with SDKs instead of direct API calls, ScreenshotBase also offers official SDKs for popular languages like Python, JavaScript, Ruby, PHP, and Go.

These SDKs provide a simpler and more convenient way to interact with the API, handling authentication and request formatting behind the scenes.

You can explore them in the ScreenshotBase SDK documentation.

Wrapping Up

In this tutorial, you learned how to build a simple Flask application that captures website screenshots using a third-party API. We explored how to send requests, handle image responses, and add customization options like image format, full-page capture, and viewport size – all while keeping the project lightweight and easy to extend.

This small project demonstrates how web automation tasks, such as generating previews or visual reports, can be simplified using modern APIs. You can build upon this foundation to create batch screenshot tools, visual monitoring systems, or even integrate screenshots into larger web applications.

The key takeaway is understanding how to interact with external APIs, process responses, and design a clean interface for users. These are skills that are essential for backend and full-stack developers alike.

In this tutorial, you'll learn how to create a simple instant search feature using Flask and HTMX. This will help you build interactive web applications with better user experience.

Table of Contents:

1. How to Set Up the Environment
2. How to Set up the Database
3. How to Set Up Basic Routing and HTML
4. How to Add HTMX for Instant Search
5. Demo
6. Conclusion

Why Use Instant Search?

• Speed: Users get immediate feedback, which helps them refine their search.
• Convenience: It reduces the number of clicks and page loads, leading to a more seamless experience.
• Engagement: Users are more likely to stay on your site if they can find what they need easily.

Technologies Used

To implement this instant search feature, we'll use two main technologies:

• Flask: Flask is a popular web framework for Python. It is simple and lightweight, making it easy to set up and start building web applications quickly. Flask lets you to create routes, handle requests, and serve HTML templates with minimal setup.
• HTMX: This is a powerful JavaScript library that lets you to create dynamic web pages without having to write a lot of JavaScript code. With HTMX, you can update parts of a page based on user actions, like typing in a search box. It makes it easy to load data from the server and display it on the page without a full reload.

How to Set Up the Environment

In this section, we'll set up the environment for our Flask project, including installing the necessary packages and organizing the project structure.

1. How to Install Flask and HTMX

First, you need to install Flask, Flask-SQLAlchemy, and Flask-Migrate. You can do this using pip. Open your terminal and run:

pip install Flask Flask-SQLAlchemy Flask-Migrate

For HTMX, we'll include it in our HTML template directly from a CDN.

2. How to Create a Virtual Environment

It's a good practice to create a virtual environment for your projects to manage dependencies. Here's how to create one:

python -m venv venv

Next, activate the environment:

# On Windows
venv\Scripts\activate

# On macOS/Linux
source venv/bin/activate

3. How to Set Up the Project Structure

Now, set up your project structure as follows:

my_flask_app/
├── core/
│   ├── __init__.py
│   ├── models.py
│   └── routes.py
├── config.py
└── main.py

Let us start with creating the first file: core/init.py. This file is the initialization script for the core module of our Flask application. It sets up the Flask app instance and configures it using the settings from the DevelopmentConfig class, and initializes the database and migration system.

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from config import DevelopmentConfig

# Create the Flask app instance
app = Flask(__name__)

# Load configuration from DevelopmentConfig
app.config.from_object(DevelopmentConfig)

# Initialize SQLAlchemy with the app instance
db = SQLAlchemy(app)

# Initialize Flask-Migrate with the app instance and database
migrate = Migrate(app, db)

# Import routes to register them with the app
from core import routes

Next, we will create the config.py file from where we'll import the DevelopmentConfig class. This file contains configuration settings for different environments (development, testing, production). These settings help manage different behaviors and configurations based on where your app is running.

class Config(object):
    DEBUG = False
    TESTING = False
    CSRF_ENABLED = True
    SECRET_KEY = "guess-me"
    SQLALCHEMY_DATABASE_URI = "sqlite:///db.sqlite"
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    BCRYPT_LOG_ROUNDS = 13
    WTF_CSRF_ENABLED = True
    DEBUG_TB_ENABLED = False
    DEBUG_TB_INTERCEPT_REDIRECTS = False

class DevelopmentConfig(Config):
    DEVELOPMENT = True
    DEBUG = True
    WTF_CSRF_ENABLED = False
    DEBUG_TB_ENABLED = True

class TestingConfig(Config):
    TESTING = True
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///testdb.sqlite"
    BCRYPT_LOG_ROUNDS = 1
    WTF_CSRF_ENABLED = False

class ProductionConfig(Config):
    DEBUG = False
    DEBUG_TB_ENABLED = False

• Config: The base configuration class with default settings.
• DevelopmentConfig: Inherits from Config and overrides development settings.
• TestingConfig: Inherits from Config and overrides settings for testing.
• ProductionConfig: Inherits from Config and overrides production settings.

Finally, we'll create the main.py file. This is the entry point of our application. When we run this file, it starts the Flask web server.

from core import app

# Start the Flask app
if __name__ == '__main__':
    app.run(debug=True)

• if __name__ == '__main__': This ensures that the Flask app runs only if the script is executed directly (not imported as a module).
• app.run(debug=True): Starts the Flask development server with debug mode enabled, which provides detailed error messages and auto-reloading.

Now that you understand the project files, we can proceed with implementing the instant search functionality. This will involve creating the models and search route, setting up the HTMX-powered front-end, and connecting everything to fetch and display search results dynamically.

How to Set up the Database

In this section, we will set up the database for our Flask application. We will use SQLite for simplicity. We will create a model for the data we want to search and seed the database with sample data.

SQLite is a lightweight, disk-based database that doesn’t require a separate server process. It's an excellent choice for development and small projects because it is easy to set up and use.

How to Create a Model for the Data to Be Searched

We will create a Book model to represent the data in our database. This model will include fields like the book title and author.

Let's create the core/models.py file and add the model there:

from core import db

class Book(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    title = db.Column(db.String(100), nullable=False)
    author = db.Column(db.String(100), nullable=False)

How to Apply Migrations Using Flask-Migrate

Before we can seed our database, we need to set up database migrations using Flask-Migrate. This tool helps us manage database changes, such as creating tables and altering schemas, systematically.

Initialize the migrations folder by running the following command in your project directory:

flask db init

This command creates a migrations directory in our project, which will store migration scripts.

Generate a migration script that creates the necessary database tables based on your models:

flask db migrate -m "Initial migration"

This command scans your models and generates a new migration script in the migrations folder.

Apply the migration to create the tables in your database:

flask db upgrade

This command executes the migration script, creating the tables defined by your models in the database. Post this step, you will see an instance/db.sqlite file created.

How to Seed Data Into Your Database

Now that we have set up the database and applied the migration, we can proceed with seeding the database. Create a file named seeder.py with the following content:

import csv
from sqlalchemy.exc import IntegrityError

from core import db, app
from core.models import Book


def seed_data():
    with app.app_context():
        # Open the CSV file
        with open("data.csv", newline='', encoding='utf-8') as csvfile:
            reader = csv.DictReader(csvfile)

            # Iterate over the rows in the CSV file
            for row in reader:
                # Create a new Book instance
                book = Book(
                    title=row['Book Name'],
                    author=row['Author Name']
                )

                # Add the book to the session
                db.session.add(book)

            try:
                # Commit the session to write the books to the database
                db.session.commit()
                print("Books added successfully.")
            except IntegrityError as e:
                db.session.rollback()
                print(f"Error occurred: {e}")


if __name__ == "__main__":
    seed_data()

The seeder script is responsible for populating the database with initial data. This is useful for testing and development purposes, allowing you to work with a set of sample data. This script reads data from data.csv, and processes it to insert it into the database.

Note: You can download the data.csv file from here.

To use this script, ensure your data.csv file exists in the same directory as seeder.py. Run the script using Python:

python seeder.py

How to Set Up Basic Routing and HTML

In this section, we'll set up a basic route in Flask to serve an index page (index.html) where users can search and display books.

How to Set Up Flask Route

Let's set up a Flask route (/) to render an index.html template and display books. For that, create a core/routes.py file and add the following route:

from flask import render_template
from core import app
from core.models import Book

@app.route('/')
def index():
    # Fetch the first 20 books to display by default
    books = Book.query.limit(20).all()
    return render_template("index.html", books=books)

The Flask application handles routing through the @app.route('/') decorator, which directs requests to the root URL (/). When a user visits the homepage, the index() function is invoked.

Inside this function, we query the Book model using SQLAlchemy to fetch the first 20 books from the database. These books are then passed as a parameter (books) to the render_template function, which renders the index.html template.

How to Creating the index.html Template

Create a file named index.html inside a templates directory in your project. The templates directory will lie in the core package. This file will contain the HTML structure for our book search page.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Book Search</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css" />
</head>
<body>
  <section class="section">
    <div class="columns">
      <div class="column is-one-third is-offset-one-third">
        <input type="text" class="input" placeholder="Search" name="query" />
      </div>
    </div>
    <table class="table is-fullwidth">
      <thead>
        <tr>
          <th>ID</th>
          <th>Book Title</th>
          <th>Book Author</th>
        </tr>
      </thead>
      <tbody id="results">
        {% for book in books %}
        <tr>
          <td>{{ book.id }}</td>
          <td>{{ book.title }}</td>
          <td>{{ book.author }}</td>
        </tr>
        {% endfor %}
      </tbody>
    </table>
  </section>
</body>
</html>

This HTML file uses the Bulma CSS framework for styling and includes elements such as an input field for user searches and a table to display book details fetched from the database.

The index.html template utilizes Jinja2 templating to dynamically populate the table rows (<tr>) with book data retrieved from the Flask backend. Each book's ID, title, and author are displayed in the table rows using {{book.id}}, {{ book.title }}, and {{book.author}} respectively.

How to Run the Application

Let's run the application using the following command:

flask run

Once your application is up and running, this what how it should look like:

web page with ID, book titles, and book authors

How to Add HTMX for Instant Search

Finally, we'll add HTMX to enhance our Flask application with dynamic search capabilities. For this, we'll introduce a new route and modify existing HTML template.

How to Create the Search Route

First, create a new route /search in your Flask application to handle book searches based on user input:

from flask import render_template, request
from core import app
from core.models import Book

@app.route('/search')
def search():
    query = request.args.get("query")
    if query:
        results = Book.query.filter(Book.title.ilike(f"%{query}%") | Book.author.ilike(f"%{query}%")).limit(10).all()
    else:
        results = Book.query.limit(20).all()
    return render_template("search_results.html", results=results)

This route listens for GET requests to /search. It retrieves the search query from the URL parameter using request.args.get("query").

If a query parameter is present, it uses SQLAlchemy's ilike method to perform a case-insensitive search across the title and author columns of the Book table, fetching up to 10 results.

If no query parameter is provided, it defaults to fetching the first 20 books from the database. The results are passed to a new search_results.html template for rendering.

How to Modify index.html to Add HTMX

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Book Search</title>
  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css" />
  <!-- Include HTMX library -->
  <script src="https://cdn.jsdelivr.net/npm/htmx.org/dist/htmx.min.js"></script>
</head>
<body>
  <section class="section">
    <div class="columns">
      <div class="column is-one-third is-offset-one-third">
        <!-- HTMX-enabled search input -->
        <input
            type="text"
            class="input"
            placeholder="Search"
            name="query"
            hx-get="/search"
            hx-trigger="keyup changed delay:500ms"
            hx-target="#results"
          />
      </div>
    </div>
    <table class="table is-fullwidth">
      <thead>
        <tr>
          <th>ID</th>
          <th>Book Title</th>
          <th>Book Author</th>
        </tr>
      </thead>
      <tbody id="results">
        {% for book in books %}
          <tr>
            <td>{{ book.id }}</td>
            <td>{{ book.title }}</td>
            <td>{{ book.author }}</td>
          </tr>
        {% endfor %}
      </tbody>
    </table>
  </section>
</body>
</html>

The <script> tag imports the HTMX library from a CDN, enabling client-side interactions without requiring complex JavaScript. In addition to that, we enhanced the <input> element with HTMX attributes:

• hx-get="/search": Specifies the endpoint (/search) to send GET requests when the user types in the input field.
• hx-trigger="keyup changed delay:500ms": Triggers the search action after a 500ms delay when the user types (keyup) or changes the input (changed).
• hx-target="#results": Updates the content of the element with id="results" with the response from the /search endpoint.

How to Create the search_results.html Template

Next, we will create a new template search_results.html to display search results:

{% for result in results %}
<tr>
    <td>{{ result.id }}</td>
    <td>{{ result.title }}</td>
    <td>{{ result.author }}</td>
</tr>
{% endfor %}

This template iterates over results, which are passed from the /search route. For each book in results, generates a table row (<tr>) that displays the book's ID, title, and author.

Demo

Finally, we have implemented instant search with HTMX in our Flask application. Here's what our final application should look like:

You'd notice a delay in the search results. This is called debouncing. It is a technique used in programming and web development to limit the rate at which a function or event handler is executed. It ensures that a function is only executed after a certain amount of time has passed since the last invocation of the function.

In our case, we set the delay to 500ms before it calls the /search API again. This ensures that we do not hit the API for every character the user types.

Conclusion

In this tutorial, you learned how to implement instant search using Flask and HTMX, focusing on enhancing user interaction and performance. By integrating HTMX for AJAX interactions, we enabled dynamic updates to search results without refreshing the entire page.

This approach not only improves user experience by providing real-time feedback but also optimizes server load by debouncing search queries.

By mastering these techniques, you're equipped to build responsive web applications that deliver seamless search experiences, combining the flexibility of Flask with the interactivity of HTMX to meet diverse user needs efficiently and effectively.

You can find the code for this tutorial in this repository: https://github.com/ashutoshkrris/instant-search-with-flask-htmx

As developers, we are tasked with safeguarding these sensitive bits of info, and it's important to implement strong secure measures in our applications.

Now, there are many authentication mechanisms available for securing data, like OAuth, OpenID Connect, and JSON Web Tokens (JWTs).

In this article, I'll show you how to use JWTs when securing information in APIs by integrating JWT-based authentication in a Flask application.

Here's what this article will cover:

• What is a JSON Web Token?
• How Do JWTs Work?
• How to Use JSON Web Tokens to Authenticate Flask Applications
• Install dependencies
• Create a database and user model
• Configure the application for JWT authentication
• Create protected routes
• Create a Login Function
• Conclusion

Prerequisites

To follow along with this tutorial you will need:

• An understanding of HTTP Methods
• An understanding of how to create APIs in Flask
• VS Code (or other similar) editor
• A terminal

What is a JSON Web Token?

JSON Web Tokens, or JWTs, are an authentication mechanism used to securely transmit information between a client and a server in JSON format.

This information can be verified and trusted because it is digitally signed with the HMAC algorithm or a public/private key pair using RSA or ECDSA.

The tokens are encoded into three parts, each divided by a period, like this:

Header.Payload.Signature

• Header: This defines the type of token (JWT) and the signing algorithm used.
• Payload: This carries user-specific data like user ID, username, roles, and any additional claims you want to include. This payload is encoded in Base64 for maximum security.
• Signature: This is a hashed combination of the header, the payload, and the server's secret key. It ensures the token's integrity and that any modifications to the token will be detected.

How Do JWTs Work?

To understand how JWTs work, you need to know what the tokens are meant to do. JWTs are not created to hide data but to ensure that the data being sent is authenticated. This is why the JWT is signed and encoded, not encrypted.

A JWT acts as a stateless means of transmitting data from a client to a server. This means that it doesn't store any session object in the browser, so the browser doesn't maintain a session state between requests.

Instead, JWTs use a token that is sent in a request header each time a request is made. This token confirms that the token sent is authenticated and is allowed access to make that request.

Let's look at how this happens:

1. A user attempts to log in and sends a username and password to be verified by the server.
2. The verification function carries out a check to see if there's a match in the database.
3. A JWT is then generated by the server once the user is successfully authenticated (logged in) using their information (payload), such as user ID or username, and signs it using a secret key.
4. The generated JWT is sent along as a bearer token with every request header to check if the user is authenticated to make that request.

How to Use JSON Web Tokens to Authenticate Flask Applications

To demonstrate how you can implement JWT authentication in Flask, we'll create a simple application that uses JWT for handling login functions and accessing protected routes.

1. Install the dependencies

Run this command to install the dependencies we'll need

pip install flask flask-bcrypt Flask-JWT-Extended

Next, make sure you import the dependencies and initialize your Flask application with this code:

from flask import Flask, jsonify, session, request, redirect, url_for
from flask_jwt_extended import JWTManager, create_access_token, jwt_required, get_jwt_identity, get_jwt


app = Flask(__name__)

////WRITE MAIN CODE HERE


if __name__ == "__main__":
    with app.app_context():
        app.run(debug=True)

2. Create a database and User Model

To do this, we'll use SQL-Alchemy, which is a Python SQL toolkit that makes it less complex to use SQL in Python scripts.

To set up SQL Alchemy in your application, follow these steps:

First, open your terminal or command prompt and enter the following command:

pip install sqlalchemy

This command installs SQLAlchemy in your Python environment, making it available in your project directory.

Next, configure your application to make use of your preferred Database Management System (DBMS). This tutorial will use the SQlite3 DBMS as it doesn't require a separate server:

app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///site.db'

This code snippet instructs Flask-SQLAlchemy to create and use the site.db file in your project directory as the SQLite database for the application.

Then initialize the database in your application:

db = SQLAlchemy(app)

This instance of the database acts as a bridge between the application and the database.

Now create the User Model where we'll store the user's details in this tutorial:

class User(db.Model, UserMixin):
    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(20), unique=True, nullable=False)
    password = db.Column(db.String(80), nullable=False)
    is_active = db.Column(db.Boolean(), default=True)
    cart = db.Column(JSON, nullable=True, default=list)  # Make cart nullable

    # Define the relationship between User and CartProducts
    cart_products = relationship('CartProducts', backref="user", lazy="dynamic")
    # Define the relationship between User and Wishlists
    wishlists = db.relationship('Wishlists', backref='user', lazy=True)

    def __repr__(self):
        return f'<User {self.username}>'

Note: You can create other models using the same syntax to represent different data entities in your application.

3. Configure the application for JWT Authentication

To implement JWT authentication in your Flask application, import the necessary libraries and set up the appropriate configurations with this code:

from flask import Flask, jsonify, request
from flask_sqlalchemy import SQLAlchemy
from flask_jwt_extended import JWTManager, create_access_token, jwt_required

app = Flask(__name__)

# Configuration
app.config['SECRET_KEY'] = 'your_strong_secret_key'
app.config["JWT_SECRET_KEY"] = 'your_jwt_secret_key'
app.config['JWT_TOKEN_LOCATION'] = ['headers']

# Database Initialization
db = SQLAlchemy(app)

# JWT Initialization
jwt = JWTManager(app)

# Rest of the application code (routes, etc.)

This code snippet imports the following components needed for our application:

• app.config['SECRET_KEY'] sets the Flask application's secret key which is used to securely sign session cookies and other security-related needs.
• app.config['JWT_SECRET_KEY'] sets the secret key used to encode and decode JWTs in for Flask-JWT operations.
• app.config['JWT_TOKEN_LOCATION'] specifies where the application should look for the JWT. Here it's set to look in the HTTP headers.

Once we've set this up, we can create the endpoints and routes that we intend to protect.

4. Create protected routes

Protected routes are the pages that we intend to keep hidden from unauthorized users.

For example, let's assume we are trying to get into a venue that's exclusive to members of a society. But a guard is securing the venue from "unauthorized users" like us. In this situation, we are the application's users, the venue is the URL we are protecting, and the guard protecting the venue is a @jwt_required decorator.

The @jwt_required decorator is used to protect specific routes that require authentication. This decorator will confirm that there's a JWT access token in the request headers before allowing access to the page:

@app.route('/get_name', methods=['GET'])
@jwt_required()
def get_name():
    # Extract the user ID from the JWT
    user_id = get_jwt_identity()
    user = User.query.filter_by(id=user_id).first()

    # Check if user exists
    if user:
        return jsonify({'message': 'User found', 'name': user.name})
    else:
        return jsonify({'message': 'User not found'}), 404

In this code snippet, we created a function that returns the name of the user after authentication. If the token is missing, invalid, or expired, the request will be denied, and typically, the server will return an HTTP 401 Unauthorized status.

5. Create a Login Page

In this endpoint, we'll create a function that accepts username and password credentials from the client request (for example, form data) and compares the credentials gotten from the user with the user data in the database. If there's a match, a JWT access token will be generated containing the user's information.

@app.route('/login', methods=['POST'])
def login():
    data = request.get_json()
    username = data['username']
    password = data['password']
    print('Received data:', username , password)

    user = User.query.filter_by(username=username).first()

    if user and bcrypt.check_password_hash(user.password, password):
        access_token = create_access_token(identity=user.id)
        return jsonify({'message': 'Login Success', 'access_token': access_token})
    else:
        return jsonify({'message': 'Login Failed'}), 401

In this example, the function checks the user's credentials against the database using bcrypt for secure password verification when a POST request is received. If the credentials are valid, the server generates a JWT for the user, allowing them to access protected routes.

Here's an example of a React form sending a POST request to the login endpoint:

import React from "react";
import axios from "axios";
import { useState } from "react";
import Footer from "./Footer";
// import "./Login.css";

function Login() {
  const [password, setPassword] = useState("");
  const [username, setUsername] = useState("");

  const handleLogin = async (event) => {
    event.preventDefault();
    const data = {
      username: username,
      Password: password,
    };

    try {
      const response = await axios.post("http://localhost:5000/login", {
        username,
        password,
      });
      localStorage.setItem("access_token", response.data.access_token);
      // Redirect to protected route
      alert("Login successful");
    } catch (error) {
      console.error(error);
      // Display error message to user
    }
  };

  const handleUsernameChange = (event) => {
    setUsername(event.target.value);
  };

  const handlePasswordChange = (event) => {
    setPassword(event.target.value);
  };

  return (
    <div >

          <form method="post" >
              <input
                type="text"
                id=""
                placeholder="Username"
                name="username"
                required
                value={username}
                onChange={handleUsernameChange}
              />
              <input
                type="text"
                id=""
                placeholder="Your email"
              />
              <input
                type="password"
                required
                placeholder="Your Password"
                name="password"
                value={password}
                onChange={handlePasswordChange}
              />
          </form>
          <button type="submit" onClick={handleLogin}>
            Log In
          </button>

    </div>
  );

}

export default Login;

In this React component, we provided a login form that uses Axios to send a POST request to the login endpoint. It manages username and password inputs using React's useState hook and submits these values once the form is submitted.

If the login is successful, it stores a JWT in local Storage. This allows the client-side application to retrieve the token easily when making authenticated requests to the server.

Conclusion

In this article, we've learned how to secure APIs with JSON Web Tokens in Flask. We covered the basics of JWTs, how they work, and provided a step-by-step process for implementing this method of authentication. This included everything from installing necessary dependencies to creating user models and protecting routes.

You can build upon this foundation, such as by adding refresh tokens, integrating with third-party OAuth providers, or handling more complex user permissions.

Magic Link Authentication offers a simple yet secure way for users to log in without passwords. This tutorial will walk you through the implementation of Magic Link Authentication using React for the front end, Flask for the back end, and the authentication service provided by Authsignal.

Table of Contents:

1. Understanding Magic Link Authentication
2. How to Configure Authsignal
3. Application Flow
4. How to Set Up Your Backend Server
5. How to Set Up Environment Variables
6. How to Initialize the Authsignal Client
7. Authsignal Actions
8. How to Create the Required Routes
9. How to Set Up a New Frontend React Project
10. How to Set Up the Components
11. How to Run the Application
12. Wrapping Up

Understanding Magic Link Authentication

Magic link authentication is a convenient and secure authentication method that simplifies users' login process. Instead of entering a username and password, users receive a unique link via email. This link, known as a magic link, grants them access to their account without traditional credentials.

One key difference between magic link authentication and authentication with email verification is the user experience. With magic link authentication, users can authenticate with just a single click. They don't need to remember or enter a password, which can be especially beneficial for users who struggle with password management or find it inconvenient to type in their credentials repeatedly.

While email verification adds an extra layer of security, it may require the user to remember additional credentials or go through multiple steps before accessing their account. If you're interested in learning more about email verification, you can check out my article here to dive deeper into the topic.

How to Configure Authsignal

Authsignal is a service that makes implementing modern authentication methods (like Magic Links and Passkeys) easier. It provides simple tools to integrate secure login methods into your web apps without hassle.

Before proceeding with the tutorial, you need to create an Authsignal account. To do that, you can follow these steps:

First, go to authsignal.com and click on "Create Free Account".

In the next step, create your first tenant. Choose any name for your tenant and select the data storage region.

Creating Tenant on Authsignal

Next, you need to configure the authenticators you want to use for your application. For example, I have enabled Email Magic Link and Authenticator App (TOTP).

Configuring Authenticators

Once you have configured the authenticator, navigate to the API Keys option. Here, you will find your Secret Key, which will be necessary for implementing the authentication.

Finding your secret key

Application Flow

Let's understand the flow of the application:

Initial Visit

• The user visits the application's user interface. On the user interface, they see a login input box and a signup option. Since the user is new, they opt to sign up.

Signup Flow

• Upon clicking the signup link, the user is directed to a page to enter their chosen username.
• After entering the username and clicking the signup button, the front end triggers a POST API call to /api/signup, sending the username in the request body.
• The backend receives the request and communicates with the Authsignal server for user authentication.
• Authsignal prompts the user to set up Magic Link authentication by entering their email address.
• Authsignal sends a magic link to the provided email address.
• After clicking the magic link, the user is authenticated and redirected to the home page, where they receive a welcome message displaying their email address. The page also includes a logout button.

Login Flow

• The user logs out and returns to the login page.
• Here, the user enters their registered username and clicks the Login button.
• Upon clicking Login, the front end triggers a POST API call to /api/login, passing the username in the request body.
• The backend again communicates with Authsignal for user authentication, prompting the setup of Magic Link authentication.
• The user is directed to a page to enter their email address.
• Authsignal sends a magic link to the provided email address.
• After clicking the magic link, the user is authenticated and redirected to the home page, greeted with a welcome message displaying their email address.

This flow ensures users can sign up using a chosen username, and set up Magic Link authentication via email for both signup and login. Here is a video tutorial to visually aid you in understanding the flow:

How to Set Up Your Backend Server

In this section, I will guide you through how to set up your Flask server for implementing Magic Link Authentication. Before we begin, it's recommended to set up a virtual environment to isolate your project's dependencies. Here's how you can do it:

1. Open your terminal or command prompt.
2. Navigate to your project's directory.
3. Run the following command to create a new virtual environment:

python -m venv myenv

Note: Replace myenv with the desired name for your virtual environment.

4. Activate the virtual environment using the appropriate command for your operating system:

5. For Windows:

source myenv/Scripts/activate

• For macOS/Linux:

source myenv/bin/activate

Now that you have your virtual environment set up, let's install the necessary dependencies.

To begin, make sure you have Flask installed, which is a micro web framework for Python. You can install it using the following one-liner:

pip install Flask

Next, we need python-decouple, a library that helps manage configuration settings in separate files. Install it with the following command:

pip install python-decouple

The flask-cors library is a Flask extension that allows for Cross-Origin Resource Sharing (CORS) support in your Flask application.

pip install flask-cors

Finally, we need to install the Python SDK for Authsignal. You can install it with the following command:

pip install authsignal

Now that we have all the necessary dependencies installed, let's create a sample Flask server to get started with Magic Link Authentication. Here's a basic setup to help you get started:

from flask import Flask
from flask_cors import CORS

app = Flask(__name__)
CORS(app, supports_credentials=True)

@app.route("/")
def hello():
    return "Hello, world!"

if __name__ == "__main__":
    app.run(debug=True)

In the next steps, we will integrate AuthSignal and implement the Magic Link Authentication functionality into this server.

How to Set Up Environment Variables

To successfully configure and integrate AuthSignal into your Flask server, you need to set up the following environment variables:

• AUTHSIGNAL_BASE_URL: This variable contains the base URL of the Authsignal server. It allows your server to communicate with Authsignal's authentication service.
• AUTHSIGNAL_SECRET_KEY: This variable contains the secret key associated with your Authsignal project. It is used for secure communication between your server and AuthSignal.
• SECRET_KEY: This variable is a random key used to encrypt the cookies and send them to the browser.

Setting environment variables instead of hardcoding in the code provides improved security by keeping sensitive information, such as API keys and secret keys, separate from the codebase. This reduces the risk of accidental exposure or unauthorized access to these credentials.

To set up these environment variables, you can follow these steps:

1. Open a terminal or command prompt.
2. Navigate to the directory where your Flask server is located.
3. Create a .env file and export the environment variables using the following commands:

export AUTHSIGNAL_BASE_URL=<base_url>
export AUTHSIGNAL_SECRET_KEY=<secret_key>
export SECRET_KEY=<random-secret-key>

Make sure to replace <base_url>, <secret_key>, and <random-secret-key> with the appropriate values for your Authsignal project. You can find the values for these environment variables in the API Keys section of the Authsignal dashboard as explained earlier.

Note: The method for setting environment variables can vary depending on your operating system. The above commands are applicable for Unix-based systems. For Windows, you can use the set command instead of export.

To export the variables added in the .env file, you can use the following command in the terminal:

source .env

By properly setting these environment variables, your Flask server can securely communicate with Authsignal and implement the Magic Link Authentication functionality.

How to Initialize the Authsignal Client

To integrate Authsignal into your Flask server and implement Magic Link Authentication, you need to initialize the Authsignal client. Here's an example of how you can do this:

from flask import Flask
from flask_cors import CORS
import authsignal.client
from decouple import config

app = Flask(__name__)
CORS(app)

AUTHSIGNAL_BASE_URL = config("AUTHSIGNAL_BASE_URL")
AUTHSIGNAL_SECRET_KEY = config("AUTHSIGNAL_SECRET_KEY")
SECRET_KEY = config("SECRET_KEY")

authsignal_client = authsignal.Client(
    api_key=AUTHSIGNAL_SECRET_KEY,
    api_url=AUTHSIGNAL_BASE_URL
)

In this code snippet, we first import the authsignal.client, the Python SDK for Authsignal. We also import config from python-decouple to retrieve the environment variables.

We retrieve the environment variables AUTHSIGNAL_BASE_URL, AUTHSIGNAL_SECRET_KEY and SECRET_KEY using config from python-decouple.

Finally, we initialize the authsignal.Client by passing in the API key AUTHSIGNAL_SECRET_KEY and the base URL of the Authsignal server AUTHSIGNAL_BASE_URL.

By initializing the Authsignal client, we are ready to implement the Magic Link Authentication functionality in our Flask server.

Authsignal Actions

Authsignal allows you to create actions to track and manage user interactions in your application. Actions are events that can be triggered by users, such as signing up or logging in. By creating custom actions, you can have more control over the authentication process and implement specific authentication methods like Magic Link Authentication.

To create an action on your Authsignal dashboard, follow these steps:

1. Click on "Actions" in your Authsignal dashboard.
2. Click on "Configure a new action" to create a new action.
3. Enter a name for the action that describes its purpose or the user interaction it represents.
4. Next, you can configure the rule for the action. In our case, since we want to implement Magic Link Authentication, we will add a rule to challenge users with Email Magic Link. This will send a magic link to the user's email for authentication.
5. Save the action to apply the rule and make it active.

Here is a video demonstrating the process of creating an Authsignal action and configuring it for Magic Link Authentication:

Creating action on Authsignal

You can create two actions – "signUp" and "signIn". In the next steps, we will make use of these actions.

How to Create the Required Routes

Finally, to implement the Magic Link Authentication, we need to create three routes: /api/signup, /api/login, /api/callback, and /api/user.

/api/signup Route

The /api/signup route is responsible for allowing the users to register in our application. Here's how we implement it:

@app.route('/api/signup', methods=['POST'])
def signup():
    username = request.json.get('username')
    if not username:
        return jsonify({'error': 'Missing username parameter'}), 400

    response = authsignal_client.track(
        user_id=username,
        action="signUp",
        payload={
            "user_id": username,
            "redirectUrl": "http://localhost:5000/api/callback"
        }
    )
    return jsonify(response), 200

In this implementation, the route expects a JSON payload containing the username parameter. It then uses the authsignal_client to track the user's signUp action and generate a Magic Link. The track method lets you record actions performed by users and initiate challenges. The redirectUrl specifies the URL where the user will be redirected after they have been authenticated. We will create this API next.

/api/callback Route

The /api/callback route handles the callback URL where the user is redirected after verifying themselves. Here's the implementation for this route:

@app.route('/api/callback', methods=['GET'])
def callback():
    token = request.args.get('token')
    challenge_response = authsignal_client.validate_challenge(token)

    if challenge_response["state"] == 'CHALLENGE_SUCCEEDED':
        encoded_token = jwt.encode(
            payload={"username": challenge_response["user_id"]},
            key=SECRET_KEY,
            algorithm="HS256"
        )
        response = redirect('http://localhost:3000/')
        response.set_cookie(
            key='auth-session',
            value=encoded_token,
            secure=False,
            path='/'
        )
        return response

    return redirect("/")

When the users are redirected, Authsignal adds the JWT token in the URL as a token query parameter.

In this implementation, the route retrieves the token parameter from the query string. It then uses the authsignal_client to validate the challenge and check if the authentication was successful.

If the authentication succeeds, we encode a JSON Web Token (JWT). The token payload includes the username obtained from the challenge response. It uses the SECRET_KEY and the HS256 algorithm for encryption.

Next, the user is redirected to the home page (http://localhost:3000/), and a auth-session cookie is set with the encoded token for further user identification.

Note that the token returned from Authsignal in the redirect is not intended to be used as a session token. It just contains information about the challenge so that we can determine if the challenge was successful.

/api/login Route

The /api/login route is responsible for allowing the users to log into the application. Here’s the implementation for the route:

@app.route('/api/login', methods=['POST'])
def login():
    username = request.json.get('username')
    if not username:
        return jsonify({'error': 'Missing username parameter'}), 400

    response = authsignal_client.track(
        user_id=username,
        action="signIn",
        payload={
            "user_id": username,
            "redirectUrl": "http://localhost:5000/api/callback"
        }
    )
    return jsonify(response), 200

The route is configured to handle POST requests on the /api/login endpoint. Upon receiving a POST request, the route first extracts the provided username from the JSON payload sent with the request. It ensures that the username is present. If not, it promptly returns a 400 error response indicating a missing username parameter.

Similar to the signup flow, it then uses the authsignal_client to track the user's signIn action and generate a Magic Link. The redirectUrl specifies the URL where the user will be redirected after they have been authenticated.

/api/user Route

The /api/user route is responsible for retrieving user information. Here's the implementation for this route:

@app.route("/api/user", methods=['GET'])
def user():
    token = request.cookies.get('auth-session')
    decoded_token = jwt.decode(token, SECRET_KEY, algorithms=["HS256"])
    username = decoded_token.get('username')
    response = authsignal_client.get_user(user_id=username)
    return jsonify({"username": username, "email": response["email"]}), 200

In this implementation, the GET endpoint starts by extracting the auth-session cookie from the incoming request. Then it decodes the JWT using the jwt.decode method, utilizing the SECRET_KEY as the secret key for decoding.

The decoded token provides the username of the user. It then uses the authsignal_client to retrieve user information based on the provided userId. It then returns a JSON response with the username and email information.

By implementing these routes, we will be able to handle the basic authentication process and retrieve user information in our Flask server.

How to Set Up a New Frontend React Project

Let's set up our front-end project in this section. This will also include setting up routing in the application.

Start by initializing a new React project using create-react-app or any preferred method (like Vite, for example, which is a more modern way to set up a React app). This command sets up the basic structure for your React application.

npx create-react-app magic-link-auth
cd magic-link-auth

Once the project is created and you're inside the project directory, install the required dependencies. Here, we need react-router-dom for handling routing and bootstrap for easy styling.

npm install react-router-dom bootstrap

Import Bootstrap CSS

Bootstrap provides pre-styled components and utilities for easier and faster styling of your application.

In the index.js file, import Bootstrap:

import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import reportWebVitals from './reportWebVitals';
import "bootstrap/dist/css/bootstrap.min.css"; // Import Bootstrap CSS

const root = ReactDOM.createRoot(document.getElementById('root'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();

Additionally, we will write some custom CSS. Replace the code in the index.css file with the following code:

html,
body {
  padding: 0;
  margin: 0;
  font-family: -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, Oxygen,
    Ubuntu, Cantarell, Fira Sans, Droid Sans, Helvetica Neue, sans-serif;
}

* {
  box-sizing: border-box;
}

main {
  padding: 5rem 0;
  flex: 1;
  display: flex;
  flex-direction: column;
  justify-content: center;
  align-items: center;
}

code {
  background: #fafafa;
  border-radius: 5px;
  padding: 0.75rem;
  font-family: Menlo, Monaco, Lucida Console, Courier New, monospace;
}

input[type="button"] {
  border: none;
  background: cornflowerblue;
  color: white;
  padding: 12px 24px;
  margin: 8px;
  font-size: 18px;
  border-radius: 8px;
  cursor: pointer;
}

Similarly, replace the code in the App.css with the following code:

.mainContainer {
  flex-direction: column;
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100vh;
}

.titleContainer {
  display: flex;
  flex-direction: column;
  font-size: 48px;
  font-weight: bolder;
  align-items: center;
  justify-content: center;
}

.resultContainer,
.historyItem {
  flex-direction: row;
  display: flex;
  width: 400px;
  align-items: center;
  justify-content: space-between;
}

.historyContainer {
  flex-direction: column;
  display: flex;
  height: 200px;
  align-items: center;
  flex-grow: 5;
  justify-content: flex-start;
}

.buttonContainer {
  display: flex;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  height: 260px;
}

.inputContainer {
  display: flex;
  flex-direction: column;
  align-items: flex-start;
  justify-content: center;
}

.inputContainer>.errorLabel {
  color: red;
  font-size: 16px;
  text-align: center;
}

.inputBox {
  height: 48px;
  width: 400px;
  font-size: medium;
  border-radius: 8px;
  border: 1px solid grey;
  padding-left: 8px;
}

.inputButton {
  height: 48px;
  width: 400px;
}

Set Up Routing

Routing in React applications helps navigate between different views or pages. react-router-dom simplifies this process.

In your App.js file, configure the routing:

import React from "react";
import { BrowserRouter, Routes, Route } from "react-router-dom";
import Dashboard from "./pages/Dashboard";
import Register from "./pages/Register";
import Login from "./pages/Login";
import "./App.css";
import "./index.css";

const App = () => {
  return (
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<Dashboard />} />
        <Route path="/login" element={<Login />} />
        <Route path="/signup" element={<Register />} />
      </Routes>
    </BrowserRouter>
  );
};

export default App;

It defines an App component that encapsulates the entire application structure within a <BrowserRouter> component. Inside <Routes>, we define three components: one for the root path / rendering the Dashboard component, and two for the /login and /signup paths, rendering the Login and Register components respectively.

This setup enables navigation between different views based on URL paths, allowing users to access specific components when they visit corresponding routes within the application.

In the upcoming sections, we will set up the above-mentioned three components.

How to Set Up the Components

In the previous section, we imported two components from the src/pages folder. Let's create a pages folder inside the src folder, and then we can start creating the components.

Register Component

Let’s create a Register.jsx file inside the pages folder. The Register component allows users to register within our application.

import React, { useState, useEffect } from "react";
import { useNavigate, Link } from "react-router-dom";

const Register = () => {
  const [username, setUsername] = useState("");
  const [usernameError, setUsernameError] = useState("");

  const navigate = useNavigate();

  useEffect(() => {
    const isAuthenticated = checkCookies();
    if (isAuthenticated) {
      navigate("/");
    }
  }, [navigate]);

  const checkCookies = () => {
    const authSessionCookie = document.cookie.match("auth-session=([^;]+)");

    return !!authSessionCookie;
  };

  const onButtonClick = () => {
    setUsernameError("");

    if ("" === username) {
      setUsernameError("Username is mandatory!");
      return;
    }

    signup();
  };

  const signup = async () => {
    const response = await fetch("http://localhost:5000/api/login", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        username,
      }),
      credentials: "include",
    });

    const { url } = await response.json();

    // Redirect to verification URL
    window.location.href = url;
  };

  return (
    <div className={"mainContainer"}>
      <div className={"titleContainer"}>
        <div>Sign Up</div>
      </div>
      <br />
      <div className={"inputContainer"}>
        <input
          value={username}
          placeholder="Enter your username"
          onChange={(e) => setUsername(e.target.value)}
          className={"inputBox"}
        />
        <label className="errorLabel text-center">{usernameError}</label>
      </div>
      <br />
      <div className={"inputContainer"}>
        <input
          className={"inputButton"}
          type="button"
          onClick={onButtonClick}
          value={"Sign Up"}
        />
      </div>
      <div>
        Existing User? <Link to="/login">Login here</Link>
      </div>
    </div>
  );
};

export default Register;

The component initializes state variables using useState to manage the visibility of the usernameError and store the username input in userName. It also initializes the navigate function from useNavigate to handle navigation within the application.

We use the useEffect hook to check for authentication cookies when the component mounts. It calls the checkCookies function, which checks for the existence of cookies that we had set from the backend server. If auth-session cookie is found, the user is automatically redirected to the root URL using navigate("/").

Clicking the “Sign Up” button triggers the onButtonClick function. It first checks whether the user has entered the username. If not, it shows an error message using the usernameError. If the user has entered the username, it calls the signup function.

The signup performs an asynchronous POST request to the /api/signup endpoint with the provided username. Upon successful response, it redirects the user to the received verification URL by changing window.location.href.

The JSX returned by the component defines the UI layout that looks like the below:

Register UI Component

It includes an input field for the users to enter their username and a "Sign Up" button. Below the button, we have a link to the Login page for the existing users to log in.

Login Component

We have kept the login page similar to the signup page for simplicity. Hence, the Login component is pretty much the same as the Register component.

import React, { useState, useEffect } from "react";
import { useNavigate, Link } from "react-router-dom";

const Login = () => {
  const [username, setUsername] = useState("");
  const [usernameError, setUsernameError] = useState("");

  const navigate = useNavigate();

  useEffect(() => {
    const isAuthenticated = checkCookies();
    if (isAuthenticated) {
      navigate("/");
    }
  }, [navigate]);

  const checkCookies = () => {
    const authSessionCookie = document.cookie.match("auth-session=([^;]+)");

    return !!authSessionCookie;
  };

  const onButtonClick = () => {
    setUsernameError("");

    if ("" === username) {
      setUsernameError("Username is mandatory!");
      return;
    }

    login();
  };

  const login = async () => {
    const response = await fetch("http://localhost:5000/api/login", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        username,
      }),
      credentials: "include",
    });

    const { url } = await response.json();

    // Redirect to verification URL
    window.location.href = url;
  };

  return (
    <div className={"mainContainer"}>
      <div className={"titleContainer"}>
        <div>Login</div>
      </div>
      <br />
      <div className={"inputContainer"}>
        <input
          value={username}
          placeholder="Enter your username"
          onChange={(ev) => setUsername(ev.target.value)}
          className={"inputBox"}
        />
        <label className="errorLabel text-center">{usernameError}</label>
      </div>
      <br />
      <div className={"inputContainer"}>
        <input
          className={"inputButton"}
          type="button"
          onClick={onButtonClick}
          value={"Log in"}
        />
      </div>
      <div>
        New User? <Link to="/signup">Sign up here</Link>
      </div>
    </div>
  );
};

export default Login;

The only significant difference other than the text and button in the UI here is that we will be making the API call to the /api/login route when the users hit the Login button.

The UI looks like below:

Login UI Component

Dashboard Component

The Dashboard component in our application serves as the interface for authenticated users, displaying a welcome message with the user’s email and enabling user logout functionality.

Let’s create a Dashboard.jsx file inside the pages folder.

import React, { useState, useEffect } from "react";
import { useNavigate } from "react-router-dom";

const Dashboard = () => {
  const [userEmail, setUserEmail] = useState("");
  const navigate = useNavigate();

  useEffect(() => {
    const checkCookies = async () => {
      const authSessionCookie = document.cookie.match("auth-session=([^;]+)");

      if (!authSessionCookie) {
        navigate("/auth");
        return false;
      }

      return true;
    };

    const fetchData = async () => {
      const cookiesValid = await checkCookies();
      if (!cookiesValid) return;

      try {
        const response = await fetch("http://localhost:5000/api/user", {
          method: "GET",
          headers: {
            "Content-Type": "application/json",
          },
          credentials: "include"
        });

        if (!response.ok) {
          throw new Error("Failed to fetch user data");
        }

        const data = await response.json();
        setUserEmail(data.email);
      } catch (error) {
        navigate("/auth");
      }
    };

    fetchData();
  }, [navigate]);

  const handleLogout = () => {
    document.cookie = `auth-session=; max-age=0`;
    navigate("/auth");
  };

  return (
    <div className="d-flex justify-content-center align-items-center vh-100">
      <main className="px-3 text-center">
        <h1>Welcome Home!</h1>
        <p className="lead">You're logged in as {userEmail}!</p>
        <div className="d-flex justify-content-center">
          <button
            className="btn btn-lg btn-dark fw-bold border-white bg-dark"
            onClick={handleLogout}
          >
            Log Out
          </button>
        </div>
      </main>
    </div>
  );
};

export default Dashboard;

Upon component mounting or when navigate changes (a dependency of useEffect), the effect runs. It begins by defining two asynchronous functions. The first, checkCookies, verifies the presence of auth-session cookies. If it is missing, it redirects the user to the authentication route.

The second function, fetchData, is responsible for fetching user data. It checks the validity of cookies using checkCookies. Upon verification, it sends a GET request to our back-end API endpoint. Upon successful response, it updates the userEmail state with the user's email fetched from the API data.

If any error occurs during this process, such as failing to fetch user data, it redirects the user back to the authentication route.

The JSX returned by the component renders a simple dashboard layout.

Dashboard UI Component

The displayed content includes a welcoming message and the currently logged-in user's email. There's also a "Log Out" button which, upon clicking, initiates the logout process by triggering the handleLogout function. It removes the auth-session cookies by setting their max-age to 0, effectively expiring them. Afterward, it redirects the user to the authentication route.

How to Run the Application

You can find the code of the final application in this GitHub repository. To run your backend application, run python app.py from your back-end folder in your terminal. This will start your back-end server on port 5000. Next, run the frontend application using the npm start command. This will start your frontend application on the port 3000.

Wrapping Up

In this tutorial, you learned how to use Authsignal to implement basic user authentication with email verification through magic links.

Authsignal makes handling users and keeping things safe easier, letting developers focus on improving apps. It also removes the overhead of remembering another password for the users of the application.

To learn more about Authsignal, visit the Authsignal documentation.

Should you have any issues or questions related to the tutorial, then feel free to reach out to me on Twitter.

Think of it as a shield for your accounts. Passwords can sometimes be guessed or stolen, but with 2FA, even if someone gets your password, they'd still need that extra code or device to get in. It's an extra step that makes your accounts much harder for hackers to break into.

So, let's explore how to set up this extra layer of protection using PyOTP and Google Authenticator in your Flask app.

Table of Contents:

1. Overview of PyOTP and Google Authenticator
2. Two-Factor Authentication Workflow in Our Application
3. Prerequisites
4. Get Your Tools Ready
5. How to Set Up the Project
6. How to Create Blueprints for Accounts and Core
7. How to Create a User Model
8. How to Add Flask-Login
9. How to Add Templates and Static Files
10. How to Create the Homepage
11. How to Implement User Registration
12. [How to Implement User Login](#

    How to Implement User Login

    )
13. How to Log Out the Users
14. How to Add the Setup 2FA Page
15. How to Add a 2FA Verification Page
16. How to Run the Completed App for the First Time
17. Wrapping Up

Overview of PyOTP and Google Authenticator

PyOTP is a Python library that's incredibly handy for generating Time-based One-Time Passwords (TOTP) and HMAC-based One-Time Passwords (HOTP). Its primary role revolves around creating these unique, time-sensitive codes that add an extra layer of security to user accounts.

By integrating PyOTP into your Flask application, you can easily implement Two-Factor Authentication (2FA) by generating and verifying these OTPs.

If you're new to PyOTP or would like a refresher on its functionalities, I recommend reviewing my previous guide on PyOTP. This understanding will be beneficial as we get into the integration of PyOTP within your Flask application for Two-Factor Authentication (2FA).

Google Authenticator, on the other hand, stands out as one of the most widely used OTP generator apps available. It functions as a secure platform for generating time-based OTPs, compatible with various services and applications supporting 2FA. Users can easily set up Google Authenticator on their devices to generate these time-sensitive codes, adding an extra level of security to their accounts.

Two-Factor Authentication Workflow in Our Application

Here's a breakdown of the flow of two-factor authentication in our application:

1. Registration with 2FA Setup: When users sign up on our website, they're prompted to set up an extra layer of security—2FA. This involves scanning a QR code using an authenticator app, such as Google Authenticator, to link their account securely.
2. Login Initiation: When users return to log in, they start by entering their usual email/username and password combo to access their account.
3. Extra Security Check: Before granting access, our website throws in an additional hurdle: users need to provide an OTP (One-Time Password) displayed on their authenticator app. This ensures they're not just entering the password but also confirming their identity with a unique, time-sensitive code.
4. Validation and Authorization: The user inputs the received OTP into our platform. The system then double-checks this OTP against the expected code, validating the information. If the OTP matches, it's like handing over the secret handshake, granting the user access to their account.

This seamless back-and-forth between passwords, authenticator apps, and unique codes ensures that only the rightful account owner can access the precious content behind the digital doors of your website.

If you also enjoy visual learning, here's a fancy video showing how the app does its thing.

Now, let's get to some coding!

Prerequisites

Before you get started with the tutorial, make sure you have the following requirements satisfied:

• Working knowledge of Python
• Python 3.8+ installed on your system
• Basic knowledge of Flask and Flask Blueprints
• Knowledge of basic authentication in Flask (optional)

Get Your Tools Ready

You'll need a few external libraries for this project. Let's learn more about them and install them one by one.

But before we install them, let's create a virtual environment and activate it.

First, start with creating the project directory and navigating to it like this:

mkdir flask-two-factor-auth
ccd flask-two-factor-auth

We are going to create a virtual environment using venv. Python now ships with a pre-installed venv library. So, to create a virtual environment, you can use the below command:

python -m venv env

The above command will create a virtual environment named env. Now, we need to activate the environment using this command:

source env/Scripts/activate

To verify if the environment has been activated or not, you can see (env) in your terminal. Now, we can install the libraries.

• Flask is a simple, easy-to-use microframework for Python that helps you build scalable and secure web applications.
• Flask-Login provides user session management for Flask. It handles the common tasks of logging in, logging out, and remembering your users’ sessions over extended periods of time.
• Flask-Bcrypt is a Flask extension that provides bcrypt hashing utilities for your application.
• Flask-WTF is a simple integration of Flask and WTForms that helps you create forms in Flask.
• Flask-Migrate is an extension that handles SQLAlchemy database migrations for Flask applications using Alembic. The database operations are made available through the Flask command-line interface.
• Flask-SQLAlchemy is an extension for Flask that adds support for SQLAlchemy to your application. It helps you simplify things using SQLAlchemy with Flask by giving you useful defaults and extra helpers that make it easier to perform common tasks.
• PyOTP helps you generate OTPs using Time-based OTP (TOTP) and HMAC-based OTP (HOTP) algorithms effortlessly.
• QRCode helps you generate QR Codes in Python
• Python Decouple helps you use environment variables in your Python project.

To install the above-mentioned libraries all in one go, run the following command:

pip install Flask Flask-Login Flask-Bcrypt Flask-WTF FLask-Migrate Flask-SQLAlchemy pyotp qrcode python-decouple

How to Set Up the Project

Let’s start by creating a src directory:

mkdir src

The first file will be the __init__.py file for the project:

from decouple import config
from flask import Flask
from flask_bcrypt import Bcrypt
from flask_migrate import Migrate
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config.from_object(config("APP_SETTINGS"))

bcrypt = Bcrypt(app)
db = SQLAlchemy(app)
migrate = Migrate(app, db)

# Registering blueprints
from src.accounts.views import accounts_bp
from src.core.views import core_bp

app.register_blueprint(accounts_bp)
app.register_blueprint(core_bp)

In the above script, we created a Flask app called app . We use the __name__ argument to indicate the app's module or package so that Flask knows where to find other files such as templates. We also set the configuration of the app using an environment variable called APP_SETTINGS. We'll export it later.

To use Flask-Bcrypt, Flask-SQLAlchemy, and Flask-Migrate in our application, we just need to create objects of the Bcrypt, SQLAlchemy and Migrate classes from the flask_bcrypt, flask_sqlalchemy and, flask_migrate libraries, respectively.

We've also registered blueprints called accounts_bp and core_bp in the application. We'll define them later in the tutorial.

In the root directory of the project (that is, outside the src directory), create a file called config.py. We'll store the configurations for the project in this file. Within the file, add the following content:

from decouple import config

DATABASE_URI = config("DATABASE_URL")
if DATABASE_URI.startswith("postgres://"):
    DATABASE_URI = DATABASE_URI.replace("postgres://", "postgresql://", 1)


class Config(object):
    DEBUG = False
    TESTING = False
    CSRF_ENABLED = True
    SECRET_KEY = config("SECRET_KEY", default="guess-me")
    SQLALCHEMY_DATABASE_URI = DATABASE_URI
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    BCRYPT_LOG_ROUNDS = 13
    WTF_CSRF_ENABLED = True
    DEBUG_TB_ENABLED = False
    DEBUG_TB_INTERCEPT_REDIRECTS = False
    APP_NAME = config("APP_NAME")


class DevelopmentConfig(Config):
    DEVELOPMENT = True
    DEBUG = True
    WTF_CSRF_ENABLED = False
    DEBUG_TB_ENABLED = True


class TestingConfig(Config):
    TESTING = True
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///testdb.sqlite"
    BCRYPT_LOG_ROUNDS = 1
    WTF_CSRF_ENABLED = False


class ProductionConfig(Config):
    DEBUG = False
    DEBUG_TB_ENABLED = False

In the above script, we have created a Config class and defined various attributes inside that. Also, we have created different child classes (as per different stages of development) that inherit the Config class.

Notice that we're using a few environment variables like SECRET_KEY, DATABASE_URL, and APP_NAME. Create a file named .env in the root directory and add the following content there:

export SECRET_KEY=fdkjshfhjsdfdskfdsfdcbsjdkfdsdf
export DEBUG=True
export APP_SETTINGS=config.DevelopmentConfig
export DATABASE_URL=sqlite:///db.sqlite
export FLASK_APP=src
export FLASK_DEBUG=1
export APP_NAME="Flask User Authentication App"

Apart from the SECRET_KEY , DATABASE_URL and APP_NAME, we've also exported APP_SETTINGS, DEBUG, FLASK_APP, and FLASK_DEBUG.

The APP_SETTINGS refers to one of the classes we created in the config.py file. We set it to the current stage of the project.

The value of FLASK_APP is the name of the package we have created. Since the app is in the development stage, you can set the values of DEBUG and FLASK_DEBUG to True and 1, respectively.

Run the following command to export all the environment variables from the .env file:

source .env

Next, we'll create a CLI application of the app so that we can later add custom commands if required.

Create a manage.py file in the root directory of the application and add the following code:

from flask.cli import FlaskGroup

from src import app

cli = FlaskGroup(app)


if __name__ == "__main__":
    cli()

Now, your basic application is ready. You can run it using the following command:

python manage.py run

Your file structure should look like below as of now:

flask-two-factor-auth/
├── src/
│   └── __init__.py
├── .env
├── config.py
└── manage.py

How to Create Blueprints for Accounts and Core

As mentioned earlier, you'll use the concepts of blueprints in the project. Let's create two blueprints – accounts_bp and core_bp – in this section.

First create a directory called accounts like this:

mkdir accounts
cd accounts

Next, add an empty __init__.py file to covert it into a Python package. Now, create a views.py file inside the package where you'll store all your routes related to user authentication.

touch __init__.py views.py

Add the following code inside the views.py file:

from flask import Blueprint

accounts_bp = Blueprint("accounts", __name__)

In the above script, you have created a blueprint called accounts_bp for the accounts package.

Similarly, you can create a core package in the root directory, and add a views.py file.

mkdir core
cd core
touch __init__.py views.py

Now, add the following code inside the views.py file:

from flask import Blueprint

core_bp = Blueprint("core", __name__)

Note: If you're new to Flask Blueprints, make sure you go through this tutorial to learn more about how it works.

Now, your file structure should look like what you see below:

flask-two-factor-auth/
├── src/
│   ├── accounts/
│   │   ├── __init__.py
│   │   └── views.py
│   ├── core/
│   │   ├── __init__.py
│   │   └── views.py
│   └── __init__.py
├── .env
├── config.py
└── manage.py

How to Create a User Model

Let's create a models.py file inside the accounts package.

touch src/accounts/models.py

Inside the models.py file, add the following code:

from datetime import datetime

import pyotp
from flask_login import UserMixin

from src import bcrypt, db
from config import Config


class User(db.Model):

    __tablename__ = "users"

    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String, unique=True, nullable=False)
    password = db.Column(db.String, nullable=False)
    created_at = db.Column(db.DateTime, nullable=False)
    is_two_factor_authentication_enabled = db.Column(
        db.Boolean, nullable=False, default=False)
    secret_token = db.Column(db.String, unique=True)

    def __init__(self, username, password):
        self.username = username
        self.password = bcrypt.generate_password_hash(password)
        self.created_at = datetime.now()
        self.secret_token = pyotp.random_base32()

    def get_authentication_setup_uri(self):
        return pyotp.totp.TOTP(self.secret_token).provisioning_uri(
            name=self.username, issuer_name=Config.APP_NAME)

    def is_otp_valid(self, user_otp):
        totp = pyotp.parse_uri(self.get_authentication_setup_uri())
        return totp.verify(user_otp)

    def __repr__(self):
        return f"<user {self.username}>"

In the above code, you created a User model by inheriting the db.Model class. The User model consists of the following fields:

• id: stores the primary key for the users table
• username: stores the username of the user
• password: stores the hashed password of the user
• created_at: stores the timestamp when the user was created
• is_two_factor_authentication_enabled: boolean flag that stores whether the user has activated two-factor authentication. Default value is False.
• secret_token: stores a unique token generated for each user, essential for implementing two-factor authentication.

The constructor initializes the User object upon instantiation by accepting username and password parameters. It hashes the provided password using bcrypt.generate_password_hash(password), records the current timestamp as the created_at value, and generates a unique secret_token using pyotp.random_base32() for 2FA setup.

The get_authentication_setup_uri() method generates a setup URI used by authenticator apps like Google Authenticator. It constructs a URI containing the user's username and the application's name (Config.APP_NAME) necessary for setting up two-factor authentication. The basic format of the URI is:

otpauth://totp/Example:alice@google.com?secret=JBSWY3DPEHPK3PXP&issuer=Example

where, alice@google.com is the username of the user and Example is the application's name.

Next up, the is_otp_valid() method verifies the one-time password (OTP) entered by the user during login. It parses the setup URI generated earlier, checks the validity of the provided OTP (user_otp), and returns True if the OTP matches, ensuring secure authentication.

Finally, the __repr__ method provides a string representation of the User object, displaying the associated username when an instance of the class is printed or represented as a string.

How to Add Flask-Login

The most important part of Flask-Login is the LoginManager class that lets your application and Flask-Login work together.

In the src/__init__.py file, add the following code:

from decouple import config
from flask import Flask
from flask_login import LoginManager # Add this line
from flask_migrate import Migrate
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config.from_object(config("APP_SETTINGS"))

login_manager = LoginManager() # Add this line
login_manager.init_app(app) # Add this line
db = SQLAlchemy(app)
migrate = Migrate(app, db)

# Registering blueprints
from src.accounts.views import accounts_bp
from src.core.views import core_bp

app.register_blueprint(accounts_bp)
app.register_blueprint(core_bp)

In the above script, we created and initialized the login manager in our app.

Next, we need to provide a user_loader callback. This callback is used to reload the user object from the user ID stored in the session. It should take the ID of a user, and return the corresponding user object.

from src.accounts.models import User

@login_manager.user_loader
def load_user(user_id):
    return User.query.filter(User.id == int(user_id)).first()

The User model should implement the following properties and methods:

• is_authenticated: This property returns True if the user is authenticated.
• is_active: This property returns True if this is an active user (the account is activated)
• is_anonymous: This property returns True if this is an anonymous user (actual users return False).
• get_id(): This method returns a string that uniquely identifies this user, and can be used to load the user from the user_loader callback.

Now, we don't need to implement these explicitly. Instead, the Flask-Login provides a UserMixin class that contains the default implementations for all of these properties and methods. We just need to inherit it in the following way:

from datetime import datetime

from flask_login import UserMixin # Add this line

from src import bcrypt, db


class User(UserMixin, db.Model): # Change this line
    ....

We can also customize the default login process in the src/__init__.py file.

The name of the login view can be set as LoginManager.login_view. The value refers to the function name that will handle the login process.

login_manager.login_view = "accounts.login"

To customize the message category, set LoginManager.login_message_category:

login_manager.login_message_category = "danger"

How to Add Templates and Static Files

Let's create a CSS file called styles.css inside the src/static folder:

.error {
  color: red;
  margin-bottom: 5px;
  text-align: center;
}

a {
  text-decoration: none;
}

Let's also create the basic templates inside the src/templates folder. Create a _base.html file and add the following code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Two Factor Authentication</title>
    <!-- meta -->
    <meta name="description" content="">
    <meta name="author" content="">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <!-- styles -->
    <!-- CSS only -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" crossorigin="anonymous">
    <link rel="stylesheet" href="{{url_for('static', filename="styles.css")}}">
    {% block css %}{% endblock %}
  </head>
  <body>

    {% include "navigation.html" %}

    <div class="container">

      <br>

      <!-- messages -->
      {% with messages = get_flashed_messages(with_categories=true) %}
      {% if messages %}
      <div class="row">
        <div class="col-md-4"></div>
        <div class="col-md-4">
          {% for category, message in messages %}
          <div class="alert alert-{{ category }} alert-dismissible fade show" role="alert">
           {{message}}
           <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
          </div>
          {% endfor %}
        </div>
        <div class="col-md-4"></div>
      </div>
      {% endif %}
      {% endwith %}

      <!-- child template -->
      {% block content %}{% endblock %}

    </div>

    <!-- scripts -->
    <script src="https://code.jquery.com/jquery-3.7.1.min.js" integrity="sha256-/JqT3SQfawRcv/BIHPThkBvs0OEvtFFmqPF/lYI/Cxo=" crossorigin="anonymous"></script>
    <!-- JavaScript Bundle with Popper -->
    <script src="https://cdn.jsdelivr.net/npm/@popperjs/core@2.11.8/dist/umd/popper.min.js" integrity="sha384-I7E8VVD/ismYTF4hNIPjVp/Zjvgyol6VFvRkX/vR+Vc4jQkC+hVqc2pM8ODewa9r" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.min.js" integrity="sha384-BBtl+eGJRgqQAUMxJ7pMwbEyER4l1g+O15P+16Ep7Q9Q+zqX6gSbd85u4mG4QzX+" crossorigin="anonymous"></script>
    {% block js %}{% endblock %}
  </body>
</html>

The _base.html is the parent HTML file that will be inherited by the other templates. We have added Bootstrap 5 support in the above file. We are also making use of Flask Flashes to show Bootstrap alerts in the app.

Let's also create a navigation.html file that contains the navbar of the app:

<!-- Navigation -->
<nav class="navbar bg-dark navbar-expand-lg bg-body-tertiary p-3" data-bs-theme="dark">
  <div class="container-fluid">
    <a class="navbar-brand" href="{{ url_for('core.home') }}">Two-Factor Authentication App</a>
    <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarSupportedContent" aria-controls="navbarSupportedContent" aria-expanded="false" aria-label="Toggle navigation">
      <span class="navbar-toggler-icon"></span>
    </button>
    <div class="collapse navbar-collapse" id="navbarSupportedContent">
      {% if current_user.is_authenticated %}
      <a href="{{ url_for('accounts.logout') }}"><button type="button" class="btn btn-danger me-2">Logout</button></a>
      {% endif %}
    </div>
  </div>
</nav>

Note that we have not yet created the views used above.

How to Create the Homepage

In this section, we'll first create a view function for the homepage inside the core/views.py file. Add the following code there:

from flask import Blueprint, render_template
from flask_login import login_required

core_bp = Blueprint("core", __name__)


@core_bp.route("/")
@login_required
def home():
    return render_template("core/index.html")

Notice that we have used the blueprint to add the route. We also added a @login_required middleware to prevent access for unauthenticated users.

Next, let's create an index.html file inside the templates/core folder, and add the following code:

{% extends "_base.html" %}
{% block content %}

<h1 class="text-center">Welcome {{current_user.username}}!</h1>

{% endblock %}

The HTML page will just have a welcome message for authenticated users.

Your file structure as of now should look like below:

flask-two-factor-auth/
├── src/
│   ├── accounts/
│   │   ├── __init__.py
│   │   └── views.py
│   ├── core/
│   │   ├── __init__.py
│   │   └── views.py
│   ├── static/
│   │   └── styles.css
│   ├── templates/
│   │   ├── core/
│   │   │   └── index.html
│   │   ├── _base.html
│   │   └── navigation.html
│   └── __init__.py
├── .env
├── config.py
└── manage.py

How to Implement User Registration

First of all, we'll create a registration form using Flask-WTF. Create a forms.py file inside the accounts package and add the following code:

from flask_wtf import FlaskForm
from wtforms import EmailField, PasswordField
from wtforms.validators import DataRequired, Email, EqualTo, Length

from src.accounts.models import User


class RegisterForm(FlaskForm):
    username = StringField(
        "Username", validators=[DataRequired(), Length(min=6, max=40)]
    )
    password = PasswordField(
        "Password", validators=[DataRequired(), Length(min=6, max=25)]
    )
    confirm = PasswordField(
        "Repeat password",
        validators=[
            DataRequired(),
            EqualTo("password", message="Passwords must match."),
        ],
    )

    def validate(self, extra_validators):
        initial_validation = super(RegisterForm, self).validate(extra_validators)
        if not initial_validation:
            return False
        user = User.query.filter_by(username=self.username.data).first()
        if user:
            self.username.errors.append("Username already registered")
            return False
        if self.password.data != self.confirm.data:
            self.password.errors.append("Passwords must match")
            return False
        return True

The RegisterForm extends the FlaskForm class and contains three fields – username, password, and confirm. We have added different validators such as DataRequired, Length, Email, and EqualTo to the respective fields.

We also defined a validate() method which is automatically called when the form is submitted.

Inside the method, we first perform the initial validation provided by FlaskForm. If that is successful, we perform our custom validation such as checking whether user is already registered, and matching the password with the confirmed password. If there are any errors, we append the error message in the respective fields.

Now, let's use this form inside the HTML file. Create an accounts directory inside the templates folder and add a new file called register.html inside it. Add the following code:

{% extends "_base.html" %}

{% block content %}

<div class="row">
  <div class="col-md-4"></div>
  <div class="col-md-4">
    <main class="form-signin w-100 m-auto">
      <form role="form" method="post" action="">
        {{ form.csrf_token }}
        <h1 class="h3 mb-3 fw-normal text-center">Please register</h1>

        <div class="form-floating">
          {{ form.username(placeholder="username", class="form-control mb-2") }}
          {{ form.username.label }}
            {% if form.username.errors %}
              {% for error in form.username.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <div class="form-floating">
          {{ form.password(placeholder="password", class="form-control mb-2") }}
          {{ form.password.label }}
            {% if form.password.errors %}
              {% for error in form.password.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <div class="form-floating">
          {{ form.confirm(placeholder="Confirm Password", class="form-control mb-2") }}
          {{ form.confirm.label }}
            {% if form.confirm.errors %}
              {% for error in form.confirm.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <button class="w-100 btn btn-lg btn-primary" type="submit">Sign up</button>
        <p class="text-center mt-3">Already registered? <a href="{{ url_for('accounts.login') }}">Login now</a></p>
      </form>
    </main>
  </div>
  <div class="col-md-4"></div>
</div>

{% endblock %}

In the above Jinja template, we make use of the form that we created, and add relevant error handling logic checks for validation errors in each field. Users can submit the form by clicking the "Sign up" button, and a link below the form allows already registered users to navigate to the login page for authentication.

Next, let's use this form in the views.py to create a function to handle the registration process.

from .forms import RegisterForm
from src.accounts.models import User
from src import db, bcrypt
from flask_login import current_user
from flask import Blueprint, flash, redirect, render_template, request, url_for

accounts_bp = Blueprint("accounts", __name__)

HOME_URL = "core.home"
SETUP_2FA_URL = "accounts.setup_two_factor_auth"
VERIFY_2FA_URL = "accounts.verify_two_factor_auth"

@accounts_bp.route("/register", methods=["GET", "POST"])
def register():
    if current_user.is_authenticated:
        if current_user.is_two_factor_authentication_enabled:
            flash("You are already registered.", "info")
            return redirect(url_for(HOME_URL))
        else:
            flash("You have not enabled 2-Factor Authentication. Please enable first to login.", "info")
            return redirect(url_for(SETUP_2FA_URL))
    form = RegisterForm(request.form)
    if form.validate_on_submit():
        try:
            user = User(username=form.username.data, password=form.password.data)
            db.session.add(user)
            db.session.commit()

            login_user(user)
            flash("You are registered. You have to enable 2-Factor Authentication first to login.", "success")

            return redirect(url_for(SETUP_2FA_URL))
        except Exception:
            db.session.rollback()
            flash("Registration failed. Please try again.", "danger")

    return render_template("accounts/register.html", form=form)

The route begins by checking if the current user is already authenticated. If so, it verifies whether 2FA is enabled for the user. If 2FA is already enabled, a message informs the user that they're already registered, redirecting them to the home URL. However, if the user is authenticated but 2FA is not enabled, a flash message prompts the user to enable 2FA first before logging in, redirecting them to the 2FA setup URL.

If the user is not authenticated or has not yet registered 2FA, the code initializes a registration form and proceeds to validate the form data on submission. Upon successful form validation, we create a new User object with the provided username and password and save it to the database.

Upon successful user registration, the newly registered user is logged in. A success message flashes, notifying the user of successful registration and prompting them to enable 2FA before logging in. Subsequently, the user is redirected to the 2FA setup URL to enable 2FA.

How to Implement User Login

First, let's create a login form in the accounts/forms.py file:

class LoginForm(FlaskForm):
    username = StringField("Username", validators=[DataRequired()])
    password = PasswordField("Password", validators=[DataRequired()])

The form is similar to the registration form but it has only two fields – username and password.

Now, let's use this form inside new HTML file called login.html created inside the templates/accounts directory. Add the following code:

{% extends "_base.html" %}

{% block content %}

<div class="row">
  <div class="col-md-4"></div>
  <div class="col-md-4">
    <main class="form-signin w-100 m-auto">
      <form role="form" method="post" action="">
        {{ form.csrf_token }}
        <h1 class="h3 mb-3 fw-normal text-center">Please sign in</h1>

        <div class="form-floating">
          {{ form.username(placeholder="username", class="form-control mb-2") }}
          {{ form.username.label }}
            {% if form.username.errors %}
              {% for error in form.username.errors %}
              <div class="alert alert-danger" role="alert">
                {{ error }}
              </div>
              {% endfor %}
            {% endif %}
        </div>
        <div class="form-floating">
          {{ form.password(placeholder="password", class="form-control mb-2") }}
          {{ form.password.label }}
            {% if form.password.errors %}
              {% for error in form.password.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <button class="w-100 btn btn-lg btn-primary" type="submit">Sign in</button>
        <p class="text-center mt-3">New User? <a href="{{ url_for('accounts.register') }}">Register now</a></p>
      </form>
    </main>
  </div>
  <div class="col-md-4"></div>
</div>

{% endblock %}

The above HTML file is also similar to the register.html file but with just two fields for the username and password.

Next, let's create a view function to handle the login process inside the accounts/views.py file:

from .forms import LoginForm, RegisterForm

@accounts_bp.route("/login", methods=["GET", "POST"])
def login():
    if current_user.is_authenticated:
        if current_user.is_two_factor_authentication_enabled:
            flash("You are already logged in.", "info")
            return redirect(url_for(HOME_URL))
        else:
            flash("You have not enabled 2-Factor Authentication. Please enable first to login.", "info")
            return redirect(url_for(SETUP_2FA_URL))

    form = LoginForm(request.form)
    if form.validate_on_submit():
        user = User.query.filter_by(username=form.username.data).first()
        if user and bcrypt.check_password_hash(user.password, request.form["password"]):
            login_user(user)
            if not current_user.is_two_factor_authentication_enabled:
                flash(
                    "You have not enabled 2-Factor Authentication. Please enable first to login.", "info")
                return redirect(url_for(SETUP_2FA_URL))
            return redirect(url_for(VERIFY_2FA_URL))
        elif not user:
            flash("You are not registered. Please register.", "danger")
        else:
            flash("Invalid username and/or password.", "danger")
    return render_template("accounts/login.html", form=form)

The route starts by checking if the current user is already authenticated. If the user is authenticated and 2FA is enabled, a message informs the user they're already logged in, redirecting them to the home URL. If the user is authenticated but 2FA isn't enabled, a flash message prompts the user to enable 2FA before logging in, redirecting them to the 2FA setup URL.

If the user isn't authenticated, the code initializes a login form and validates the form data upon submission. Upon successful validation, it queries the database to find a user matching the provided username. If the user exists and the password matches the hashed password stored in the database, the user is logged in.

Additionally, if 2FA isn't enabled for the current user after successful login, a flash message prompts the user to enable 2FA before proceeding, redirecting them to the 2FA setup URL. If the login is successful and 2FA is enabled, the user is redirected to the 2FA verification URL.

If the user isn't registered, a flash message informs them to register. If there's a mismatch in the provided username or password, another flash message notifies the user of invalid credentials.

How to Log Out the Users

Logging out the user is a very simple process. You just need to create a view function for it inside the accounts/views.py file:

from flask_login import login_required, login_user, logout_user


@accounts_bp.route("/logout")
@login_required
def logout():
    logout_user()
    flash("You were logged out.", "success")
    return redirect(url_for("accounts.login"))

The Flask-Login library contains a logout_user method that removes the user from the session. We used the @login_required decorator so that only authenticated users can logout.

How to Add the Setup 2FA Page

Up until now, we have been redirecting the users to the setup 2FA page whenever the 2FA is not enabled in their accounts, but we haven't implemented it yet. Let's do that in this section.

Let's start with the route for the page:

from src.utils import get_b64encoded_qr_image

@accounts_bp.route("/setup-2fa")
@login_required
def setup_two_factor_auth():
    secret = current_user.secret_token
    uri = current_user.get_authentication_setup_uri()
    base64_qr_image = get_b64encoded_qr_image(uri)
    return render_template("accounts/setup-2fa.html", secret=secret, qr_image=base64_qr_image)

The route, created inside accounts/views.py, ensures that only authenticated users can access it using the @login_required decorator.

Upon accessing this route, the function retrieves the current user's secret_token for 2FA setup and generates a URI through current_user.get_authentication_setup_uri() to configure an authenticator app like Google Authenticator.

It also uses get_b64encoded_qr_image(uri) to obtain a Base64-encoded QR code image representing this setup URI. We will define it below.

Finally, it renders the setup-2fa.html template, passing the user's secret_token and the Base64-encoded QR image to the template for users to scan it.

Next, create a utils.py file in the src directory and add the following code to generate the QR:

from io import BytesIO
import qrcode
from base64 import b64encode


def get_b64encoded_qr_image(data):
    print(data)
    qr = qrcode.QRCode(version=1, box_size=10, border=5)
    qr.add_data(data)
    qr.make(fit=True)
    img = qr.make_image(fill_color='black', back_color='white')
    buffered = BytesIO()
    img.save(buffered)
    return b64encode(buffered.getvalue()).decode("utf-8")

Remember the qrcode library we installed in the beginning of the tutorial? This is where we're going to use it.

Upon receiving data as input, representing the content to be embedded within the QR code, the function initializes a QRCode object using the qrcode library. It adds the provided data to this QR code instance and generates the QR code. The code then converts this QR code into an image representation.

Using a BytesIO object, it stores this image in memory. The function proceeds to encode the content of this in-memory buffer, representing the QR code image, into Base64 format. Finally, it returns this Base64-encoded string, encapsulating the QR code image, ready for transmission or display in various applications.

Next, let's create the setup-2fa.html page inside the templates/accounts folder, and add the following content:

{% extends "_base.html" %}

{% block content %}

<div class="row">
  <div class="col-md-4"></div>
  <div class="col-md-4">
    <main class="form-signin w-100 m-auto">
      <form role="form">
        <h5>Instructions!</h5>
          <ul>
            <li>Download <a href="https://play.google.com/store/apps/details?id=com.google.android.apps.authenticator2&hl=en&gl=US" target="_blank">Google Authenticator</a> on your mobile.</li>
            <li>Set up a new authenticator.</li>
            <li>Once you have scanned the QR, please click <a href="{{ url_for('accounts.verify_two_factor_auth') }}">here.</li>
          </ul>
          <div class="text-center">
            <img src="data:image/png;base64, {{ qr_image }}" alt="Secret Token" style="width:200px;height:200px"/>
          </div>
        <div class="form-group">
          <label for="secret">Secret Token</label>
          <input type="text" class="form-control" id="secret" value="{{ secret }}" readonly>
        </div>
        <div class="text-center mt-2">
          <button type="button" class="btn btn-primary" onclick="copySecret()">
            Copy Secret
          </button>
        </div>
        <p class="mt-4 text-center">
          Once you have scanned the QR, please click <a href="{{ url_for('accounts.verify_two_factor_auth') }}">here</a>.
        </p>
      </form>
    </main>
  </div>
  <div class="col-md-4"></div>
</div>

{% endblock %}

{% block js %}
<script>
    function copySecret() {
    var copyText = document.getElementById("secret");
    copyText.select();
    copyText.setSelectionRange(0, 99999); /*For mobile devices*/
    document.execCommand("copy");
    alert("Successfully copied TOTP secret token!");
  }
</script>
{% endblock %}

We add some instructions in the page for the users to follow. These instructions provide clear steps for users to enable 2FA: directing them to download the Google Authenticator app via a link, guiding the setup process within the app, and prompting users to proceed by clicking a link after scanning the displayed QR code.

Displaying the QR code is central to the setup process. The template embeds the QR code image using an <img> tag with its source set to a Base64-encoded string ({{ qr_image }}). This image represents the secret key essential for 2FA setup.

We also show the secret key in read-only mode, allowing users to view the key without being able to modify it. We have added a copy button to make it easier for the users to copy the key.

Moreover, we have added a link to the 2FA verification page guiding users to proceed with the setup process after scanning the QR code. We will implement this functionality in the next section.

Here's how your page looks right now:

2FA Setup Page

How to Add a 2FA Verification Page

In this section, let's implement the 2FA verification. To start with, we will require an OTP form where users can enter their OTP. Add the following content in the accounts/forms.py file:

class TwoFactorForm(FlaskForm):
    otp = StringField('Enter OTP', validators=[
                      InputRequired(), Length(min=6, max=6)])

The TwoFactorForm contains just one field (otp) to get the OTP from the users.

Now, let's use this form in the verify-2fa.html file inside the templates/accounts folder:

{% extends "_base.html" %}

{% block content %}

<div class="row">
  <div class="col-md-4"></div>
  <div class="col-md-4">
    <main class="form-signin w-100 m-auto">
      <form role="form" method="post" action="">
        {{ form.csrf_token }}
        <h1 class="h3 mb-3 fw-normal text-center">Enter OTP</h1>

        <div class="form-floating">
          {{ form.otp(placeholder="OTP", class="form-control mb-2") }}
          {{ form.otp.label }}
            {% if form.otp.errors %}
              {% for error in form.otp.errors %}
              <div class="alert alert-danger" role="alert">
                {{ error }}
              </div>
              {% endfor %}
            {% endif %}
        </div>
        <button class="w-100 btn btn-lg btn-primary" type="submit">Verify</button>
      </form>
    </main>
  </div>
  <div class="col-md-4"></div>
</div>

{% endblock %}

The Jinja template essentially contains a form with one field for OTP and a verify button.

Let's create the route which handles the submission of this form inside the accounts/views.py file:

@accounts_bp.route("/verify-2fa", methods=["GET", "POST"])
@login_required
def verify_two_factor_auth():
    form = TwoFactorForm(request.form)
    if form.validate_on_submit():
        if current_user.is_otp_valid(form.otp.data):
            if current_user.is_two_factor_authentication_enabled:
                flash("2FA verification successful. You are logged in!", "success")
                return redirect(url_for(HOME_URL))
            else:
                try:
                    current_user.is_two_factor_authentication_enabled = True
                    db.session.commit()
                    flash("2FA setup successful. You are logged in!", "success")
                    return redirect(url_for(HOME_URL))
                except Exception:
                    db.session.rollback()
                    flash("2FA setup failed. Please try again.", "danger")
                    return redirect(url_for(VERIFY_2FA_URL))
        else:
            flash("Invalid OTP. Please try again.", "danger")
            return redirect(url_for(VERIFY_2FA_URL))
    else:
        if not current_user.is_two_factor_authentication_enabled:
            flash(
                "You have not enabled 2-Factor Authentication. Please enable it first.", "info")
        return render_template("accounts/verify-2fa.html", form=form)

The route starts by initializing a form (TwoFactorForm) meant for 2FA verification using the data obtained from the request. Upon form submission, the code proceeds with several conditional checks to validate the OTP entered by the user.

Once the form has been successfully submitted and validated, the code verifies the authenticity of the OTP using current_user.is_otp_valid(form.otp.data), which checks if the entered OTP is valid for the current user. If the OTP is valid, the code executes the following logic:

• If the provided OTP is valid and 2FA is already enabled for the user, a success message is flashed indicating successful 2FA verification, and the user is redirected to the home URL.
• If the OTP is valid but 2FA isn't enabled for the user, it attempts to enable 2FA for that user. Upon successful activation, a success message flashes, and the user is redirected to the home URL.

Furthermore, if the OTP entered by the user is invalid, the code flashes an error message indicating an invalid OTP and redirects the user back to the 2FA verification URL to retry the verification process.

2FA Verification Page

With this, we have completed the implementation of all the features! 🎉

How to Run the Completed App for the First Time

Now that our application is ready, you can first migrate the database, and then run the app.

To initialize the database (create a migration repository), use the command:

flask db init

To migrate the database changes, use the command:

flask db migrate

To apply the migrations, use the command:

flask db upgrade

Since this is the first time we're running our app, you'll need to run all the above commands. Later, whenever you make changes to the database, you'll just need to run the last two commands.

After that, you can run your application using the command:

python manage.py run

Since we have completed the development, here's how your file structure should look like:

flask-two-factor-auth/
├── migrations/
├── src/
│   ├── accounts/
│   │   ├── __init__.py
│   │   ├── forms.py
│   │   ├── models.py
│   │   └── views.py
│   ├── core/
│   │   ├── __init__.py
│   │   └── views.py
│   ├── static/
│   │   └── styles.css
│   ├── templates/
│   │   ├── accounts/
│   │   │   ├── login.html
│   │   │   ├── register.html
│   │   │   ├── setup-2fa.html
│   │   │   └── verify-2fa.html
│   │   ├── core/
│   │   │   └── index.html
│   │   ├── _base.html
│   │   └── navigation.html
│   ├── __init__.py
│   └── utils.py
├── .env
├── config.py
└── manage.py

Wrapping up

In this tutorial, you learned how to set up two-factor authentication in your Flask app using PyOTP.

Here's the link to the GitHub repository. Feel free to check it out whenever you're stuck.

Here are some other tutorials I wrote about authentication, email verification, and OTPs that you might enjoy:

• How to Set Up Basic User Authentication in a Flask App
• How to Set Up Email Verification in a Flask App
• How To Generate OTPs Using PyOTP in Python

Thank you for reading. I hope you found this article useful. You can follow me on Twitter.

Email-based authentication is one of the most popular and widely used methods for user registration and login. But it's not always reliable, as users can enter fake or invalid email addresses during registration. This can lead to security risks and fraud. This is where Email Validation Services come in handy.

In this tutorial, you'll use the Email Validation Service to help you automate your email validation process during user registration by validating contact information.

The API checks the syntax, domain, and mailbox of an email address, and can even detect disposable and risky emails.

By integrating this API with your application, you can ensure that only valid and genuine email addresses are used for user registration, which will enhance the security of your application.

Prerequisites

Before you get started with the tutorial, make sure you have satisfied the following requirements:

• Working knowledge of Python
• Python 3.8+ installed on your system
• Basic knowledge of Flask, Flask Blueprints and Requests.

How to Set Up the Virtual Environment

Before you start coding, you'll need to make sure you have all the necessary tools and libraries installed. To ensure that you have a clean and isolated environment, you'll create a virtual environment using venv.

Create a project directory and navigate to it in the terminal:

mkdir email-validation
cd email-validation

Create a virtual environment named env using the following command:

python -m venv env

Python now ships with pre-installed venv library to create virtual environments.

Activate the virtual environment like this:

source env/bin/activate

Note: If you're on Windows, you'll need to use source env/Scripts/activate to activate the environment.

You should see (env) in your terminal prompt, indicating that the virtual environment has been activated.

How Email Validation Service Works

Email validation is an essential process for any web application that requires user authentication, and there are various ways to perform it.

One way is to use an email validation service such as emailvalidation.io. This API allows developers to validate email addresses by checking whether they are syntactically correct, whether the domain exists, and whether the mailbox can receive messages.

The API offers a range of pricing plans to suit different needs. The free plan allows developers to validate up to 100 emails, which should be sufficient for our testing purposes. The paid plans start at $9.99 per month and offer more requests, more features, and faster response times.

In this section, you'll write a Python function that sends a GET request to the API's endpoint and passes the email address to be validated as a parameter.

To authenticate the API request, you will also need to pass the API key with the request. Before proceeding, you must create an account on emailvalidation.io to obtain an API key. Once you've created your account, you will be redirected to a dashboard, similar to the one shown below. The API key is located in the black highlighted area.

To make a GET request, you'll need to install the requests library in your virtual environment:

pip install requests

Next, create a test.py file and add the following code there:

import requests
from requests.structures import CaseInsensitiveDict


def is_valid(email: str):
    url = f"https://api.emailvalidation.io/v1/info?email={email}"

    headers = CaseInsensitiveDict()
    headers["apikey"] = "your-api-key-here"

    response = requests.get(url, headers=headers)

    return response.json()


print(is_valid("support@emailvalidation.io"))
print(is_valid("venip42579@jdsdhak.com"))

The is_valid function takes an email address as an argument and constructs a URL with the email address to call the emailvalidation.io API. The CaseInsensitiveDict class from the requests.structures module is used to create a dictionary with case-insensitive keys to set the API key in the header of the request. You then return the JSON response from the function.

Finally, you call the is_valid function twice with different email addresses to demonstrate how the function can validate both a valid email address (support@emailvalidation.io) and an invalid email address (venip42579@jdsdhak.com).

Output:

{
   "email":"support@emailvalidation.io",
   "user":"support",
   "tag":"",
   "domain":"emailvalidation.io",
   "smtp_check":true,
   "mx_found":true,
   "did_you_mean":"",
   "role":true,
   "disposable":false,
   "score":0.64,
   "state":"deliverable",
   "reason":"valid_mailbox",
   "free":false,
   "format_valid":true,
   "catch_all":"None"
}
{
   "email":"venip42579@jdsdhak.com",
   "user":"venip42579",
   "tag":"",
   "domain":"jdsdhak.com",
   "smtp_check":false,
   "mx_found":false,
   "did_you_mean":"",
   "role":false,
   "disposable":false,
   "score":0.64,
   "state":"undeliverable",
   "reason":"invalid_mx",
   "free":false,
   "format_valid":true,
   "catch_all":"None"
}

You can learn about the different keys in the response here. To determine if an email address is valid or invalid based on the JSON response from emailvalidation.io, you should check the following fields:

1. format_valid: If true, the email address is properly formatted. If false, the email address is not valid.
2. mx_found: If true, at least one MX record was found for the domain. If false, the domain is not valid.
3. smtp_check: If true, the email address has a valid mailbox. If false, the mailbox is not valid.
4. state: The current state of the email address. The values can be "deliverable" or "undeliverable".

Thus, you can modify the is_valid function to return a Boolean response instead of a JSON object as below:

import requests
from requests.structures import CaseInsensitiveDict


def is_valid(email: str):
    url = f"https://api.emailvalidation.io/v1/info?email={email}"

    headers = CaseInsensitiveDict()
    headers["apikey"] = "nUH1hmV24lEwX1TIXmsgRPRRZw0L0NuOeHrdMp78"

    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        json_resp = response.json()
        format_valid = json_resp["format_valid"]
        mx_found = json_resp["mx_found"]
        smtp_check = json_resp["smtp_check"]
        state = json_resp["state"]

        return format_valid and mx_found and smtp_check and state == "deliverable"

    return False


print(is_valid("support@emailvalidation.io"))
print(is_valid("venip42579@jdsdhak.com"))

Output:

True
False

In the upcoming section, you'll use this function to validate emails during user registration.

How to Set Up Basic User Authentication in Flask

In this section, you will go through the steps to set up basic user authentication in Flask. You will be using the code from one of my previous articles where I had explained how to implement basic user authentication.

You can start by pulling the code from the GitHub repository to the email-validation folder:

git init
git remote add origin https://github.com/ashutoshkrris/Flask-User-Authentication.git
git pull origin main

Note: The command git clone [https://github.com/ashutoshkrris/Flask-User-Authentication.git](https://github.com/ashutoshkrris/Flask-User-Authentication.git) . won't run in this case because your directory is not empty.

Next, you'll see a requirements.txt file that contains the dependencies to run the the application in your system. Install the dependencies using the command:

pip install -r requirements.txt

Once all the dependencies are installed, you'll need to add the environment variables required for the project. The project contains a .env file which has all the environment variables. Run the following command to export all the environment variables from the .env file:

source .env

Next, you have to create the database. Since the project uses Flask-Migrate, creating the database is a fairly simple task using the following commands:

python manage.py db init
python manage.py db migrate
python manage.py db upgrade

Now, you can run the application using the command:

python manage.py run

The application will start running and you can go to http://localhost:5000/login in your web browser to see the application.

Here's a demo video that shows the application:

Inside your project flask-validation, you'll have a src folder containing your source code and a tests folder containing the unit tests.

In addition to these, you'll also have a config.py file that contains the configuration settings for your application and a manage.py file that uses Flask-CLI to add different commands for running and testing your application. You'll also find other files such as .env and requirements.txt which you already know about.

The src folder contains four subfolders – accounts, core, templates, and static. The templates and static folders contain the HTML files and static files such as CSS, images, and JavaScript files, respectively. The other two folders, accounts and core, use the concept of Flask Blueprints and contain the respective codes for different parts of the application.

If you want to learn more about the implementation of your Flask application, you can refer to this tutorial.

How to Integrate the Email Validation Service in Your Flask App

Up until this point, it is possible to successfully register in the application using any email address, regardless of whether it is valid or not.

But it's not desirable to have random or incorrect email addresses cluttering up your database. So it's a good idea to validate the email address before registering the user. If the email address is valid, you can proceed with registering the user successfully.

Add your Email Validation API Key in the .env file to so that you can read it without exposing to the public:

export SECRET_KEY=fdkjshfhjsdfdskfdsfdcbsjdkfdsdf
export DEBUG=True
export APP_SETTINGS=config.DevelopmentConfig
export DATABASE_URL=sqlite:///db.sqlite
export FLASK_APP=src
export FLASK_DEBUG=1
export API_KEY=your-api-key-here

Replace the your-api-key-here with your correct API key. Next, you'll again need to run the following command to export the environment variables:

source .env

Now, create a utils.py file inside the accounts subfolder in the src folder. The file will contain the utility function to validate the email. Add the following code in the file:

import requests
from requests.structures import CaseInsensitiveDict
from decouple import config


def is_valid(email: str):
    url = f"https://api.emailvalidation.io/v1/info?email={email}"

    headers = CaseInsensitiveDict()
    headers["apikey"] = config("API_KEY")

    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        json_resp = response.json()
        format_valid = json_resp["format_valid"]
        mx_found = json_resp["mx_found"]
        smtp_check = json_resp["smtp_check"]
        state = json_resp["state"]

        return format_valid and mx_found and smtp_check and state == "deliverable"

    return False

As previously mentioned, the is_valid() function returns a Boolean value indicating whether an email address is valid or not. It's important to note that the function doesn't hardcode the API key value, instead it retrieves it from the environment variables.

Next, in the RegisterForm class in the forms.py file, you have a validate method. This method is responsible for validating the input data submitted by the user during the registration process.

Previously, this method only checked if the email was already registered and if the passwords matched. But you can now add an additional validation to check if the email is valid. Thus the modified validate method looks like this:

...

from src.accounts.utils import is_valid

...

class RegisterForm(FlaskForm):
    ...

    def validate(self):
        initial_validation = super(RegisterForm, self).validate()
        if not initial_validation:
            return False
        if not is_valid(self.email.data):
            self.email.errors.append("Email is invalid")
            return False
        user = User.query.filter_by(email=self.email.data).first()
        if user:
            self.email.errors.append("Email already registered")
            return False
        if self.password.data != self.confirm.data:
            self.password.errors.append("Passwords must match")
            return False
        return True

In the validate method, if the self.email.data (that is the user's email address) is not valid, you append an error message to the self.email.errors list and return False which means the user data is not valid.

Now, when you run the application and try to register, you can see it live. Here's a demo showing both valid and invalid cases.

Other Use Cases of an Email Validation Service

Apart from validating a user's email during registration, there are several other use cases for Email Validation Services. Some of these are:

1. Cleaning Email Lists: you can use email validation services to clean email lists by removing invalid, non-existent or risky email addresses. This can help to improve email deliverability and ensure that your emails reach the intended recipients.
2. Preventing Fraudulent Activities: you can also use email validation services to detect fraudulent activities such as fake account creation or fraudulent orders. By validating the email addresses associated with these activities, you can prevent such activities from happening.
3. Enhancing marketing campaigns: these services can also help improve the accuracy and effectiveness of email marketing campaigns. By ensuring that email addresses are valid and active, businesses can increase their email deliverability rates and improve their overall campaign performance.

Overall, email validation services can be a powerful tool in ensuring the accuracy and validity of user data, preventing fraud, and improving the user experience.

Conclusion

Email validation services are a powerful tool for any application that requires verifying user email addresses. It is essential to ensure that email addresses are valid to prevent errors and to ensure that the user input data is correct.

In this article, you saw how to use the emailvalidation.io API to validate an email address in Python. You also learned other potential use cases for email validation services, such as fraud detection and email marketing.

By implementing email validation services in your application, you can improve your user experience and ensure that your data is accurate and up-to-date.

Additional Resources

• How to Use Blueprints to Organize Your Flask Apps
• How to Set Up Email Verification in a Flask App
• emailvalidation.io Documentation

We just published a comprehensive video course on the freeCodeCamp.org YouTube channel that is designed to teach you how to build and deploy a production-ready database-driven web application using Python and Flask.

Akash created this course. He is the CEO of Jovian and he has created many popular courses.

The course is divided into two parts, each with its own set of objectives, covering everything from Flask basics to MySQL database setup, and application deployment.

In Part 1, you will learn how to build and deploy a site using the Flask Python web framework. You will start by creating a "Jovian Careers" website that lists job openings at Jovian.

You will also learn how to use a modern HTML & CSS framework for layout and styling, as well as how to deploy the website to the cloud and attach a custom domain. By the end of Part 1, you will have a working website that is ready to be connected to a database.

In Part 2, you will connect the Flask application from the first part to a cloud MySQL database, and learn how to deploy a production-ready database-driven web application. You will start by setting up the project and deployment, then move on to cloud MySQL database setup, and DB connection with SQLAlchemy.

You will learn how to display DB data on web pages, create dynamic database-driven pages, and build an HTML form for applications. Finally, you will learn how to save applications to the database, and wrap up the course by summarizing the topics covered and outlining future work.

By the end of the course, you will have the knowledge and skills needed to build and deploy a production-ready database-driven web application. This will not only enhance your skills as a developer but also open up new career opportunities. You will also have a deep understanding of Flask and MySQL, which will enable you to apply these skills to other projects.

So, if you're ready to take your web development skills to the next level, star watching this 5-hour course and continue your journey towards becoming a master web developer!

This central access point to your application’s data raises the question: how can you provide access to the information to those who need it while denying access to unauthorized requests?

The industry has provided several protocols and best practices for securing APIs. Today we will focus on OAuth2, one of the most popular options for authorizing clients into our APIs.

But how do we implement OAuth2? There are two ways to go about it:

1. Do it yourself approach
2. Work with a safe 3rd party like Auth0

In this article, I will walk you through an implementation of OAuth2 for Python and Flask using Auth0 as our identity provider. But first, we are going to discuss the do-it-yourself approach.

Why Not Build Your Own Authentication and Authorization?

For a few years now, I wanted to give back to the community that helped me so much by teaching me programming and helping me progress in my search for knowledge. I always thought that a great way to contribute was by having my own blog, a thing that I tried more than a few times and failed.

But where did I fail? Instead of focusing on writing, I tried to build my own blog engine because it’s in my nature. It’s what developers do. They love to build.

But why do I mention that here? Because many fall into the same trap when building APIs. Let me explain with an example.

Bob is a great developer, and he has this great idea for a ToDo app that can be the next big thing. Bob is very aware that for a successful implementation, users can only access their own data.

Here is bob’s application timeline:

• Sprint 0: Research ideas and start prototyping
• Sprint 1: Build user table and login screen with API
• Sprint 2: Add password reset screens and build all email templates
• Sprint 3: Build, create and list ToDos screens
• Sprint 4: MVP goes live
• User feedback:
  • Some users can’t log in due to a bug
  • Some users feel unsafe without 2-factor authentication
  • Some users don’t want to get yet another password. They prefer single sign-on with Google or Facebook.
  • …

Let’s talk about what happened. Bob spent the first few sprints not building his app but building the basic blocks, like logging in and out functionality, email notifications, and so on. This valuable time could have been spent differently, but what happens next is more concerning.

Bob’s backlog starts to fill in. Now, he needs to improvise a 2-factor authentication method, add single sign-on, and more non-product-related functions that could potentially delay his product.

And there’s still a big question to be answered: did Bob implement all the security mechanisms correctly? A critical error could expose all the user’s information to outsiders.

What Bob did is what I did with my blog many times. Sometimes, it's helpful to rely on 3rd parties if we want to get things done right.

Today, hackers and attacks have become so sophisticated that security is not a trivial factor anymore. It is a complicated system on its own, and it is often best to leave its implementation to experts – not only so it’s done right, but also so we can focus on what matters: building our applications and APIs.

How to Set Up a Free Auth0 Identity Management Account

Auth0 is a leading authentication and authorization provider, but let’s see how it can help Bob (or you) build a better app:

1. It saves time
2. It’s secure
3. It has a free plan

Time to get practical. First, make sure you have an Auth0 account. If not, you can create one here for free.

Create a New Auth0 API

There is still one more thing we have to do before we start coding. Head over to the APIs section of your Auth0 dashboard and click on the “Create API” button. After that, fill in the form with your details. However, make sure you select RS256 as the Signing Algorithm.

Your form should look like the following:

Creating the API – image showing fields to fill out

The API details page opens after successfully creating an API. Keep that tab open, as it contains information we need to set up our application. If you close it, don’t worry, you can always access it again.

How to Bootstrap our Application

Because we will focus on the security aspects only, we will take a few shortcuts when building our demo API. However, when developing actual APIs, please follow best practices for Flask APIs.

Install the dependencies

First, install the following dependencies for setting up Flask and authenticating users.

pipenv install flask python-dotenv python-jose flask-cors six

Build the endpoints

Our API will be straightforward. It will consist of only three endpoints, all of which, for now, will be publicly accessible. However, we will fix that soon. Here are our endpoints:

• / (public endpoint)
• /user (requires a logged in user)
• /admin (only users of admin role)

Let’s get to it:

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index_view():
    """
    Default endpoint, it is public and can be accessed by anyone
    """
    return jsonify(msg="Hello world!")

@app.route("/user")
def user_view():
    """
    User endpoint, can only be accessed by an authorized user
    """
    return jsonify(msg="Hello user!")

@app.route("/admin")
def admin_view():
    """
    Admin endpoint, can only be accessed by an admin
    """
    return jsonify(msg="Hello admin!")

Very simple right? Let’s run it:

~ pipenv run flask run
* 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)

And if we access our endpoint:

~ curl -i http://localhost:5000
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:24:57 GMT

{"msg":"Hello world!"}

~ curl -i http://localhost:5000/user
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 22
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:25:42 GMT

{"msg":"Hello user!"}

~ curl -i http://localhost:5000/admin
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:26:18 GMT

{"msg":"Hello admin!"}

How to Secure the Endpoints

As we are using OAuth, we will authenticate requests by validating an access token in JWT format. We'll send it to the API on each request as part of the HTTP headers.

Auth0 configuration variables

As mentioned in the previous section, our API needs to be aware and will require information from our Auth0 dashboard. So head back to your API details page, and grab two different values.

First, the API Identifier:

This is the value required when the API is created. You can also get it from your API details page:

How to find the API identifier on the API details page

Next, Auth0 domain:

Unless you're using a custom domain, this value will be [TENANT_NAME].auth0.com, and you can grab it from the Test tab (make sure not to include https:// and the last forward slash /).

Getting the Auth0 domain

Next, pass those values into variables so they can be used in the validation functions.

AUTH0_DOMAIN = 'YOUR-AUTH0-DOMAIN'
API_IDENTIFIER = 'API-IDENTIFIER'
ALGORITHMS = ["RS256"]

Error methods

During this implementation, we will need a way to throw errors when authentication fails. So we will use the following helpers for those needs:

class AuthError(Exception):
    def __init__(self, error, status_code):
        self.error = error
        self.status_code = status_code

@app.errorhandler(AuthError)
def handle_auth_error(ex):
    response = jsonify(ex.error)
    response.status_code = ex.status_code
    return response

How to capture the JWT token

The first step to validate a user is to retrieve the JWT token from the HTTP headers. This is very simple, but there are a few things to keep in mind. Here is an example of it:

def get_token_auth_header():
    """
    Obtains the Access Token from the Authorization Header
    """
    auth = request.headers.get("Authorization", None)
    if not auth:
        raise AuthError({"code": "authorization_header_missing",
                        "description":
                            "Authorization header is expected"}, 401)

    parts = auth.split()

    if parts[0].lower() != "bearer":
        raise AuthError({"code": "invalid_header",
                        "description":
                            "Authorization header must start with"
                            " Bearer"}, 401)
    elif len(parts) == 1:
        raise AuthError({"code": "invalid_header",
                        "description": "Token not found"}, 401)
    elif len(parts) > 2:
        raise AuthError({"code": "invalid_header",
                        "description":
                            "Authorization header must be"
                            " Bearer token"}, 401)

    token = parts[1]
    return token

How to validate the token

Having a token passed to our API is a good sign, but it doesn’t mean that it is a valid client. We need to check the token signature.

Since the logic to require authentication can be used for more than one endpoint, it would be important to abstract it and make it easily accessible for developers to implement. The best way to do this is by using decorators.

def requires_auth(f):
    """
    Determines if the Access Token is valid
    """
    @wraps(f)
    def decorated(*args, **kwargs):
        token = get_token_auth_header()
        jsonurl = urlopen("https://"+AUTH0_DOMAIN+"/.well-known/jwks.json")
        jwks = json.loads(jsonurl.read())
        unverified_header = jwt.get_unverified_header(token)
        rsa_key = {}
        for key in jwks["keys"]:
            if key["kid"] == unverified_header["kid"]:
                rsa_key = {
                    "kty": key["kty"],
                    "kid": key["kid"],
                    "use": key["use"],
                    "n": key["n"],
                    "e": key["e"]
                }
        if rsa_key:
            try:
                payload = jwt.decode(
                    token,
                    rsa_key,
                    algorithms=ALGORITHMS,
                    audience=API_IDENTIFIER,
                    issuer="https://"+AUTH0_DOMAIN+"/"
                )
            except jwt.ExpiredSignatureError:
                raise AuthError({"code": "token_expired",
                                "description": "token is expired"}, 401)
            except jwt.JWTClaimsError:
                raise AuthError({"code": "invalid_claims",
                                "description":
                                    "incorrect claims,"
                                    "please check the audience and issuer"}, 401)
            except Exception:
                raise AuthError({"code": "invalid_header",
                                "description":
                                    "Unable to parse authentication"
                                    " token."}, 401)

            _request_ctx_stack.top.current_user = payload
            return f(*args, **kwargs)
        raise AuthError({"code": "invalid_header",
                        "description": "Unable to find appropriate key"}, 401)
    return decorated

The newly created requires_auth decorator, when applied to an endpoint, will automatically reject the request if no valid user can be authenticated.

How to require an authenticated request for an endpoint

We are ready to secure our endpoints, let’s update the user and admin endpoints to utilize our decorator.

@app.route("/user")
@requires_auth
def user_view():
    """
    User endpoint, can only be accessed by an authorized user
    """
    return jsonify(msg="Hello user!")

@app.route("/admin")
@requires_auth
def admin_view():
    """
    Admin endpoint, can only be accessed by an admin
    """
    return jsonify(msg="Hello admin!")

Our only change was adding @required_auth at the top of the declaration of each endpoint function, and with that we can test once again:

~ curl -i http://localhost:5000/user
HTTP/1.0 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 89
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:42:26 GMT

{"code":"authorization_header_missing","description":"Authorization header is expected"}

~ curl -i http://localhost:5000/admin
HTTP/1.0 401 UNAUTHORIZED
Content-Type: application/json
Content-Length: 89
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:42:42 GMT

{"code":"authorization_header_missing","description":"Authorization header is expected"}

As expected, we can’t access our endpoints as the authorization header is missing. But before we add one, let’s see if our public endpoint still works:

~ curl -i http://localhost:5000
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 21:43:55 GMT

{"msg":"Hello world!"}

Awesome, it works as expected.

How to test it out

For testing our newly secured endpoints, we need to get a valid access token that we can pass to the request. We can do that directly on the Test tab on the API details page, and it’s as simple as copying a value from the screen:

Copying the token for testing

Once we have the token we can change our curl request accordingly:

~ curl -i -H "Authorization: bearer [ACCESS_TOKEN]"  http://localhost:5000/user
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 22
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 22:17:06 GMT

{"msg":"Hello user!"}

Please remember to replace [ACCESS_TOKEN] with the value you copied from the dashboard.

It works! But we still have some work to do. Even though our /admin endpoint is secured, it can be accessed by any user:

~ curl -i -H "Authorization: bearer [ACCESS_TOKEN]"  http://localhost:5000/admin
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 23
Server: Werkzeug/2.0.1 Python/3.9.1
Date: Tue, 24 Jan 2023 22:21:09 GMT

{"msg":"Hello admin!"}

Role-based access control

For role-based access control there’s a few things we need to do:

1. Create permissions for the API
2. Enable adding permissions to the JWT for the API
3. Update the code
4. Test with users

The first 2 points are very well explained in the Auth0 docs, so just make sure you add the corresponding permissions on your API.

Next, we need to update the code. We need a function to check if a given permission exists in the access token and return True if it does and False if it does not:

def requires_scope(required_scope):
    """
    Determines if the required scope is present in the Access Token
    Args:
        required_scope (str): The scope required to access the resource
    """
    token = get_token_auth_header()
    unverified_claims = jwt.get_unverified_claims(token)
    if unverified_claims.get("scope"):
            token_scopes = unverified_claims["scope"].split()
            for token_scope in token_scopes:
                if token_scope == required_scope:
                    return True
    return False

And lastly, it can be used as follows:

@app.route("/admin")
@requires_auth
def admin_view():
    """
    Admin endpoint, can only be accessed by an admin
    """
    if requires_scope("read:admin"):
        return jsonify(msg="Hello admin!")

    raise AuthError({
        "code": "Unauthorized",
        "description": "You don't have access to this resource"
    }, 403)

Now, only users with the permission read:admin can access our admin endpoint.

In order to test your final implementation, you can follow the steps detailed on obtaining an access token for a given user.

You can also use the Auth0 Dashboard to test permissions, but that is outside the scope of this article. If you would like to learn more about it, read here.

Conclusion

Today we learned how to secure a Flask API. We explored the do-it-yourself path, and we built a secure API with three levels of access – public access, private access and privately-scoped access.

There’s so much more that Auth0 can do for your APIs and also for your client applications. Today we just scratched the surface, and it’s up to you and your team when working with real-life scenarios to explore all the potential of their services.

The full code is available on GitHub.

Thanks for reading! If you like my teaching style, you can Subscribe to my weekly newsletter for developers and builders and get a weekly email with relevant content.

In this article, we will explore the process of handling email verification in Flask. The topic will include setting up a route to handle the email verification process, and storing the verification status in a database.

By the end of this article, you will have a thorough understanding of how to implement email verification in your own Flask application.

Before getting started, make sure you have a good understanding of basic user authentication in Flask. You can go through this tutorial to learn more.

Project Demo

Here’s what you're going to build in this tutorial:

The link to the GitHub repository is available at the end of the tutorial. Feel free to check it out whenever you're stuck.

Flask Basic User Authentication

To begin, you will use a Flask boilerplate that includes basic user authentication. You can get the code from this repository. After creating and activating a virtual environment, run the following command to install all the dependencies:

$ pip install -r requirements.txt

Create a file named .env in the root directory and add the following content there:

export SECRET_KEY=fdkjshfhjsdfdskfdsfdcbsjdkfdsdf
export DEBUG=True
export APP_SETTINGS=config.DevelopmentConfig
export DATABASE_URL=sqlite:///db.sqlite
export FLASK_APP=src
export FLASK_DEBUG=1

Run the following command to export all the environment variables from the .env file:

source .env

Run the following commands to set up the database:

flask db init
flask db upgrade

Run the following command to run the Flask server:

python manage.py run

Once the app is running, go to http://localhost:5000/register to register a new user. You will notice that after completing the registration, the app will automatically log you in and redirect you to the main page.

Before proceeding, I'd recommend exploring the app and then reviewing the code, particularly the accounts blueprint. This will give you a better understanding of how the user authentication is implemented.

How to Modify the Current Implementation

In this section, you will modify the existing implementation of user authentication in our Flask app.

Models

First of all, you'll need to add two new fields – is_confirmed and confirmed_on in the User model of your app.

Open the src/accounts/models.py file and update the User class with the following:

class User(UserMixin, db.Model):

    __tablename__ = "users"

    id = db.Column(db.Integer, primary_key=True)
    email = db.Column(db.String, unique=True, nullable=False)
    password = db.Column(db.String, nullable=False)
    created_on = db.Column(db.DateTime, nullable=False)
    is_admin = db.Column(db.Boolean, nullable=False, default=False)
    is_confirmed = db.Column(db.Boolean, nullable=False, default=False)
    confirmed_on = db.Column(db.DateTime, nullable=True)

    def __init__(
        self, email, password, is_admin=False, is_confirmed=False, confirmed_on=None
    ):
        self.email = email
        self.password = bcrypt.generate_password_hash(password)
        self.created_on = datetime.now()
        self.is_admin = is_admin
        self.is_confirmed = is_confirmed
        self.confirmed_on = confirmed_on

    def __repr__(self):
        return f"<email {self.email}>"

The is_confirmed is a boolean field to indicate whether the user's email address has been confirmed, set as not nullable and defaulting to False. The confirmed_on is a datetime field for the time when the user's email was confirmed, set as nullable.

To migrate and apply these changes in the database, run the following commands:

flask db migrate
flask db upgrade

How to create the admin

Next, in the manage.py file, update the create_admin command to take the new database fields into account:

@cli.command("create_admin")
def create_admin():
    """Creates the admin user."""
    email = input("Enter email address: ")
    password = getpass.getpass("Enter password: ")
    confirm_password = getpass.getpass("Enter password again: ")
    if password != confirm_password:
        print("Passwords don't match")
    else:
        try:
            user = User(
                email=email,
                password=password,
                is_admin=True,
                is_confirmed=True,
                confirmed_on=datetime.now(),
            )
            db.session.add(user)
            db.session.commit()
            print(f"Admin with email {email} created successfully!")
        except Exception:
            print("Couldn't create admin user.")

Notice that the is_confirmed field is set to True in this case because you don't want the admin to verify their account.

How to add a new decorator to check if the user is logged out

If you notice the register() and login() function in src/accounts/views.py, you'll find the below code in both of them:

if current_user.is_authenticated:
    flash("You are already registered.", "info")
    return redirect(url_for("core.home"))

The code checks whether a user is already logged in. If the user is authenticated, a message is displayed using the flash function and the user is redirected to the home page using the redirect function from Flask.

If the user is not authenticated, they will be allowed to continue with the process they were trying to complete. This essentially means you require the user to be logged out to continue the flow.

Instead of repeating the code at two places, you can create a decorator to check if the user is logged out.

Create a new utils folder in the src folder, and a decorators.py file in the utils folder with the following content:

from functools import wraps

from flask import flash, redirect, url_for
from flask_login import current_user


def logout_required(func):
    @wraps(func)
    def decorated_function(*args, **kwargs):
        if current_user.is_authenticated:
            flash("You are already authenticated.", "info")
            return redirect(url_for("core.home"))
        return func(*args, **kwargs)

    return decorated_function

The above code defines a decorator called logout_required which is used to wrap routes in a Flask app.

If the user is authenticated, a message is displayed using the flash function and the user is redirected to the home page using the redirect function from Flask. If the user is not authenticated, they will be allowed to continue and the decorated route function will be executed.

Now, you can use this decorator in the register() and login() function as below:

from src.utils.decorators import logout_required


@accounts_bp.route("/register", methods=["GET", "POST"])
@logout_required
def register():
    ...


@accounts_bp.route("/login", methods=["GET", "POST"])
@logout_required
def login():
    ...

How to Add Email Verification to Your Flask App

In this section, you will learn how to add email verification to your Flask app.

Confirmation token

The email confirmation should contain a unique URL that the user can click to confirm their account. The URL should be in the following format: http://localhost:5000/confirm/<id>.

The <id> portion of the URL is a unique identifier that is generated using the user's email address and a timestamp. We can use the itsdangerous package to encode this information in the <id>. When the user clicks the link, the app can decode the <id> to retrieve the user's email address and verify their account.

To provide an additional layer of security to the token, the itsdangerours package requires a password salt. You can set an environment variable for the same in the .env file:

other env vars...
export SECURITY_PASSWORD_SALT=fkslkfsdlkfnsdfnsfd

Run the following command to export the environment variable from the .env file:

source .env

Add the SECURITY_PASSWORD_SALT to your app’s config (Config) in the config.py file:

class Config:
    ...other configs
    SECURITY_PASSWORD_SALT = config("SECURITY_PASSWORD_SALT", default="very-important")

Create a src/accounts/token.py file and add the following code:

from itsdangerous import URLSafeTimedSerializer

from src import app


def generate_token(email):
    serializer = URLSafeTimedSerializer(app.config["SECRET_KEY"])
    return serializer.dumps(email, salt=app.config["SECURITY_PASSWORD_SALT"])


def confirm_token(token, expiration=3600):
    serializer = URLSafeTimedSerializer(app.config["SECRET_KEY"])
    try:
        email = serializer.loads(
            token, salt=app.config["SECURITY_PASSWORD_SALT"], max_age=expiration
        )
        return email
    except Exception:
        return False

This code defines two functions for generating and confirming tokens for email verification in a Flask app:

The generate_token function takes an email address as an argument and returns a token that is generated using the URLSafeTimedSerializer class from the itsdangerous package.

The URLSafeTimedSerializer class is initialized with the app's secret key, which is stored in the SECRET_KEY configuration variable. The dumps method of the URLSafeTimedSerializer instance is called with the email address and a password salt as arguments. As mentioned earlier, the password salt is stored in the SECURITY_PASSWORD_SALT configuration variable.

The confirm_token function takes a token and an optional expiration time as arguments and returns the email address that was used to generate the token.

The URLSafeTimedSerializer instance is initialized with the app's secret key, and the loads method is called with the token, password salt, and expiration time as arguments.

If the token is valid and has not expired, the email address is returned. If the token is invalid or has expired, an exception is raised and caught by the except block, causing the function to return False.

How to update the register() function

When the user registers, you need to generate a token using the email address of the user.

from src.accounts.token import confirm_token, generate_token


@accounts_bp.route("/register", methods=["GET", "POST"])
@logout_required
def register():
    form = RegisterForm(request.form)
    if form.validate_on_submit():
        user = User(email=form.email.data, password=form.password.data)
        db.session.add(user)
        db.session.commit()

        token = generate_token(user.email)

        ...

The token variable will be used while sending an email to the user with the token included in the email's URL.

How to handle email confirmation

To confirm the email, create a new view function in the src/accounts/views.py file:

@accounts_bp.route("/confirm/<token>")
@login_required
def confirm_email(token):
    if current_user.is_confirmed:
        flash("Account already confirmed.", "success")
        return redirect(url_for("core.home"))
    email = confirm_token(token)
    user = User.query.filter_by(email=current_user.email).first_or_404()
    if user.email == email:
        user.is_confirmed = True
        user.confirmed_on = datetime.now()
        db.session.add(user)
        db.session.commit()
        flash("You have confirmed your account. Thanks!", "success")
    else:
        flash("The confirmation link is invalid or has expired.", "danger")
    return redirect(url_for("core.home"))

The above code defines a route for the confirm_email view function in a Flask app. The route is decorated with the @login_required decorator, which requires the user to be logged in to access the view. The route takes a token argument, which is included in the URL of the route.

The view function first checks if the user's account is already confirmed. If the account is already confirmed, a message is displayed using the flash function from the Flask-Babel library and the user is redirected to the home page using the redirect function from Flask.

If the account is not confirmed, the confirm_token function is called with the token as an argument to confirm the token and retrieve the email address that was used to generate the token. If the token is invalid or has expired, the confirm_token function returns False, and a message is displayed indicating that the confirmation link is invalid or has expired.

If the token is valid, the user's account is confirmed by setting the is_confirmed field to True and the confirmed_on field to the current time. The changes are then committed to the database. A message is displayed indicating that the account has been confirmed, and the user is redirected to the home page.

How to send email confirmation

Let's first create a basic email template that will be used while sending the email. Create a templates/accounts/confirm_email.html file and add the following code:

<p>
  Welcome! Thanks for signing up. Please follow this link to activate your
  account:
</p>
<p><a href="{{ confirm_url }}">{{ confirm_url }}</a></p>
<br />
<p>Cheers!</p>

The confirm_url placeholder is used to insert a URL into the email message. When the template is rendered, the confirm_url placeholder is replaced with the actual URL that the user should visit to confirm their account.

How to set up Flask-Mail

Next, you'll need a library called Flask-Mail to send out emails using Flask.

Install the library using the pip command:

pip install Flask-Mail

Initialize the Flask-Mail library inside the src/__init__.py file as:

...other imports...
from flask_mail import Mail

...other initializations...
mail = Mail(app)
...

You can set environment variables for your email and password that will be used to send emails in the .env file:

export EMAIL_USER=your-email
export EMAIL_PASSWORD=your-password

Run the following command to export the environment variables from the .env file:

source .env

Update the Config class in the config.py file:

class Config(object):
    ...other configs

    # Mail Settings
    MAIL_DEFAULT_SENDER = "noreply@flask.com"
    MAIL_SERVER = "smtp.gmail.com"
    MAIL_PORT = 465
    MAIL_USE_TLS = False
    MAIL_USE_SSL = True
    MAIL_DEBUG = False
    MAIL_USERNAME = config("EMAIL_USER")
    MAIL_PASSWORD = config("EMAIL_PASSWORD")

Note: If your Gmail account has 2-step authentication, Google will block the attempt. Use an app password to sign in.

How to create a function to send email

Next, create a email.py file in the src/utils folder and add the following code:

from flask_mail import Message

from src import app, mail


def send_email(to, subject, template):
    msg = Message(
        subject,
        recipients=[to],
        html=template,
        sender=app.config["MAIL_DEFAULT_SENDER"],
    )
    mail.send(msg)

The function takes three arguments: the recipient's email address (to), the subject of the email (subject), and the body of the email (template).

The Message class from the Flask-Mail library is used to create a new email message with the specified subject and recipient. The html argument is used to set the body of the email to the provided template, which is expected to be an HTML string. The sender argument is used to specify the default sender for the email, which is stored in the MAIL_DEFAULT_SENDER configuration variable.

The send method of the mail object is then called with the message object as an argument to send the email.

How to send the email (finally)

Let's finally send the confirmation email from the register() function:

from src.utils.email import send_email


@accounts_bp.route("/register", methods=["GET", "POST"])
@logout_required
def register():
    form = RegisterForm(request.form)
    if form.validate_on_submit():
        user = User(email=form.email.data, password=form.password.data)
        db.session.add(user)
        db.session.commit()
        token = generate_token(user.email)
        confirm_url = url_for("accounts.confirm_email", token=token, _external=True)
        html = render_template("accounts/confirm_email.html", confirm_url=confirm_url)
        subject = "Please confirm your email"
        send_email(user.email, subject, html)

        login_user(user)

        flash("A confirmation email has been sent via email.", "success")
        return redirect(url_for("accounts.inactive"))

    return render_template("accounts/register.html", form=form)

The url_for function is then called to generate a URL for the confirm_email route with the token as an argument. The _external argument is set to True to generate an absolute URL with the full domain name. The render_template function is called to render an HTML template for the email message, using the confirm_url as a placeholder in the template.

The send_email function is then called to send the email with the rendered template as the body, using the user's email address as the recipient and a subject of "Please confirm your email".

Finally, the user is logged in using the login_user function from the Flask-Login library and a message is displayed indicating that a confirmation email has been sent. The user is then redirected to the inactive view. You'll create it later.

A sample email looks like this:

How to Handle Inactive Accounts

Whenever you create a new account, you're redirected to a view called inactive where you're asked to confirm your account.

Let's create a view function in the src/accounts/views.py file:

@accounts_bp.route("/inactive")
@login_required
def inactive():
    if current_user.is_confirmed:
        return redirect(url_for("core.home"))
    return render_template("accounts/inactive.html")

The view function checks if the user's account is confirmed. If the account is confirmed, the user is redirected to the home page using the redirect function from Flask. If the account is not confirmed, the inactive.html template is rendered using the render_template function from Flask.

Let's create the inactive.html file in templates/accounts folder:

{% extends "_base.html" %} {% block content %}

<div class="text-center">
  <h1>Welcome!</h1>
  <br />
  <p>
    You have not confirmed your account. Please check your inbox (and your spam
    folder) - you should have received an email with a confirmation link.
  </p>
  <p>
    Didn't get the email?
    <a href="{{ url_for('accounts.resend_confirmation') }}">Resend</a>.
  </p>
</div>

{% endblock %}

The template includes a link to the resend_confirmation route.

How to resend the email

Consider a case where the user was not able to confirm the account before the expiration time of the token. As a user, you'll want to have an option to resend the email, right?

Create a new view function in the src/accounts/views.py:

@accounts_bp.route("/resend")
@login_required
def resend_confirmation():
    if current_user.is_confirmed:
        flash("Your account has already been confirmed.", "success")
        return redirect(url_for("core.home"))
    token = generate_token(current_user.email)
    confirm_url = url_for("accounts.confirm_email", token=token, _external=True)
    html = render_template("accounts/confirm_email.html", confirm_url=confirm_url)
    subject = "Please confirm your email"
    send_email(current_user.email, subject, html)
    flash("A new confirmation email has been sent.", "success")
    return redirect(url_for("accounts.inactive"))

This code defines a route for the resend_confirmation view function in a Flask app. The route is decorated with the login_required decorator, which requires the user to be logged in to access the view.

The view function first checks if the user's account is already confirmed. If the account is confirmed, a message is displayed indicating that the account has already been confirmed and the user is redirected to the home page.

If the account is not confirmed, a token is generated as earlier. The url_for function is then called to generate a URL for the confirm_email route with the token as an argument. The send_email function is then called to send the email with the rendered template as the body, using the user's email address as the recipient and a subject of "Please confirm your email". A message is displayed indicating that a new confirmation email has been sent, and the user is redirected to the inactive view.

How to add middleware for routes

Now that you have the email verification mechanism ready, you want your routes in the core package to be accessed by only users with a confirmed account. To do that, you can add a decorator on those routes.

Create a new decorator in the src/utils/decorators.py file:

def check_is_confirmed(func):
    @wraps(func)
    def decorated_function(*args, **kwargs):
        if current_user.is_confirmed is False:
            flash("Please confirm your account!", "warning")
            return redirect(url_for("accounts.inactive"))
        return func(*args, **kwargs)

    return decorated_function

This code defines a decorator called check_is_confirmed. The decorator takes a function as an argument and returns a decorated function.

The decorator works by checking if the user's account is confirmed. If the account is not confirmed, a message is displayed warning the user to confirm their account, and the user is redirected to the inactive view. If the account is confirmed, the decorated function is called as usual.

Now, you can use this decorator in the home view function in src/core/views.py file:

from src.utils.decorators import check_is_confirmed


@core_bp.route("/")
@login_required
@check_is_confirmed
def home():
    return render_template("core/index.html")

This is how it looks when you login, and your account is not verified:

How to Add New Test Cases

Now that you have added the main functionality, it's time to update the test suite.

How to modify the setUp() method in base_test.py

Replace the setUp() method with the following code:

def setUp(self):
    db.create_all()
    unconfirmed_user = User(email="unconfirmeduser@gmail.com",
                                password="unconfirmeduser")
    db.session.add(unconfirmed_user)
    confirmed_user = User(email="confirmeduser@gmail.com",
                              password="confirmeduser", is_confirmed=True)
    db.session.add(confirmed_user)
    db.session.commit()

The method now creates two users – a user with a confirmed account and another user without a confirmed account.

Note that you'll need to replace the usage of the old email address and password with the unconfirmed user's email address and password in all the test files.

How to add new test cases in test_routes.py

Since unauthenticated users cannot access the home page, let's add a test case in the TestLoggingInOut class to see if the user is redirected to the login page:

def test_home_route_requires_login(self):
    self.client.get("/logout", follow_redirects=True)
    self.client.get('/', follow_redirects=True)
    self.assertTemplateUsed('accounts/login.html')

Create a new TestEmailConfirmationToken class in the same file:

class TestEmailConfirmationToken(BaseTestCase):
    def test_confirm_token_route_requires_login(self):
        # Ensure confirm/<token> route requires logged in user.
        self.client.get("/logout", follow_redirects=True)
        self.client.get('/confirm/some-unique-id', follow_redirects=True)
        self.assertTemplateUsed('accounts/login.html')

    def test_confirm_token_route_valid_token(self):
        # Ensure user can confirm account with valid token.
        with self.client:
            self.client.get("/logout", follow_redirects=True)
            self.client.post('/login', data=dict(
                email='unconfirmeduser@gmail.com', password='unconfirmeduser'
            ), follow_redirects=True)
            token = generate_token('unconfirmeduser@gmail.com')
            response = self.client.get(
                '/confirm/'+token, follow_redirects=True)
            self.assertIn(
                b'You have confirmed your account. Thanks!', response.data)
            self.assertTemplateUsed('core/index.html')
            user = User.query.filter_by(
                email='unconfirmeduser@gmail.com').first_or_404()
            self.assertIsInstance(user.confirmed_on, datetime)
            self.assertTrue(user.is_confirmed)

    def test_confirm_token_route_invalid_token(self):
        # Ensure user cannot confirm account with invalid token.
        token = generate_token('test@test1.com')
        with self.client:
            self.client.get("/logout", follow_redirects=True)
            self.client.post('/login', data=dict(
                email='unconfirmeduser@gmail.com', password='unconfirmeduser'
            ), follow_redirects=True)
            response = self.client.get('/confirm/'+token,
                                       follow_redirects=True)
            self.assertIn(
                b'The confirmation link is invalid or has expired.',
                response.data
            )

    def test_confirm_token_route_expired_token(self):
        # Ensure user cannot confirm account with expired token.
        user = User(email='test@test1.com', password='test1')
        db.session.add(user)
        db.session.commit()
        token = generate_token('test@test1.com')
        self.assertFalse(confirm_token(token, -1))

The above code tests the email verification functionality of the app.

• The test_confirm_token_route_requires_login test case tests that when a user tries to access the confirmation route when not logged in, they are redirected to the login page.
• The test_confirm_token_route_valid_token test case tests that when a user tries to access the confirmation route with a valid token, their account is confirmed and they are redirected to the index page.
• The test_confirm_token_route_invalid_token test case tests that when a user tries to access the confirmation route with an invalid token, an error message is displayed.
• The test_confirm_token_route_expired_token test case tests that when a user tries to access the confirmation route with an expired token, an error message is displayed.

Wrapping up

In this tutorial, you learned how to handle email verification in your Flask app. You also wrote few more testcases in order to test the new functionalities.

Here's the link to the GitHub repository. Feel free to check it out whenever you're stuck.

Recommended next steps

• You can add a "forgot password" feature in the application.
• You can allow users to manage their profiles.
• You can add more testcases in order to test the app more thoroughly.

Thank you for reading. I hope you found this article useful. You can follow me on Twitter.

There are different methods for implementing user authentication, including password-based authentication, token-based authentication, and so on.

In this tutorial, you will learn how to set up basic user authentication – that is password-based authentication – in your Flask application.

Project Demo

Here’s what the final output will look like:

The link to the GitHub repository is available at the end of the tutorial. Feel free to check it out whenever you're stuck.

Prerequisites

Before you get started with the tutorial, make sure you have the following requirements satisfied:

• Working knowledge of Python
• Python 3.8+ installed on your system
• Basic knowledge of Flask and Flask Blueprints

Get Your Tools Ready

You'll need a few external libraries in this project. Let's learn more about them and install them one by one.

But before we install them, let's create a virtual environment and activate it.

First, start with creating the project directory and navigating to it like this:

mkdir flask-basic-auth
ccd flask-basic-auth

We are going to create a virtual environment using venv. Python now ships with a pre-installed venv library. So, to create a virtual environment, you can use the below command:

python -m venv env

The above command will create a virtual environment named env. Now, we need to activate the environment using this command:

source env/Scripts/activate

To verify if the environment has been activated or not, you can see (env) in your terminal. Now, we can install the libraries.

• Flask is a simple, easy-to-use microframework for Python that helps you build scalable and secure web applications.
• Flask-Login provides user session management for Flask. It handles the common tasks of logging in, logging out, and remembering your users’ sessions over extended periods of time.
• Flask-Bcrypt is a Flask extension that provides bcrypt hashing utilities for your application.
• Flask-WTF is a simple integration of Flask and WTForms that helps you create forms in Flask.
• Flask-Migrate is an extension that handles SQLAlchemy database migrations for Flask applications using Alembic. The database operations are made available through the Flask command-line interface.
• Flask-SQLAlchemy is an extension for Flask that adds support for SQLAlchemy to your application. It helps you simplify things using SQLAlchemy with Flask by giving you useful defaults and extra helpers that make it easier to perform common tasks.
• Flask-Testing extension provides unit testing utilities for Flask.
• Python Decouple helps you use environment variables in your Python project.

To install the above-mentioned libraries, run the following command:

pip install Flask Flask-Login Flask-Bcrypt Flask-WTF FLask-Migrate Flask-SQLAlchemy Flask-Testing python-decouple

This tutorial was verified with Python V3.11, Flask V2.2.2, Flask-Login V0.6.0, Flask-Bcrypt V1.0.1, Flask-WTF V1.0.1, Flask-SQLAlchemy V2.5.1 and, Flask-Testing V0.8.1.

How to Set Up the Project

Let’s start by creating a src directory:

mkdir src

The first file will be the __init__.py file for the project:

from decouple import config
from flask import Flask
from flask_bcrypt import Bcrypt
from flask_migrate import Migrate
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config.from_object(config("APP_SETTINGS"))

bcrypt = Bcrypt(app)
db = SQLAlchemy(app)
migrate = Migrate(app, db)

# Registering blueprints
from src.accounts.views import accounts_bp
from src.core.views import core_bp

app.register_blueprint(accounts_bp)
app.register_blueprint(core_bp)

In the above script, we created a Flask app called app . We use the __name__ argument to indicate the app's module or package so that Flask knows where to find other files such as templates. You also set the configuration of the app using an environment variable called APP_SETTINGS. You'll export it later.

To use Flask-Bcrypt, Flask-SQLAlchemy, and Flask-Migrate in your application, you just need to create objects of the Bcrypt, SQLAlchemy and Migrate classes from the flask_bcrypt, flask_sqlalchemy and, flask_migrate libraries, respectively.

You've also registered blueprints called accounts_bp and core_bp in the application. You'll define them later in the tutorial.

In the root directory of the project (that is, outside the src directory), create a file called config.py. We'll store the configurations for the project in this file. Within the file, add the following content:

from decouple import config

DATABASE_URI = config("DATABASE_URL")
if DATABASE_URI.startswith("postgres://"):
    DATABASE_URI = DATABASE_URI.replace("postgres://", "postgresql://", 1)


class Config(object):
    DEBUG = False
    TESTING = False
    CSRF_ENABLED = True
    SECRET_KEY = config("SECRET_KEY", default="guess-me")
    SQLALCHEMY_DATABASE_URI = DATABASE_URI
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    BCRYPT_LOG_ROUNDS = 13
    WTF_CSRF_ENABLED = True
    DEBUG_TB_ENABLED = False
    DEBUG_TB_INTERCEPT_REDIRECTS = False


class DevelopmentConfig(Config):
    DEVELOPMENT = True
    DEBUG = True
    WTF_CSRF_ENABLED = False
    DEBUG_TB_ENABLED = True


class TestingConfig(Config):
    TESTING = True
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///testdb.sqlite"
    BCRYPT_LOG_ROUNDS = 1
    WTF_CSRF_ENABLED = False


class ProductionConfig(Config):
    DEBUG = False
    DEBUG_TB_ENABLED = False

In the above script, we have created a Config class and defined various attributes inside that. Also, we have created different child classes (as per different stages of development) that inherit the Config class.

Notice that we're using a few environment variables like SECRET_KEY and DATABASE_URL. Create a file named .env in the root directory and add the following content there:

export SECRET_KEY=fdkjshfhjsdfdskfdsfdcbsjdkfdsdf
export DEBUG=True
export APP_SETTINGS=config.DevelopmentConfig
export DATABASE_URL=sqlite:///db.sqlite
export FLASK_APP=src
export FLASK_DEBUG=1

Apart from the SECRET_KEY and DATABASE_URL, we've also exported APP_SETTINGS, DEBUG, FLASK_APP, and FLASK_DEBUG.

The APP_SETTINGS refers to one of the classes we created in the config.py file. We set it to the current stage of the project.

The value of FLASK_APP is the name of the package we have created. Since the app is in the development stage, you can set the values of DEBUG and FLASK_DEBUG to True and 1, respectively.

Run the following command to export all the environment variables from the .env file:

source .env

Next, you'll create a CLI application of the app so that you can later add custom commands such as test and create_admin in order to test the application and create admin, respectively.

Create a manage.py file in the root directory of the application and add the following code:

from flask.cli import FlaskGroup

from src import app

cli = FlaskGroup(app)


if __name__ == "__main__":
    cli()

Now, your basic application is ready. You can run it using the following command:

python manage.py run

How to Create Blueprints for Accounts and Core

As mentioned earlier, you'll use the concepts of blueprints in the project. Let's create two blueprints – accounts_bp and core_bp – in this section.

First create a directory called accounts like this:

mkdir accounts
cd accounts

Next, add an empty __init__.py file to covert it into a Python package. Now, create a views.py file inside the package where you'll store all your routes related to user authentication.

touch __init__.py views.py

Add the following code inside the views.py file:

from flask import Blueprint

accounts_bp = Blueprint("accounts", __name__)

In the above script, you have created a blueprint called accounts_bp for the accounts package.

Similarly, you can create a core package in the root directory, and add a views.py file.

mkdir core
cd core
touch __init__.py views.py

Now, add the following code inside the views.py file:

from flask import Blueprint

core_bp = Blueprint("core", __name__)

Note: If you're new to Flask Blueprints, make sure you go through this tutorial to learn more about how it works.

How to Create a User Model

Let's create a models.py file inside the accounts package.

touch src/accounts/models.py

Inside the models.py file, add the following code:

from datetime import datetime

from src import bcrypt, db


class User(db.Model):

    __tablename__ = "users"

    id = db.Column(db.Integer, primary_key=True)
    email = db.Column(db.String, unique=True, nullable=False)
    password = db.Column(db.String, nullable=False)
    created_on = db.Column(db.DateTime, nullable=False)
    is_admin = db.Column(db.Boolean, nullable=False, default=False)

    def __init__(self, email, password, is_admin=False):
        self.email = email
        self.password = bcrypt.generate_password_hash(password)
        self.created_on = datetime.now()
        self.is_admin = is_admin

    def __repr__(self):
        return f"<email {self.email}>"

In the above code, you created a User model by inheriting the db.Model class. The User model consists of the following fields:

• id: stores the primary key for the users table
• email: stores the email of the user
• password: stores the hashed password of the user
• created_on: stores the timestamp when the user was created
• is_admin: stores whether the user is admin or not

In the constructor of the class, you set the fields. Notice the password field where you generate the hash of the password using the bcrypt object imported from the app.

How to Add Flask-Login

The most important part of Flask-Login is the LoginManager class that lets your application and Flask-Login work together.

In the src/__init__.py file, add the following code:

from decouple import config
from flask import Flask
from flask_login import LoginManager # Add this line
from flask_migrate import Migrate
from flask_sqlalchemy import SQLAlchemy

app = Flask(__name__)
app.config.from_object(config("APP_SETTINGS"))

login_manager = LoginManager() # Add this line
login_manager.init_app(app) # Add this line
db = SQLAlchemy(app)
migrate = Migrate(app, db)

# Registering blueprints
from src.accounts.views import accounts_bp
from src.core.views import core_bp

app.register_blueprint(accounts_bp)
app.register_blueprint(core_bp)

In the above script, you created and initialized the login manager in your app.

Next, you need to provide a user_loader callback. This callback is used to reload the user object from the user ID stored in the session. It should take the ID of a user, and return the corresponding user object.

from src.accounts.models import User

@login_manager.user_loader
def load_user(user_id):
    return User.query.filter(User.id == int(user_id)).first()

The User model should implement the following properties and methods:

• is_authenticated: This property returns True if the user is authenticated.
• is_active: This property returns True if this is an active user (the account is activated)
• is_anonymous: This property returns True if this is an anonymous user (actual users return False).
• get_id(): This method returns a string that uniquely identifies this user, and can be used to load the user from the user_loader callback.

Now, you don't need to implement these explicitly. Instead, the Flask-Login provides a UserMixin class that contains the default implementations for all of these properties and methods. You just need to inherit it in the following way:

from datetime import datetime

from flask_login import UserMixin # Add this line

from src import bcrypt, db


class User(UserMixin, db.Model): # Change this line

    __tablename__ = "users"

    id = db.Column(db.Integer, primary_key=True)
    email = db.Column(db.String, unique=True, nullable=False)
    password = db.Column(db.String, nullable=False)
    created_on = db.Column(db.DateTime, nullable=False)
    is_admin = db.Column(db.Boolean, nullable=False, default=False)

    def __init__(self, email, password, is_admin=False):
        self.email = email
        self.password = bcrypt.generate_password_hash(password)
        self.created_on = datetime.now()
        self.is_admin = is_admin

    def __repr__(self):
        return f"<email {self.email}>"

You can also customize the default login process in the src/__init__.py file.

The name of the login view can be set as LoginManager.login_view. The value refers to the function name that will handle the login process.

login_manager.login_view = "accounts.login"

To customize the message category, set LoginManager.login_message_category:

login_manager.login_message_category = "danger"

How to Add Templates and Static Files

Let's create a CSS file called styles.css inside the src/static folder:

.error {
  color: red;
  margin-bottom: 5px;
  text-align: center;
}

a {
  text-decoration: none;
}

Let's also create the basic templates inside the src/templates folder. Create a _base.html file and add the following code:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>Flask User Management</title>
    <!-- meta -->
    <meta name="description" content="">
    <meta name="author" content="">
    <meta name="viewport" content="width=device-width,initial-scale=1">
    <!-- styles -->
    <!-- CSS only -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-gH2yIJqKdNHPEq0n4Mqa/HGKIhSkIHeL5AyhkYV8i59U5AR6csBvApHHNl/vI1Bx" crossorigin="anonymous">
    <link rel="stylesheet" href="{{url_for('static', filename="styles.css")}}">
    {% block css %}{% endblock %}
  </head>
  <body>

    {% include "navigation.html" %}

    <div class="container">

      <br>

      <!-- messages -->
      {% with messages = get_flashed_messages(with_categories=true) %}
      {% if messages %}
      <div class="row">
        <div class="col-md-4"></div>
        <div class="col-md-4">
          {% for category, message in messages %}
          <div class="alert alert-{{ category }} alert-dismissible fade show" role="alert">
           {{message}}
           <button type="button" class="btn-close" data-bs-dismiss="alert" aria-label="Close"></button>
          </div>
          {% endfor %}
        </div>
        <div class="col-md-4"></div>
      </div>
      {% endif %}
      {% endwith %}

      <!-- child template -->
      {% block content %}{% endblock %}

    </div>

    <!-- scripts -->
    <script src="https://code.jquery.com/jquery-3.6.1.min.js" type="text/javascript"></script>
    <!-- JavaScript Bundle with Popper -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0/dist/js/bootstrap.bundle.min.js" integrity="sha384-A3rJD856KowSb7dwlZdYEkO39Gagi7vIsF0jrRAoQmDKKtQBHUuLZ9AsSv4jD4Xa" crossorigin="anonymous"></script>
    {% block js %}{% endblock %}
  </body>
</html>

The _base.html is the parent HTML file that will be inherited by the other templates. We have added Bootstrap 5 support in the above file. We are also making use of Flask Flashes to show Bootstrap alerts in the app.

Let's also create a navigation.html file that contains the navbar of the app:

<!-- Navigation -->
<header class="p-3 text-bg-dark">
  <div class="container">
    <div class="d-flex flex-wrap align-items-center justify-content-center justify-content-lg-start">
      <ul class="nav col-12 col-lg-auto me-lg-auto mb-2 justify-content-center mb-md-0">
        <li><a href="{{ url_for('core.home') }}" class="nav-link px-2 text-secondary">Home</a></li>
      </ul>

      <div class="text-end">
        {% if current_user.is_authenticated %}
        <a href="{{ url_for('accounts.logout') }}"><button type="button" class="btn btn-danger me-2">Logout</button></a>
        {% else %}
          <a href="{{ url_for('accounts.login') }}"><button type="button" class="btn btn-outline-light me-2">Login</button></a>
          <a href="{{ url_for('accounts.register') }}"><button type="button" class="btn btn-success">Sign up</button></a>
        {% endif %}

      </div>
    </div>
  </div>
</header>

Note that we have not yet created the views used above.

How to Create the Homepage

In this section, you'll first create a view function for the homepage inside the core/views.py file. Add the following code there:

from flask import Blueprint, render_template
from flask_login import login_required

core_bp = Blueprint("core", __name__)


@core_bp.route("/")
@login_required
def home():
    return render_template("core/index.html")

Notice that we have used the blueprint to add the route. We also added a @login_required middleware to prevent access from unauthenticated users.

Next, let's create an index.html file inside the templates/core folder, and add the following code:

{% extends "_base.html" %}
{% block content %}

<h1 class="text-center">Welcome {{current_user.email}}!</h1>

{% endblock %}

The HTML page will just have a welcome message for authenticated users.

How to Implement User Registration

First of all, we'll create a registration form using Flask-WTF. Create a forms.py file inside the accounts package and add the following code:

from flask_wtf import FlaskForm
from wtforms import EmailField, PasswordField
from wtforms.validators import DataRequired, Email, EqualTo, Length

from src.accounts.models import User


class RegisterForm(FlaskForm):
    email = EmailField(
        "Email", validators=[DataRequired(), Email(message=None), Length(min=6, max=40)]
    )
    password = PasswordField(
        "Password", validators=[DataRequired(), Length(min=6, max=25)]
    )
    confirm = PasswordField(
        "Repeat password",
        validators=[
            DataRequired(),
            EqualTo("password", message="Passwords must match."),
        ],
    )

    def validate(self):
        initial_validation = super(RegisterForm, self).validate()
        if not initial_validation:
            return False
        user = User.query.filter_by(email=self.email.data).first()
        if user:
            self.email.errors.append("Email already registered")
            return False
        if self.password.data != self.confirm.data:
            self.password.errors.append("Passwords must match")
            return False
        return True

The RegisterForm extends the FlaskForm class and contains three fields – email, password, and confirm. We have added different validators such as DataRequired, Length, Email, and EqualTo to the respective fields.

We also defined a validate() method which is automatically called when the form is submitted.

Inside the method, we first perform the initial validation provided by FlaskForm. If that is successful, we perform our custom validation such as checking whether user is already registered, and matching the password with the confirmed password. If there are any errors, we append the error message in the respective fields.

Let's use this form in the views.py to create a function to handle the registration process.

from flask import Blueprint, flash, redirect, render_template, request, url_for
from flask_login import login_user

from src import db
from src.accounts.models import User

from .forms import RegisterForm


@accounts_bp.route("/register", methods=["GET", "POST"])
def register():
    if current_user.is_authenticated:
        flash("You are already registered.", "info")
        return redirect(url_for("core.home"))
    form = RegisterForm(request.form)
    if form.validate_on_submit():
        user = User(email=form.email.data, password=form.password.data)
        db.session.add(user)
        db.session.commit()

        login_user(user)
        flash("You registered and are now logged in. Welcome!", "success")

        return redirect(url_for("core.home"))

    return render_template("accounts/register.html", form=form)

In the above function, notice that we're using the blueprint to add the route for the function. Initially, we check if a user is already authenticated using the is_authenticated property. If it is, we redirect it to the homepage with a message.

If no user is authenticated, we first create an instance of the RegisterForm class. If the request method is GET, we render an HTML file with the form. Otherwise, we check if the form has valid inputs using the validate_on_submit() method.

If the inputs are valid, we create an instance of the User class with the email and password provided by the user, and add it to the database.

Next, we login the user using the login_user() method that accepts the user object. We also flash a success message and redirect the user to the homepage.

Now, let's use this form inside the HTML file. Create an accounts directory inside the templates folder and add a new file called register.html inside it. Add the following code:

{% extends "_base.html" %}

{% block content %}

<div class="row">
  <div class="col-md-4"></div>
  <div class="col-md-4">
    <main class="form-signin w-100 m-auto">
      <form role="form" method="post" action="">
        {{ form.csrf_token }}
        <h1 class="h3 mb-3 fw-normal text-center">Please register</h1>

        <div class="form-floating">
          {{ form.email(placeholder="email", class="form-control mb-2") }}
          {{ form.email.label }}
            {% if form.email.errors %}
              {% for error in form.email.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <div class="form-floating">
          {{ form.password(placeholder="password", class="form-control mb-2") }}
          {{ form.password.label }}
            {% if form.password.errors %}
              {% for error in form.password.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <div class="form-floating">
          {{ form.confirm(placeholder="Confirm Password", class="form-control mb-2") }}
          {{ form.confirm.label }}
            {% if form.confirm.errors %}
              {% for error in form.confirm.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <button class="w-100 btn btn-lg btn-primary" type="submit">Sign up</button>
        <p class="text-center mt-3">Already registered? <a href="{{ url_for('accounts.login') }}">Login now</a></p>
      </form>
    </main>
  </div>
  <div class="col-md-4"></div>
</div>

{% endblock %}

In the above code, we created an HTML form where we make use of the form instance that contains the form fields with their labels and errors. We have used a accounts.login view function which doesn't exist yet.

How to Implement User Login and Logout

First, let's create a login form in the accounts/forms.py file:

class LoginForm(FlaskForm):
    email = EmailField("Email", validators=[DataRequired(), Email()])
    password = PasswordField("Password", validators=[DataRequired()])

The form is similar to the registration form but it has only two fields – email and password.

Next, let's create a view function to handle the login process inside the accounts/views.py file:

from flask import Blueprint, flash, redirect, render_template, request, url_for
from flask_login import login_user

from src import bcrypt, db
from src.accounts.models import User

from .forms import LoginForm, RegisterForm


@accounts_bp.route("/login", methods=["GET", "POST"])
def login():
    if current_user.is_authenticated:
        flash("You are already logged in.", "info")
        return redirect(url_for("core.home"))
    form = LoginForm(request.form)
    if form.validate_on_submit():
        user = User.query.filter_by(email=form.email.data).first()
        if user and bcrypt.check_password_hash(user.password, request.form["password"]):
            login_user(user)
            return redirect(url_for("core.home"))
        else:
            flash("Invalid email and/or password.", "danger")
            return render_template("accounts/login.html", form=form)
    return render_template("accounts/login.html", form=form)

Similar to registration view function, we first check if a user is already authenticated using the is_authenticated property. If it is, we redirect it to the homepage with a message.

If not authenticated, we create an instance of the login form. If the request method is GET, we simply render a login.html file with the form. Otherwise, the form is validated.

During the validation, we use the check_password_hash method from the Flask-Bcrypt library to match the hashed passwords. If the passwords match, we login the user using the login_user() method and redirect to the homepage. Otherwise, we flash an error message and render the same HTML page.

Now, let's create a login.html file inside the templates/accounts folder:

{% extends "_base.html" %}

{% block content %}

<div class="row">
  <div class="col-md-4"></div>
  <div class="col-md-4">
    <main class="form-signin w-100 m-auto">
      <form role="form" method="post" action="">
        {{ form.csrf_token }}
        <h1 class="h3 mb-3 fw-normal text-center">Please sign in</h1>

        <div class="form-floating">
          {{ form.email(placeholder="email", class="form-control mb-2") }}
          {{ form.email.label }}
            {% if form.email.errors %}
              {% for error in form.email.errors %}
              <div class="alert alert-danger" role="alert">
                {{ error }}
              </div>
              {% endfor %}
            {% endif %}
        </div>
        <div class="form-floating">
          {{ form.password(placeholder="password", class="form-control mb-2") }}
          {{ form.password.label }}
            {% if form.password.errors %}
              {% for error in form.password.errors %}
                <div class="alert alert-danger" role="alert">
                  {{ error }}
                </div>
              {% endfor %}
            {% endif %}
        </div>
        <button class="w-100 btn btn-lg btn-primary" type="submit">Sign in</button>
        <p class="text-center mt-3">New User? <a href="{{ url_for('accounts.register') }}">Register now</a></p>
      </form>
    </main>
  </div>
  <div class="col-md-4"></div>
</div>

{% endblock %}

The login form is similar to the registration form but with just two fields for the email and password.

Logging out the user is a very simple process. You just need to create a view function for it inside the accounts/views.py file:

from flask_login import login_required, login_user, logout_user


@accounts_bp.route("/logout")
@login_required
def logout():
    logout_user()
    flash("You were logged out.", "success")
    return redirect(url_for("accounts.login"))

The Flask-Login library contains a logout_user method that removes the user from the session. We used the @login_required decorator so that only authenticated users can logout.

How to Run the Completed App for the First Time

Now that your application is ready (without the tests), you can first migrate the database, and then run the app.

• To initialize the database (create a migration repository), use the command:

flask db init

• To migrate the database changes, use the command:

flask db migrate

• To apply the migrations, use the command:

flask db upgrade

Since this is the first time we're running our app, you'll need to run all the above commands. Later, whenever you make changes to the database, you'll just need to run the last two commands.

After that, you can run your application using the command:

python manage.py run

How to Add Unit Tests to the App

Now that we have all the features ready, create a tests folder in the root directory and convert it into a package by adding an empty __init__.py file.

How to Create a Base TestCase

Let's create a base testcase that will be extended by the other testcases. Create a base_test.py file inside the tests package, and add the following code:

import os

from flask_testing import TestCase

from src import app, db
from src.accounts.models import User


class BaseTestCase(TestCase):
    def create_app(self):
        app.config.from_object("config.TestingConfig")
        return app

    def setUp(self):
        db.create_all()
        user = User(email="ad@min.com", password="admin_user")
        db.session.add(user)
        db.session.commit()

    def tearDown(self):
        db.session.remove()
        db.drop_all()
        testdb_path = os.path.join("src", "testdb.sqlite")
        os.remove(testdb_path)

The BaseTestCase class extends the TestCase class and implements the following three methods:

• The create_app() method is a required method which should return a Flask instance. If you don’t define create_app(), NotImplementedError will be raised. Notice that we're using the TestingConfig in this case.
• The setUp() method is called before running any test. In this method, we create all the database tables. Additionally, we also create a user so that we can play with it later.
• The tearDown() method is called after running all the testcases. So, in this method, we'll clean up all the test data.

How to Write Tests for Forms

In the above sections, we created two forms – RegisterForm and LoginForm. Let's test these forms in a new test file named test_forms.py inside the tests package.

import unittest

from base_test import BaseTestCase

from src.accounts.forms import LoginForm, RegisterForm


class TestRegisterForm(BaseTestCase):
    def test_validate_success_register_form(self):
        # Ensure correct data validates.
        form = RegisterForm(email="new@test.com", password="example", confirm="example")
        self.assertTrue(form.validate())

    def test_validate_invalid_password_format(self):
        # Ensure incorrect data does not validate.
        form = RegisterForm(email="new@test.com", password="example", confirm="")
        self.assertFalse(form.validate())

    def test_validate_email_already_registered(self):
        # Ensure user can't register when a duplicate email is used
        form = RegisterForm(
            email="ad@min.com", password="admin_user", confirm="admin_user"
        )
        self.assertFalse(form.validate())


class TestLoginForm(BaseTestCase):
    def test_validate_success_login_form(self):
        # Ensure correct data validates.
        form = LoginForm(email="ad@min.com", password="admin_user")
        self.assertTrue(form.validate())

    def test_validate_invalid_email_format(self):
        # Ensure invalid email format throws error.
        form = LoginForm(email="unknown", password="example")
        self.assertFalse(form.validate())


if __name__ == "__main__":
    unittest.main()

The TestRegisterForm class defines three test methods to test the validate method of the RegisterForm class.

The first test method tests that the form validates with correct input data. The second test method tests that the form does not validate with an invalid password format. And the third test method tests that the form does not validate when a duplicate email is used to register.

The TestLoginForm class defines two test methods to test the validate method of the LoginForm class. The first test method tests that the form validates with correct input data, and the second test method tests that the form does not validate with an invalid email format.

How to Test the User Model

Let's now test the User model in a new file named test_models.py inside the tests package.

import datetime
import unittest

from base_test import BaseTestCase
from flask_login import current_user

from src import bcrypt
from src.accounts.models import User


class TestUser(BaseTestCase):
    def test_user_registration(self):
        # Ensure user registration behaves correctly.
        with self.client:
            self.client.get("/logout", follow_redirects=True)
            self.client.post(
                "/register",
                data=dict(
                    email="test@user.com", password="test_user", confirm="test_user"
                ),
                follow_redirects=True,
            )
            user = User.query.filter_by(email="test@user.com").first()
            self.assertTrue(user.id)
            self.assertTrue(user.email == "test@user.com")
            self.assertFalse(user.is_admin)

    def test_get_by_id(self):
        # Ensure id is correct for the current/logged in user
        with self.client:
            self.client.get("/logout", follow_redirects=True)
            self.client.post(
                "/login",
                data=dict(email="ad@min.com", password="admin_user"),
                follow_redirects=True,
            )
            self.assertTrue(current_user.id == 1)

    def test_created_on_defaults_to_datetime(self):
        # Ensure that registered_on is a datetime
        with self.client:
            self.client.get("/logout", follow_redirects=True)
            self.client.post(
                "/login",
                data=dict(email="ad@min.com", password="admin_user"),
                follow_redirects=True,
            )
            user = User.query.filter_by(email="ad@min.com").first()
            self.assertIsInstance(user.created_on, datetime.datetime)

    def test_check_password(self):
        # Ensure given password is correct after unhashing
        user = User.query.filter_by(email="ad@min.com").first()
        self.assertTrue(bcrypt.check_password_hash(user.password, "admin_user"))
        self.assertFalse(bcrypt.check_password_hash(user.password, "foobar"))

    def test_validate_invalid_password(self):
        # Ensure user can't login when the pasword is incorrect
        with self.client:
            self.client.get("/logout", follow_redirects=True)
            response = self.client.post(
                "/login",
                data=dict(email="ad@min.com", password="foo_bar"),
                follow_redirects=True,
            )
        self.assertIn(b"Invalid email and/or password.", response.data)


if __name__ == "__main__":
    unittest.main()

The TestUser class defines four test methods to test various aspects of the User model class.

• The first test method tests the user registration process by posting a registration request to the server with the client object, which is a Flask test client. The test verifies that a new user is correctly added to the database and that the user's attributes are correctly set.
• The second test method tests the get_by_id method, which is a helper method to get the user object from the database by its id. The test logs in a user and verifies that the current user's id is correct.
• The third test method tests that the created_on attribute of the user object is a datetime object.
• The fourth test method tests the check_password method, which is a helper method to check the user's password. The test verifies that the method correctly checks a correct and an incorrect password.
• The fifth test method tests the login process by posting a login request to the server with the client object and verifies that the server responds with an error message when the password is incorrect.

How to Test the Routes

Let's now test the routes in a new file named test_routes.py inside the tests package.

import unittest

from base_test import BaseTestCase
from flask_login import current_user


class TestPublic(BaseTestCase):
    def test_main_route_requires_login(self):
        # Ensure main route requres logged in user.
        response = self.client.get("/", follow_redirects=True)
        self.assertTrue(response.status_code == 200)
        self.assertIn(b"Please log in to access this page", response.data)

    def test_logout_route_requires_login(self):
        # Ensure logout route requres logged in user.
        response = self.client.get("/logout", follow_redirects=True)
        self.assertIn(b"Please log in to access this page", response.data)


class TestLoggingInOut(BaseTestCase):
    def test_correct_login(self):
        # Ensure login behaves correctly with correct credentials
        with self.client:
            response = self.client.post(
                "/login",
                data=dict(email="ad@min.com", password="admin_user"),
                follow_redirects=True,
            )
            self.assertTrue(current_user.email == "ad@min.com")
            self.assertTrue(current_user.is_active)
            self.assertTrue(response.status_code == 200)

    def test_logout_behaves_correctly(self):
        # Ensure logout behaves correctly, regarding the session
        with self.client:
            self.client.post(
                "/login",
                data=dict(email="ad@min.com", password="admin_user"),
                follow_redirects=True,
            )
            response = self.client.get("/logout", follow_redirects=True)
            self.assertIn(b"You were logged out.", response.data)
            self.assertFalse(current_user.is_active)


if __name__ == "__main__":
    unittest.main()

The TestPublic class defines two test methods to test the access control of certain routes.

The first test method tests that the main route requires a logged-in user by attempting to access it with the client object, which is a Flask test client. The test verifies that the server responds with a login prompt. The second test method tests that the logout route also requires a logged-in user.

The TestLoggingInOut class defines two test methods to test the login and logout functionality.

The first test method tests the login process by posting a login request to the server with the client object and verifies that the server responds with a successful login. The second test method tests the logout process by posting a logout request to the server with the client object. It then verifies that the server responds with a logout message and that the user is no longer logged in.

How to Run the Tests

Now that we have all the tests ready, we are ready to run the testcases. But before that, as mentioned in the beginning, we'll need to add a command in the manage.py file to run the tests.

import unittest


@cli.command("test")
def test():
    """Runs the unit tests without coverage."""
    tests = unittest.TestLoader().discover("tests")
    result = unittest.TextTestRunner(verbosity=2).run(tests)
    if result.wasSuccessful():
        return 0
    else:
        return 1

The command runs the unit tests in the tests package and displays the results in the terminal.

You use the unittest.TestLoader().discover() method to discover and run all the unit tests in the tests package. You use the unittest.TextTestRunner() method to run the unit tests and to print the results to the terminal. The verbosity argument controls the level of detail in the output.

If all the unit tests pass, the test command returns a exit code of 0. If any of the unit tests fail, the command returns a exit code of 1.

Now, you can run all the tests using the command:

python manage.py test

This will give the below output:

test_validate_invalid_email_format (test_forms.TestLoginForm) ... ok
test_validate_success_login_form (test_forms.TestLoginForm) ... ok
test_validate_email_already_registered (test_forms.TestRegisterForm) ... ok
test_validate_invalid_password_format (test_forms.TestRegisterForm) ... ok
test_validate_success_register_form (test_forms.TestRegisterForm) ... ok
test_check_password (test_models.TestUser) ... ok
test_created_on_defaults_to_datetime (test_models.TestUser) ... ok
test_get_by_id (test_models.TestUser) ... ok
test_user_registration (test_models.TestUser) ... ok
test_validate_invalid_password (test_models.TestUser) ... ok
test_correct_login (test_routes.TestLoggingInOut) ... ok
test_logout_behaves_correctly (test_routes.TestLoggingInOut) ... ok
test_logout_route_requires_login (test_routes.TestPublic) ... ok
test_main_route_requires_login (test_routes.TestPublic) ... ok

----------------------------------------------------------------------
Ran 14 tests in 19.577s

OK

Features to Add to Your Application

Here are some extra things you can add in your application. Note that these are optional.

How to Create an Admin

Similar to the test command, you can add a create_admin command to create an admin in your application. Add the following code inside the manage.py file:

import getpass


@cli.command("create_admin")
def create_admin():
    """Creates the admin user."""
    email = input("Enter email address: ")
    password = getpass.getpass("Enter password: ")
    confirm_password = getpass.getpass("Enter password again: ")
    if password != confirm_password:
        print("Passwords don't match")
        return 1
    try:
        user = User(email=email, password=password, is_admin=True)
        db.session.add(user)
        db.session.commit()
    except Exception:
        print("Couldn't create admin user.")

The command prompts the user to enter an email address and a password for the admin user. The password is entered using the getpass module, which hides the password input from the terminal. The command then checks if the entered password and the confirmed password match. If the passwords don't match, the command prints an error message and returns a exit code of 1.

If the passwords match, the command creates a new User object with the entered email address, password, and the is_admin attribute set to True. The command then adds the user object to the database session and commits the changes to the database. If an exception is raised during this process, the command prints an error message.

You can run the below command to create one:

python manage.py create_admin

Output:

> python manage.py create_admin
Enter email address: admin@myapp.com
Enter password: 
Enter password again: 
Admin with email admin@myapp.com created successfully!

How to Create Error Pages

Our application can get errors at any time. The most common errors that we get are Unauthorized (401), Not Found (404) and Server Error (500).

Let's create an errors directory inside the templates directory and create three HTML pages as below:

• 401.html

{% extends "_base.html" %}
{% block content %}
<h1>401</h1>
<p>Run along!</p>
<p><em>Return <a href="{{url_for('core.home')}}">Home</a>?</em></p>
{% endblock %}

• 404.html

{% extends "_base.html" %}
{% block content %}
<h1>404</h1>
<p>There's nothing here!</p>
<p><em>Return <a href="{{url_for('core.home')}}">Home</a>?</em></p>
{% endblock %}

• 500.html

{% extends "_base.html" %}
{% block content %}
<h1>500</h1>
<p>Something's wrong! We are on the job.</p>
<p><em>Return <a href="{{url_for('core.home')}}">Home</a>?</em></p>
{% endblock %}

Next, we need to add error handlers for these errors. Open the src/__init__.py file and add the following code in the bottom of the file:

@app.errorhandler(401)
def unauthorized_page(error):
    return render_template("errors/401.html"), 401


@app.errorhandler(404)
def page_not_found(error):
    return render_template("errors/404.html"), 404


@app.errorhandler(500)
def server_error_page(error):
    return render_template("errors/500.html"), 500

This above code snippet registers error handler functions for the HTTP error codes 401, 404, and 500 in a Flask application. An error handler function is a function that is called when an error occurs in the application.

The error handler functions are decorated with the @app.errorhandler decorator, which registers them with the Flask application. The decorator takes an error code as an argument, and the function is called when the error code is raised.

Each error handler function returns a rendered template and the error code as a response to the client. The templates are HTML files located in the errors folder and contain the content to be displayed to the user for each error. The error code is passed as an argument to the render_template function to determine which template to render.

Wrapping up

In this tutorial, you learned how to set up basic user authentication in your Flask app. You also wrote few testcases in order to test the functionalities.

Here's the link to the GitHub repository. Feel free to check it out whenever you're stuck.

Recommended next steps

• You can add more security such as email verification, or token-based authentication in the app.
• You can add a "forgot password" feature in the application.
• You can add more testcases in order to test the app more thoroughly.

Thank you for reading. I hope you found this article useful. You can follow me on Twitter.

Sometimes you'll find developers dumping all of their logic into a single file called app.py. You will find a lot of tutorials that follow the same pattern. But it's not a good practice for a large-scale app.

By doing this, you are clearly violating the Single Responsibility Principle, where each piece of your application should handle just one responsibility.

If you have worked with Django, you might have found your project divided into different modules. In Flask, also, you can organize your applications using Blueprints, a built-in concept in Flask similar to Python modules.

What Does a Flask Application Look Like?

If you follow the Flask documentation to create a minimal application, your project structure will look similar to this:

/myapp
├── /templates
├── /static
└── app.py

Doesn't the folder look so clean? All you have is an app.py file where you have all your logic for the application, a templates folder to store your HTML files, and a static folder to store your static files.

Let's look at the app.py file:

from flask import Flask


app = Flask(__name__)

# Some Models Here


# Routes related to core functionalities


# Routes related to Profile Page


# Routes related to Products Page


# Routes related to Blog Page


# Routes related to Admin Page

if __name__ == '__main__':
    app.run(debug=True)

Doesn't that look messy (imagining that you've built a large-scale app)? You have all your models and different routes inside the same file spread around here and there.

How Does Blueprints Solve the Problem?

Now, this is where Flask Blueprints come into picture. Blueprints help you structure your application by organizing the logic into subdirectories. In addition to that, you can store your templates and static files along with the logic in the same subdirectory.

So, with Blueprints now your same application will look like this:

/blueprint-tutorial
├── /myapp_with_blueprints
│   ├── __init__.py
│   ├── /admin
│   │   ├── /templates
│   │   ├── /static
│   │   └── routes.py
│   ├── /core
│   │   ├── /templates
│   │   ├── /static
│   │   └── routes.py
│   ├── /products
│   │   ├── /templates
│   │   ├── /static
│   │   └── routes.py
│   └── /profile
|       ├── /templates
|       ├── /static
|       └── routes.py        
├── app.py
├── /static
└── /templates

Now you can see that you have clear separation of concerns. The logic related to admin resides inside the admin folder, the logic related to products resides inside the products folder and so on.

Additionally, we also separated the templates and static files in the subdirectories where they are required, so that irrelevant files don't load when going to a page that doesn't require them.

How to Use Blueprints

Now that you understand what problems Blueprints solves, let's see how we can use Blueprints in our applications.

How to Define a Blueprint

Let's define our very first blueprint for the admin functionality inside the admin/routes.py file:

from flask import Blueprint


# Defining a blueprint
admin_bp = Blueprint(
    'admin_bp', __name__,
    template_folder='templates',
    static_folder='static'
)

Since Blueprint is a Flask built-in concept, you can import it from the Flask library. While creating the object of the Blueprint class, the first parameter is the name you want to give to your Blueprint. This name will later be used for internal routing (we'll see below).

The second parameter is the name of the Blueprint package, generally __name__. This helps locate the root_path for the blueprint.

The third and fourth parameters passed are optional keyword arguments. By defining the template_folder and static_folder parameters, you specify that you'll be using blueprint-specific templates and static files.

How to Define Routes with Blueprints

Now that you have created a blueprint for the admin related functionality, you can use it while creating routes for the admins.

from flask import Blueprint


# Defining a blueprint
admin_bp = Blueprint(
    'admin_bp', __name__,
    template_folder='templates',
    static_folder='static'
)

@admin_bp.route('/admin')   # Focus here
def admin_home():
    return "Hello Admin!"

In the above snippet, focus on the line where the route is defined. Instead of the usual @app.route('...'), we have used @admin_bp.route('...'). This is how you bind a route to a particular blueprint.

How to Register Your Blueprints

Now you have a blueprint and a route registered to it. But, will your app automatically know about this blueprint?

No. You do it.

So, let's do it. In the __init__.py file, we will create a Flask app and register our blueprints there:

from flask import Flask


app = Flask(__name__)

from .admin import routes

# Registering blueprints
app.register_blueprint(admin.admin_bp)

To register the blueprint, we use the register_blueprint() method and pass the name of the blueprint. Additionally, you can pass other parameters to the method for more customization. One such is url_prefix that you may require.

app.register_blueprint(admin.admin_bp, url_prefix='/admin')

Similarly, you can register rest of your blueprints if you have more.

Template Routing with Blueprints

Without Blueprints, in order to create links in your templates, you would use something similar to the below:

<a href="{{ url_for('admin_home') }}">My Link</a>

But with blueprints in place, now you can define your links as:

<a href="{{ url_for('admin_bp.admin_home') }}">My Link</a>

The admin_bp that we used above is the name we gave to our blueprint for internal routing while creating the object.

To print the blueprint name of the Jinja2 template that the current page belongs to, you can use {{request.blueprint}}.

Note: To use Blueprint-specific assets, you can use the Flask-Assets library.

Wrapping Up

Blueprint is an amazing tool to organize and structure your Flask applications.

In this article, you've learned what blueprints have to offer and how to use them in your Flask applications.

Thanks for reading!

You can follow me on Twitter.

The application will allow users to enter a URL and an optional custom short id and generate a shorter version.

Here's what we're going to build:

The frontend of the application is not attractive, because the main focus of the project is building a backend project.

Some sample shortened URLs are https://shorty-flask.herokuapp.com/mzkpK8sw and https://shorty-flask.herokuapp.com/linkify.

Create the Virtual Environment and Install the Dependencies

In this tutorial, we're going to use Pipenv to manage our virtual environment.

Pipenv is a tool that automatically creates and manages a virtualenv for your projects, as well as adds/removes packages from your Pipfile as you install/uninstall packages. It also generates the ever-important Pipfile.lock, which is used to produce deterministic builds.

You can read this article to learn more about it.

Pipenv is an external library and we need to install it explicitly. To install the library, use the pip command:

pip install pipenv

Once it's installed, we can create a virtual environment and activate it using this command:

pipenv shell

To deactivate the virtual environment, we have a simple command:

exit

Once you have created and activated the virtual environment, you're ready to install the required libraries.

• Flask is a simple, easy-to-use microframework for Python that can help build scalable and secure web applications. The module doesn't come pre-installed with Python, so we need to install it using the command:

    pipenv install Flask
  

• Flask-Migrate is an extension that handles SQLAlchemy database migrations for Flask applications using Alembic. The database operations are made available through the Flask command-line interface. To install the module, use the command:

    pipenv install Flask-Migrate
  

• Flask-SQLAlchemy is an extension for Flask that adds support for SQLAlchemy to your application. It helps you simplify things using SQLAlchemy with Flask by giving you useful defaults and extra helpers that make it easier to perform common tasks. To install the module, use the command:

    pipenv install Flask-SQLAlchemy
  

• Psycopg2 is the most popular PostgreSQL database adapter for the Python programming language. To install the module, use the command:

    pipenv install psycopg2
  

• Gunicorn is a Python WSGI HTTP Server for UNIX. To install the module, use the command:

    pipenv install gunicorn
  

• Python Decouple: We'll also use environment variables in this project. So, we are going to install another module called python-decouple to handle this:

    pipenv install python-decouple
  

How to Set Up the Flask Project

The first thing we're going to do is to create a Flask project. If you check the official documentation of Flask, you'll find a minimal application there.

But, we're not going to follow that. We are going to write an application that is more extensible and has a good base structure. If you wish, you can follow this guide to get started with Flask.

Our application will exist within a package called core. To convert a usual directory to a Python package, we just need to include an __init__.py file. So, let's create our core package first.

$ mkdir core

After that, let's create the __init__.py file inside the core directory:

$ cd core
$ touch __init__.py
$ cd ..

In the root directory of the project, create a file called config.py. We'll store the configurations for the project in this file. Within the file, add the following content:

from decouple import config


DATABASE_URI = config("DATABASE_URL")
if DATABASE_URI.startswith("postgres://"):
    DATABASE_URI = DATABASE_URI.replace("postgres://", "postgresql://", 1)


class Config(object):
    DEBUG = False
    TESTING = False
    CSRF_ENABLED = True
    SECRET_KEY = config('SECRET_KEY', default='guess-me')
    SQLALCHEMY_DATABASE_URI = DATABASE_URI
    SQLALCHEMY_TRACK_MODIFICATIONS = False


class ProductionConfig(Config):
    DEBUG = False


class StagingConfig(Config):
    DEVELOPMENT = True
    DEBUG = True


class DevelopmentConfig(Config):
    DEVELOPMENT = True
    DEBUG = True


class TestingConfig(Config):
    TESTING = True

In the above script, we have created a Config class and defined various attributes inside that. Also, we have created different child classes (as per different stages of development) that inherit the Config class.

Notice that we're using a few environment variables like SECRET_KEY and DATABASE_URL. Create a file named .env in the root directory and add the following content there:

SECRET_KEY=verysecretkey
DATABASE_URL=sqlite:///shorty.db
APP_SETTINGS=config.DevelopmentConfig
FLASK_APP=core

Apart from the SECRET_KEY and DATABASE_URL, we've also specified APP_SETTINGS and FLASK_APP.

The APP_SETTINGS refers to one of the classes we created in the config.py file. We set it to the current stage of the project. The value of FLASK_APP is the name of the package we have created.

Now, we can add the following content in the core/__init__.py file:

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from decouple import config

app = Flask(__name__)
app.config.from_object(config("APP_SETTINGS"))

db = SQLAlchemy(app)
migrate = Migrate(app, db)

from core import routes

In the above Python script, we are first importing the Flask class from the Flask module that we have installed. Next, we're creating an object app of class Flask. We use the __name__ argument to indicate the app's module or package, so that Flask knows where to find other files such as templates.

Next we are setting the app configurations to the APP_SETTINGS according to the variable in the .env file. To use Flask-SQLAlchemy and Flask-Migrate in our application, we just need to create objects of the SQLAlchemy class and Migrate class from the flask_sqlalchemy and flask_migrate libraries respectively.

The application then imports the routes module, which doesn't exist yet.

To run the application, we'll use a main.py file with the following content:

from core import app

if __name__ == '__main__':
    app.run()

How to Create the Database Table

To define our database tables, we’ll create a models.py file within the core package. Inside that, we can write the following code :

from core import db
from datetime import datetime

class ShortUrls(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    original_url = db.Column(db.String(500), nullable=False)
    short_id = db.Column(db.String(20), nullable=False, unique=True)
    created_at = db.Column(db.DateTime(), default=datetime.now(), nullable=False)

We first imported the db object that we had initialized in the __init__.py file. Then we created a ShortUrls class with a few fields such as id (primary key), original_url (provided by the user), short_id (generated by us or provided by the user), and created_at (timestamp).

We can then use Flask-Migrate commands to migrate the database with the new tables. The commands we'll use are:

• flask db init — to initialize the database at the beginning (to be used only once)
• flask db migrate — to migrate the new changes to the database (to be used every time we make changes in the database tables)
• flask db upgrade — to upgrade our database with the new changes (to be used with the migrate command)

After we run the database initialization we will see a new folder called “migrations” in the project. This holds the setup necessary for Alembic to run migrations against the project.

Inside of “migrations”, we will see that it has a folder called “versions”, which will contain the migration scripts as they are created.

How to Create the Homepage for Shortening URLs

In this step, we will create a Flask route for the index page, which will allow users to enter a URL that we then save into the database. This route will use the custom short id provided by the user or generate one on its own, construct the short URL, and then render it as a result.

First, let’s create a routes.py file in the core package and create a Python function to generate short id.

from random import choice
import string

def generate_short_id(num_of_chars: int):
    """Function to generate short_id of specified number of characters"""
    return ''.join(choice(string.ascii_letters+string.digits) for _ in range(num_of_chars))

In order to generate a short id, we have used the choice method from Python’s random module. Also, we have used Python’s in-built string module for letters (lowercase + uppercase), and digits.

Now, we need to create a template for the index page that will be served by the index route. This template will have a simple form where a user can input the original URL and custom short id (optional) and submit it.

But we’ll not create index.html directly. We can use the Template Inheritance concept in Jinja2. So, let's create a templates directory within the core package and create a base.html file inside that. You can paste the HTML code into that file.

<!doctype html>
<html lang="en">
  <head>
    <!-- Required meta tags -->
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">

    <!-- Bootstrap CSS -->
    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-KyZXEAg3QhqLMpG8r+8fhAXLRk2vvoC2f3B09zVXn8CA5QIVfZOJ3BCsw2P0p/We" crossorigin="anonymous">

    <title>{% block title %} {% endblock %}</title>
  </head>
  <body>
    <div class="container mt-3">
        {% for message in get_flashed_messages() %}
            <div class="alert alert-danger">{{ message }}</div>
        {% endfor %}
        {% block content %} {% endblock %}
    </div>

    <!-- Optional JavaScript -->
    <!-- jQuery first, then Popper.js, then Bootstrap JS -->
    <script src="https://code.jquery.com/jquery-3.3.1.slim.min.js" integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/@popperjs/core@2.9.3/dist/umd/popper.min.js" integrity="sha384-eMNCOe7tC1doHpGoWe/6oMVemdAVTMs2xqW4mwXrXsW0L84Iytr2wi5v2QjrP/xp" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.1.0/dist/js/bootstrap.min.js" integrity="sha384-cn7l7gDp0eyniUwwAZgrzD06kc/tftFf19TOAs2zVinnD/C7E91j9yyk5//jjpt/" crossorigin="anonymous"></script>
  </body>
</html>

Note that, for styling, we’re using Bootstrap here.

Most of the code in the preceding block is standard HTML code required for Bootstrap. The <meta> tags provide information for the web browser, the <link> tag links the Bootstrap CSS files, and the <script> tags are links to JavaScript code that allows some additional Bootstrap features.

You can check out the Bootstrap documentation for more information.

The <title>{% block title %} {% endblock %}</title> tag allows the inheriting templates to define a custom title.

We use the for message in get_flashed_messages() loop to display the flashed messages (warnings, alerts, and so on).

The {% block content %} {% endblock %} placeholder is where inheriting templates place the content so that all templates have access to this base template, which avoids repetition.

Next, create the index.html file that will extend this base.html file:

{% extends 'base.html' %}

{% block content %}
    <h1 class="text-center mb-3">{% block title %} Welcome to Shorty {% endblock %}</h1>
    <div class="row">
        <div class="col-md-2"></div>
        <div class="col-md-8">
            <form method="post" action="{{url_for('index')}}">
            <div class="form-floating mb-3">
                <input type="text" name="url" id="url"
                    placeholder="Enter looooooooooooong URL" class="form-control"
                    value="{{ request.form['url'] }}" autofocus></input>
                <label for="url">URL</label>
            </div>
            <div class="form-floating mb-3">
                <input type="text" name="custom_id" id="custom_id"
                    placeholder="Want to customise? (optional)" class="form-control"
                    value="{{ request.form['custom_id'] }}"></input>
                <label for="custom_id">Custom Short ID</label>
            </div>

            <div class="form-group text-center">
                <button type="submit" class="btn btn-lg btn-primary">Shorten</button>
            </div>
            </form>

            {% if short_url %}
            <hr>
            <span><a href="{{ short_url }}" target="_blank">{{ short_url }}</a></span>
            {% endif %}
        </div>
        <div class="col-md-2"></div>
    </div>
{% endblock %}

Here we extend base.html, define a title, and create a form with two inputs named url and custom_id.

The url input will allow users to enter URLs to shorten. It has a value of request.form['url'], which stores data in cases of submission failure (that is if the user provides no URL). Similarly, custom_id input will allow users to enter a custom short id. We then have a submit button.

Then we check if the short_url variable has any value—this is true if the form submits and the short URL generates successfully. If the condition is true, we display the short URL under the form.

Now we can rewrite our index view function in routes.py as:

from datetime import datetime
from core.models import ShortUrls
from core import app, db
from random import choice
import string
from flask import render_template, request, flash, redirect, url_for


def generate_short_id(num_of_chars: int):
    """Function to generate short_id of specified number of characters"""
    return ''.join(choice(string.ascii_letters+string.digits) for _ in range(num_of_chars))


@app.route('/', methods=['GET', 'POST'])
def index():
    if request.method == 'POST':
        url = request.form['url']
        short_id = request.form['custom_id']

        if short_id and ShortUrls.query.filter_by(short_id=short_id).first() is not None:
            flash('Please enter different custom id!')
            return redirect(url_for('index'))

        if not url:
            flash('The URL is required!')
            return redirect(url_for('index'))

        if not short_id:
            short_id = generate_short_id(8)

        new_link = ShortUrls(
            original_url=url, short_id=short_id, created_at=datetime.now())
        db.session.add(new_link)
        db.session.commit()
        short_url = request.host_url + short_id

        return render_template('index.html', short_url=short_url)

    return render_template('index.html')

The index() function is a Flask view function, which is a function decorated using the special @app.route decorator. Its return value gets converted into an HTTP response that an HTTP client, such as a web browser, displays.

Inside the index() view function, we accept both GET and POST requests by passing methods=['GET', 'POST'] to the app.route() decorator.

Then if the request is a GET request, it skips the if request.method == 'POST' condition until the last line. This is where we render a template called index.html, which will contain a form for users to enter a URL to shorten.

If the request is a POST request, the if request.method == 'POST' condition is true, which means a user has submitted a URL. We store the URL in the url variable. If the user has submitted an empty form, you flash the message The URL is required! and redirect to the index page.

If the user has entered custom_id, we store it in short_id, else we generate random short id using the function that we had created before.

If the user has submitted a URL, we create a new_link with all the data such as original_url short_id and created_at. Then we commit the transaction.

We then construct the short URL using request.host_url, which is an attribute that Flask’s request object provides to access the URL of the application’s host. This will be http://127.0.0.1:5000/ in a development environment and our_domain if we deploy our application.

For example, the short_url variable will have a value like http://127.0.0.1:5000/asdf1gHJ, which is the short URL that will redirect users to the original URL stored in the database with the ID that matches the asdf1gHJ.