Sentinel is a small security-focused microservices project. It demonstrates authentication, authorization, and service monitoring in a setup you can run locally.
- 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
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/statsrequiresadmin)
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
- Python (FastAPI)
- PostgreSQL
- Docker + Docker Compose
- NGINX
- Prometheus + Grafana
auth-service/ # Authentication and token handling
protected-service/ # Role-protected endpoints
monitoring/ # Prometheus + Grafana config
docker-compose.yml # Full local stack
-
Copy environment variables if needed:
cp .env.example .env
-
Start the stack:
docker compose up --build
-
Open the services:
- Gateway: http://localhost
- Grafana: http://localhost/grafana/
- Register a user through the auth service
- Login to receive a token
- Call protected endpoints with that token
- View metrics in Grafana/Prometheus
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
POST /auth/register- create userPOST /auth/login- login and get JWTGET /auth/verify- verify JWTGET /auth/me- get current authenticated user
GET /public/info- public endpoint (no token required)GET /internal- authenticated endpointGET /users/me- authenticated endpointGET /admin/stats- admin-only endpoint (RBAC)
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.
Use this section for quick validation, then use Swagger for full endpoint schemas and examples.
-
Open Swagger docs:
- Auth:
http://localhost/auth/docs - Protected:
http://localhost/protected/docs
- Auth:
-
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>"
-
Expected results:
/internalreturns200 OK/admin/statsreturns403 Forbiddenfor non-admin users
This project intentionally keeps admin promotion out of public APIs.
-
Create/login a user first (for example,
alice). -
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';"
-
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
I built Sentinel to practice practical backend security concepts:
- JWT authentication
- Password hashing with bcrypt
- RBAC enforcement
- Security observability with metrics and dashboards
- This is a learning project, not a production deployment.
- If ports are already in use, update
docker-compose.ymland restart.