hellgate - Secure, Scalable API Gateway & Centralized Authentication

A production-ready API Gateway and Authentication Service solution for microservices architecture, designed to be technology-agnostic and scalable.

Architecture Overview

                    ┌─────────────────┐
                    │   Client Apps   │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │   Kong Gateway  │
                    │  (Entry Point)  │
                    └────────┬────────┘
                             │
                    ┌────────▼────────┐
                    │ Spring Cloud    │
                    │    Gateway      │
                    │ (Custom Logic)  │
                    └────────┬────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
  ┌─────▼─────┐      ┌───────▼───────┐   ┌──────▼──────┐
  │   Auth    │      │ Microservice 1 │   │Microservice 2│
  │  Service  │      │   (Example)    │   │  (Example)  │
  └───────────┘      └────────────────┘   └─────────────┘
        │
        │
  ┌─────▼─────┐      ┌──────────────┐
  │   Redis   │      │   Eureka     │
  │  (Cache)  │      │  (Discovery) │
  └───────────┘      └──────────────┘

Components

1. API Gateway (Kong + Spring Cloud Gateway)

• Kong Gateway: Primary entry point with plugins for JWT validation, rate limiting, IP filtering
• Spring Cloud Gateway: Handles custom routing logic, circuit breakers, and advanced transformations
• Features:
  • Dynamic routing based on path, headers, query parameters
  • Service discovery integration (Eureka)
  • Load balancing across service instances
  • Request/response transformation
  • Circuit breakers and retries
  • JWT pre-validation
  • Rate limiting (global and per-user/per-API)
  • IP whitelisting/blacklisting
  • Comprehensive logging and metrics

2. Authentication Service (Spring Boot)

• Centralized authentication and authorization
• JWT token issuance and management
• Refresh token support
• Token revocation (Redis-based blacklist)
• Role-Based Access Control (RBAC)
• OAuth2/OpenID Connect support
• Audit logging

3. Supporting Infrastructure

• Eureka Server: Service discovery
• Redis: Distributed caching, rate limiting, token blacklist
• Prometheus + Grafana: Metrics and monitoring
• ELK Stack / Loki: Centralized logging
• Zipkin/Jaeger: Distributed tracing

Quick Start

Prerequisites

• Docker and Docker Compose
• JDK 17 or higher
• Maven 3.8+
• Kubernetes cluster (for K8s deployment)

Local Development (Docker Compose)

1. Start all services:

docker compose up -d

2. Wait for services to be healthy:

# Check service status
docker compose ps

# View logs
docker compose logs -f auth-service

3. Access services:

• Kong Admin API: http://localhost:8001
• Kong Gateway: http://localhost:8000
• Auth Service: http://localhost:8080
• Eureka Dashboard: http://localhost:8761
• Grafana: http://localhost:3000 (admin/admin)
• Prometheus: http://localhost:9090

Kubernetes Deployment

1. Apply configurations:

kubectl apply -f k8s/

2. Check deployment status:

kubectl get pods -n hellgate
kubectl get services -n hellgate

Service Endpoints

Authentication Service

Public Endpoints (No Auth Required)

• POST /api/auth/login - User login
• POST /api/auth/register - User registration
• POST /api/auth/refresh - Refresh access token
• GET /api/auth/.well-known/jwks.json - JWKS endpoint for token verification

Protected Endpoints (Require JWT)

• GET /api/auth/me - Get current user info
• POST /api/auth/logout - Logout and revoke token
• GET /api/auth/users - List users (Admin only)
• GET /api/auth/users/{id} - Get user details
• PUT /api/auth/users/{id}/roles - Update user roles (Admin only)

API Gateway

All microservice requests should go through:

• http://localhost:8000/api/{service-name}/{path}

Example:

• http://localhost:8000/api/user-service/users → routes to user-service
• http://localhost:8000/api/order-service/orders → routes to order-service

Configuration

Environment Variables

See individual service READMEs:

• auth-service/README.md
• spring-cloud-gateway/README.md
• kong/README.md

Key Configuration Files

• kong/kong.yml - Kong Gateway configuration
• auth-service/src/main/resources/application.yml - Auth service config
• docker-compose.yml - Local development setup
• k8s/ - Kubernetes manifests

Security Features

1. JWT Validation: All requests validated at gateway level
2. Rate Limiting: Configurable per-user and per-API limits
3. IP Filtering: Whitelist/blacklist support
4. Token Revocation: Redis-based token blacklist
5. RBAC: Role-based access control
6. HTTPS: TLS/SSL support (configure in production)
7. CORS: Configurable CORS policies

Monitoring & Observability

Metrics

• Gateway metrics: http://localhost:9090 (Prometheus)
• Custom dashboards: http://localhost:3000 (Grafana)

Logging

• Centralized logs: Check ELK stack or Loki
• Service logs: docker-compose logs -f {service-name}

Tracing

• Distributed traces: http://localhost:9411 (Zipkin)

Testing

Run Tests

# Auth Service tests
cd auth-service
mvn test

# Integration tests
mvn verify -P integration-tests

Example Test Requests

# Register a user
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"password123","email":"test@example.com"}'

# Login
curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","password":"password123"}'

# Access protected endpoint (use token from login response)
curl -X GET http://localhost:8000/api/auth-service/api/auth/me \
  -H "Authorization: Bearer {token}"

Technology Stack

• API Gateway: Kong Gateway, Spring Cloud Gateway
• Auth Service: Spring Boot 3.x, Spring Security, OAuth2
• Service Discovery: Eureka (Spring Cloud Netflix)
• Caching: Redis
• Containerization: Docker
• Orchestration: Kubernetes
• Monitoring: Prometheus, Grafana
• Logging: ELK Stack / Grafana Loki
• Tracing: Zipkin / Jaeger

Project Structure

spring-gateway/
├── auth-service/              # Authentication Service (Spring Boot)
├── spring-cloud-gateway/      # Spring Cloud Gateway (Custom Logic)
├── kong/                      # Kong Gateway Configuration
├── example-services/          # Example Microservices
│   ├── user-service/
│   └── order-service/
├── k8s/                       # Kubernetes Manifests
├── monitoring/                # Prometheus, Grafana configs
├── logging/                   # ELK/Loki configurations
├── docker-compose.yml         # Local development setup
└── README.md                  # This file

Development

Adding a New Microservice

1. Create service in example-services/
2. Register with Eureka
3. Configure route in Kong (kong/kong.yml)
4. Add route in Spring Cloud Gateway if needed
5. Update service discovery config

Extending Authentication

The authentication service is designed to be extensible:

• Add custom authentication providers
• Integrate with external IDPs (Okta, Azure AD, Keycloak)
• Extend RBAC with custom permissions

Production Deployment

1. Security:

   • Enable HTTPS/TLS
   • Use secrets management (K8s secrets, Vault)
   • Configure proper CORS policies
   • Set up firewall rules

2. Scalability:

   • Horizontal scaling via Kubernetes
   • Database connection pooling
   • Redis cluster for high availability

3. Monitoring:

   • Set up alerting rules
   • Configure log retention policies
   • Set up distributed tracing

License

MIT License

Contributing

See CONTRIBUTING.md for guidelines.

Support

For issues and questions, please open an issue in the repository.