Skip to content
KareemAssafPublic

About

Guards your internal services like a watchful sentinel

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Sentinel

Sentinel is a small security-focused microservices project. It demonstrates authentication, authorization, and service monitoring in a setup you can run locally.

What It Does

  • Handles user registration and login with JWT-based auth
  • Protects routes with role-based access control (RBAC)
  • Routes traffic through an NGINX gateway
  • Exposes Prometheus metrics and dashboards in Grafana

Zero Trust Model

Sentinel follows a Zero Trust approach: each service validates authentication and authorization independently. The gateway handles routing, but it is not trusted as the only security boundary.

  • Auth service issues and verifies JWTs
  • Protected service validates JWTs again before serving private routes
  • RBAC is enforced at endpoint level (/admin/stats requires admin)

Architecture

Request flow:
Client
   -> NGINX Gateway (:80)
       -> /auth/* -> Auth Service (:8001) -> PostgreSQL (:5432)
       -> /internal, /users, /admin, /public -> Protected Service (:8000)
       -> /grafana/ -> Grafana

Monitoring flow (internal Docker network):
Prometheus -> scrape Auth Service /metrics
Prometheus -> scrape Protected Service /metrics
Grafana -> query Prometheus

Tech Stack

  • Python (FastAPI)
  • PostgreSQL
  • Docker + Docker Compose
  • NGINX
  • Prometheus + Grafana

Project Structure

auth-service/         # Authentication and token handling
protected-service/    # Role-protected endpoints
monitoring/           # Prometheus + Grafana config
docker-compose.yml    # Full local stack

Quick Start

  1. Copy environment variables if needed:

    cp .env.example .env
  2. Start the stack:

    docker compose up --build
  3. Open the services:

Typical Flow

  1. Register a user through the auth service
  2. Login to receive a token
  3. Call protected endpoints with that token
  4. View metrics in Grafana/Prometheus

API Routes (Via Gateway)

Base URL: http://localhost

For full request/response schemas, use Swagger docs:

  • Auth Service Swagger: http://localhost/auth/docs
  • Protected Service Swagger: http://localhost/protected/docs

Auth Service

  • POST /auth/register - create user
  • POST /auth/login - login and get JWT
  • GET /auth/verify - verify JWT
  • GET /auth/me - get current authenticated user

Protected Service

  • GET /public/info - public endpoint (no token required)
  • GET /internal - authenticated endpoint
  • GET /users/me - authenticated endpoint
  • GET /admin/stats - admin-only endpoint (RBAC)

Monitoring

  • GET /grafana/ - Grafana UI (login required)

Metrics endpoints are internal-only and scraped by Prometheus from the Docker network.

Note: Keep this README as a quick start, and use Swagger as the source of truth for endpoint details.

How To Use

Use this section for quick validation, then use Swagger for full endpoint schemas and examples.

  1. Open Swagger docs:

    • Auth: http://localhost/auth/docs
    • Protected: http://localhost/protected/docs
  2. Quick smoke test with curl:

    curl -X POST http://localhost/auth/register \
      -H "Content-Type: application/json" \
      -d '{"username":"alice","email":"alice@example.com","password":"SecurePass123"}'
    
     # Login template (copy access_token from the response)
     curl -X POST http://localhost/auth/login \
        -H "Content-Type: application/json" \
        -d '{"username":"alice","password":"SecurePass123"}'
    
     # Use token when needed
     curl http://localhost/internal -H "Authorization: Bearer <TOKEN>"
     curl -i http://localhost/admin/stats -H "Authorization: Bearer <TOKEN>"
  3. Expected results:

    • /internal returns 200 OK
    • /admin/stats returns 403 Forbidden for non-admin users

Create An Admin (Manual SQL)

This project intentionally keeps admin promotion out of public APIs.

  1. Create/login a user first (for example, alice).

  2. Promote the user in Postgres:

    docker compose exec postgres psql -U "$POSTGRES_USER" -d "$POSTGRES_DB" \
      -c "UPDATE users SET role='admin' WHERE username='alice';"
  3. Login again to get a fresh token with admin role, then test:

    curl -i http://localhost/admin/stats -H "Authorization: Bearer $TOKEN"

    Expected: 200 OK

Why This Project

I built Sentinel to practice practical backend security concepts:

  • JWT authentication
  • Password hashing with bcrypt
  • RBAC enforcement
  • Security observability with metrics and dashboards

Notes

  • This is a learning project, not a production deployment.
  • If ports are already in use, update docker-compose.yml and restart.

About

Guards your internal services like a watchful sentinel

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages