About

Inspired by FastAPI's OAuth2 with Password (and hashing), Bearer with JWT tokens, this project represents a simple cookies-based role-based authentication service using JWT tokens, built with FastAPI and managed by Nginx's Auth Sub Request module to verify users access to the protected resources of the API.

Features

• Access and refresh JWT tokens stored in secure cookies
• Role-based access control
• Automatic tokens refreshment and invalidation
• Authentication based on Nginx's subrequest module
• Admin UI to manage users and roles
• CLI for creating users

How it works

How to protect an endpoint

Only 2 steps required to protect an endpoint, and grant access to the endpoint only to users with specific roles. For example, let's say you have an endpoint named /protected that you want to protect it from the public access:

Step 1. Add a location block for the target to Nginx config:

  location = /protected {
    include /etc/nginx/snippets/auth_subrequest.conf;
    proxy_pass http://auth_api/protected;
  }

The most important part in the location block is the inclusion of the auth_subrequest.conf snippet, which contains the configuration for Nginx's subrequest authentication module.

Step 2. Grant access to the endpoint only to users with a specific role.

For this, you simple need to insert the endpoint into the locations attribute of the specified role in policy.json file. For example, let's say that access to the /protected endpoint should be granted only to users with the moderator role:

  "moderator": {
    "locations": [
      "/protected"
    ]
  }

As a result, after authentication and authorization process, Nginx will automatically send an internal subrequest to the API for each request to the /protected endpoint, verifying user's JWT tokens and role. If the user doesn't have access to the protected endpoint, the API will respond with the 403 Forbidden status code.

System Requirements

• Python 3.12
• UV package manager
• Docker and Docker Compose plugin

Configuration

There are a few configuration files that can be modified to customize the behavior of the application:

• proxy/default.conf.tpl. This is the configuration file for Nginx. In this file you declare the endpoints (locations) that you want to protect in your API using Nginx's subrequest module.
• src/policy.json. Access control policy file. This is a simple JSON file that defines the roles and their associated permissions (i.e., which endpoints they can access).
• .env. File containing environment variables for configuring the application. It provides settings for:
  • Main FastAPI application
  • PostgreSQL for storing users data
  • Redis for storing information about authentication tokens
  • JWT tokens
  • Nginx server
  • Other settings

Note: if the .env file is missing, create it by copying the .env.example file and modifying the values as needed.

Deployment

Once the configuration files are set up, you can deploy the application using Docker Compose:

docker compose up -d

This will start the following services:

• app - FastAPI application;
• db - PostgreSQL database to store users data;
• redis - Redis database to store authentication tokens data;
• nginx - Nginx for proxying API requests and handling authentication using the Auth Subrequest module.

Usage

Once all services are up and running, you can register the first user via CLI.

Note: use the CLI script below to register a user with a specified role, such as admin or moderator.

docker compose exec app python scripts/create_user.py

After creating the user, navigate to http://localhost/ to access the Swagger UI documentation of the API. From there, you can use the /login endpoint to authenticate and obtain a pair of JWT tokens that will be stored in the browser's cookies. You can then access protected endpoints based on the user's role and the corresponding policy.

References:

• OAuth2 with Password (and hashing), Bearer with JWT tokens¶
• FastAPI JWT Auth
• Nginx. Authentication Based on Subrequest Result
• JSON Web Token (JWT) Debugger