Main v2

.env.example

@@ -1,13 +1,11 @@
-APP_HOST=auth
+APP_HOST=app
 APP_PORT=8000
 
 DEBUG=1
-ADMIN_DEBUG=1
-GUNICORN_WORKERS=5
-GUNICORN_THREADS=2
+GUNICORN_WORKERS=2
 
 POSTGRES_USER=user
-POSTGRES_PASSWORD=123456
+POSTGRES_PASSWORD=12345
 POSTGRES_DB=user
 POSTGRES_HOST=db
 POSTGRES_PORT=5432
@@ -16,7 +14,7 @@ DATABASE_URL=postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGR
 REDIS_HOST=redis
 REDIS_PORT=6379
 REDIS_USER=default
-REDIS_PASSWORD=secret123
+REDIS_PASSWORD=123456
 REDIS_URL=redis://${REDIS_USER}:${REDIS_PASSWORD}@${REDIS_HOST}:${REDIS_PORT}
 
 NGINX_PORT=80

.github/workflows/checks.yml

@@ -1,39 +1,40 @@
-name: code checks
+name: Code Checks
 
 on:
   push:
     branches: [ main ]
-    paths: ['src/**']
   pull_request:
     branches: [ main ]
 
 jobs:
   checks:
     name: Test Code
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v3
+        uses: actions/setup-python@v4
         with:
-          python-version: 3.12
+          python-version: "3.12"
 
-      - name: Install python packages
-        run: |
-          pip install --upgrade pip
-          pip install setuptools poetry
-          poetry install --no-root
+      - name: Install uv
+        uses: astral-sh/setup-uv@v1
+        with:
+          version: "0.7.13"
+
+      - name: Install dependencies
+        run: uv sync --locked --all-extras --group test
 
-      - name: Running Ruff
-        run: poetry run ruff check
+      - name: Run Ruff
+        run: uv run ruff check
 
-      - name: Running Mypy
-        run: poetry run mypy .
+      - name: Run Mypy
+        run: uv run mypy
 
-      - name: Running Pytest with Coverage
-        run: poetry run pytest --cov
+      - name: Run Pytest with Coverage
+        run: uv run pytest --cov
 
       - name: Creating coverage folder
         run: mkdir -p coverage

.gitignore

@@ -2,5 +2,6 @@ venv
 __pycache__
 .pytest_cache
 .env
+.coverage
 notes.txt
 test.db

Dockerfile

@@ -1,32 +1,13 @@
-FROM python:3.12.4-slim AS builder
-
-ARG DEV=false
-
-COPY pyproject.toml poetry.lock /
-
-RUN pip install poetry && \
-    POETRY_CMD="poetry export -f requirements.txt --output requirements.txt --without-hashes"; \
-    if [ "$DEV" = "true" ]; then \
-        POETRY_CMD="$POETRY_CMD --with dev"; \
-    fi; \
-    $POETRY_CMD && \
-    pip wheel --no-cache-dir --no-deps --wheel-dir /wheels -r requirements.txt
-
-
-FROM python:3.12.4-slim
-
+FROM ghcr.io/astral-sh/uv:python3.12-alpine
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     PYTHONIOENCODING=utf-8 \
-    PYTHONPATH=/app
-
-WORKDIR /app
-
-COPY --from=builder /wheels /wheels
-COPY ./src .
-
-RUN chmod +x ./scripts/run.sh && \
-    pip install --no-cache /wheels/* && \
-    rm -rf /wheels
-
-CMD ["./scripts/run.sh"]
+    PATH="/src/.venv/bin:$PATH" \
+    PYTHONPATH="/src"
+WORKDIR /src
+COPY ./pyproject.toml ./uv.lock ./run.sh ./
+RUN apk add --no-cache curl && \
+    uv sync --locked && \
+    chmod +x ./run.sh
+COPY ./src ./
+CMD ["./run.sh"]

README.md

@@ -1,35 +1,113 @@
-![Pytest](https://github.com/pypa/hatch/actions/workflows/test.yml/badge.svg)
+![Pytest](https://github.com/pypa/hatch/actions/workflows/protected.yml/badge.svg)
 ![Pytest Coverage](https://github.com/srg12354/fastapi-auth-api/blob/coverage-badge/coverage.svg)
 [![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
 [![Linter Ruff](https://img.shields.io/badge/Linter-Ruff-brightgreen)](https://github.com/charliermarsh/ruff)
 
 
+## About
+Inspired by FastAPI's [OAuth2 with Password (and hashing), Bearer with JWT tokens](https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/), 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](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/) module to verify users access to the protected resources of the API.
 
-## Usage
 
-Build production image:
-```bash
-docker-compose build .
+## 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
+
+<p align="center">
+  <img src="assets/images/request_lifecycle.png" alt="Request Flow" width="800" />
+</p>
+
+
+## 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](proxy/default.conf.tpl):
+
+```nginx
+  location = /protected {
+    include /etc/nginx/snippets/auth_subrequest.conf;
+    proxy_pass http://auth_api/protected;
+  }
 ```
 
-Build development image:
+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](src/policy.json) file. For example, let's say that access to the `/protected` endpoint should be granted only to users with the `moderator` role:
+
+```json
+  "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](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](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:
+
 ```bash
- docker-compose build --build-arg DEV=true auth
+docker compose up -d
 ```
 
-Run app:
+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](src/scripts/create_user.py) below to register a user with a specified role, such as *admin* or *moderator*.
+
 ```bash
-docker-compose up -d
+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](src/policy.json).
+
 
-## Useful Links:
+## References:
   - [OAuth2 with Password (and hashing), Bearer with JWT tokens¶](https://fastapi.tiangolo.com/tutorial/security/oauth2-jwt/)
   - [FastAPI JWT Auth](https://indominusbyte.github.io/fastapi-jwt-auth/)
   - [Nginx. Authentication Based on Subrequest Result](https://docs.nginx.com/nginx/admin-guide/security-controls/configuring-subrequest-authentication/)
-  - [SQLAlchemy 2.0 Asynchronous I/O (asyncio)](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html)
-  - [SQLAlchemy 2.0 Table Configuration with Declarative](https://docs.sqlalchemy.org/en/20/orm/declarative_tables.html)
-  - [Github Actions. Pytest Coverage Comment](https://github.com/marketplace/actions/pytest-coverage-comment)
-  - [Github. FakeRedis](https://fakeredis.readthedocs.io/en/latest)
-  - [Redis Asyncio Examples](https://redis-py.readthedocs.io/en/stable/examples/asyncio_examples.html)
-  - [The mypy configuration file](https://mypy.readthedocs.io/en/stable/config_file.html)
+  - [JSON Web Token (JWT) Debugger](https://www.jwt.io/)
+

docker-compose.yml

@@ -1,10 +1,8 @@
-version: '3.8'
-
 services:
-  auth:
+  app:
     build: .
-    container_name: auth
-    restart: on-failure
+    container_name: app
+    restart: always
     environment:
       - APP_HOST=${APP_HOST}
       - APP_PORT=${APP_PORT}
@@ -15,30 +13,47 @@ services:
       - JWT_SECRET_KEY=${JWT_SECRET_KEY}
       - REDIS_URL=${REDIS_URL}
       - SERVER_DOMAIN=${SERVER_DOMAIN}
-    volumes:
-      - ./src:/app
     depends_on:
-      - db
-      - redis
+      db:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+    volumes:
+      - static_data:/src/.venv/lib/python3.12/site-packages/sqladmin/statics
+    healthcheck:
+      test: ["CMD-SHELL", "curl -f http://${APP_HOST}:${APP_PORT}/health || exit 1"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
 
   db:
     image: postgres:16.3-alpine
     container_name: db
-    restart: on-failure
+    restart: always
     environment:
       - POSTGRES_DB=${POSTGRES_DB}
       - POSTGRES_USER=${POSTGRES_USER}
       - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
     volumes:
       - pg_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
+      interval: 5s
+      timeout: 10s
+      retries: 5
 
   redis:
     image: redis:7.2-alpine
     container_name: redis
-    restart: on-failure
+    restart: always
     command: redis-server --requirepass ${REDIS_PASSWORD}
     volumes:
       - redis_data:/data
+    healthcheck:
+      test: ["CMD-SHELL", "redis-cli -a ${REDIS_PASSWORD} ping"]
+      interval: 5s
+      timeout: 10s
+      retries: 5
 
   nginx:
     build:
@@ -51,12 +66,15 @@ services:
       - NGINX_PORT=${NGINX_PORT}
       - NGINX_SERVER_HOST=${NGINX_SERVER_HOST}
     depends_on:
-      - auth
+      app:
+        condition: service_healthy
     ports:
       - ${NGINX_PORT}:${NGINX_PORT}
     volumes:
       - ./proxy/snippets:/etc/nginx/snippets
+      - static_data:/api/statics
 
 volumes:
   pg_data:
-  redis_data:
+  redis_data:
+  static_data: