didi-lot2-backend/backend/services/gateway-auth-layer/README.md

Gateway & Auth Layer - DIDI Backend 🔐

Quick Start 🚀

# Recommended: Start via unified deployment manager
./deploy/didi.sh staging start

Staging URLs:

Service	URL
Kong Gateway	http://localhost:18100
Kong Admin API	http://localhost:18101
Kong Manager UI	http://localhost:18102
Keycloak	http://localhost:18280

Overview 🔍

The Gateway & Auth Layer provides API management and authentication services:

Services

Service	Container Name	Staging Ports	Purpose
didiKong	staging-gatewayAuthLayer-kong	18100, 18101, 18102	API Gateway, routing, rate limiting
didiKeycloak	staging-gatewayAuthLayer-keycloak	18280	Identity provider, SSO, OAuth2/OIDC

Architecture 🏗️

┌─────────────────────────────────────────────────────────┐
│                  Gateway & Auth Layer                   │
├───────────────────────┬─────────────────────────────────┤
│       didiKong        │        didiKeycloak             │
│                       │                                 │
│  • API Gateway        │  • Identity Provider            │
│  • Route Management   │  • User Management              │
│  • Rate Limiting      │  • OAuth2/OIDC                  │
│  • CORS Handling      │  • Custom Theme                 │
│  • Load Balancing     │  • Realm Import                 │
│                       │                                 │
│  Ports: 18100-18102   │  Port: 18280                    │
└───────────────────────┴─────────────────────────────────┘
                   │                    │
                   ▼                    ▼
        ┌──────────────────────────────────────┐
        │        Protected Services            │
        │  • Orchestrator API (port 18000)     │
        │  • Analysis Service (port 18004)     │
        │  • Admin Dashboard (port 13003)      │
        └──────────────────────────────────────┘

Service Communication Flow 📬

Client Request → Kong Gateway (18100) → Route Rules → Backend Service
                      ↓
                 Rate Limiting
                      ↓
                 CORS Headers
                      ↓
              (Optional) Keycloak Auth

Kong Configuration 🛠️

DB-less Mode

Kong runs in declarative (DB-less) mode with configuration in didiKong/declarative/kong.yml

Configured Routes (Staging)

• /api/v1/catalog/* → Orchestrator (18000)
• /api/v1/pipelines/* → Orchestrator (18000)
• /api/v1/runs/* → Orchestrator (18000)
• /orchestrator/health → Orchestrator health check
• /analysis/health → Analysis service health check
• /didiai/* → AI Gateway (via DIDIAI_GATEWAY_URL)
• /admin/* → Admin Dashboard (13003)

Enabled Plugins

• CORS: Cross-origin resource sharing
• Rate Limiting: 100/min, 2000/hr, 10000/day
• Request ID: UUID tracking with X-Request-ID
• Size Limiting: 100MB max for media files
• Response Transform: Add gateway headers

Keycloak Configuration 🔑

Admin Access

• URL: http://localhost:8280 (standalone) or http://localhost:18280 (staging)
• Username: admin
• Password: keycloak123

Imported Realm

• Realm Name: misinformation
• Theme: misinformation-theme (custom)
• Location: didiKeycloak/realm-import/misinformation-realm.json

Pre-configured Elements

• Client applications
• User roles and groups
• Authentication flows
• Custom login theme

Quick Commands 🎯

# Service Management
make up              # Start both services
make down            # Stop both services
make restart         # Restart both services
make status          # Check service status
make logs            # View logs for both services

# Individual Service Control
make up-kong         # Start only Kong
make up-keycloak     # Start only Keycloak
make logs-kong       # View Kong logs
make logs-keycloak   # View Keycloak logs

# Kong Management
make kong-reload     # Reload Kong configuration
make kong-validate   # Validate kong.yml syntax

# Keycloak Management
make keycloak-export # Export current realm configuration

# Maintenance
make clean           # Remove containers and volumes
make rebuild         # Rebuild all images
make health          # Health check both services

Environment Configuration 🔐

Kong Environment

KONG_DATABASE=off                    # DB-less mode
KONG_DECLARATIVE_CONFIG=/kong/declarative/kong.yml
KONG_PROXY_LISTEN=0.0.0.0:8000
KONG_ADMIN_LISTEN=0.0.0.0:8001

Keycloak Environment

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=keycloak123
KC_DB_URL=jdbc:postgresql://dataLayer-postgres:5432/keycloak_db
KC_DB_USERNAME=postgres
KC_DB_PASSWORD=postgres123

Testing the Gateway 🧪

Test Kong Gateway (Staging)

# Check Kong status
curl http://localhost:18101/status

# Test orchestrator route through Kong
curl http://localhost:18100/orchestrator/health

# Test analysis route through Kong
curl http://localhost:18100/analysis/health

Test Keycloak (Staging)

# Check Keycloak health
curl http://localhost:18280/health/ready

# Access Keycloak admin console
open http://localhost:18280

Troubleshooting 🔧

Kong won't start?

# Check configuration validity
make kong-validate

# Check logs
make logs-kong

# Verify declarative config exists
ls -la didiKong/declarative/kong.yml

Keycloak won't start?

# Check if database exists
docker exec dataLayer-postgres psql -U postgres -c "\l" | grep keycloak_db

# Create database if missing
make init-db

# Check logs
make logs-keycloak

Services can't connect?

# Verify network exists
docker network ls | grep didi-backend

# Check all services are on same network
docker inspect gatewayAuthLayer-kong | grep NetworkMode

Security Considerations 🛡️

1. Change default passwords in production
2. Enable HTTPS for all services
3. Configure proper CORS origins (not wildcard)
4. Set up proper rate limiting per consumer
5. Enable authentication on sensitive routes
6. Use secrets management for credentials

Integration with Other Layers 🔗

Prerequisites

• Data Layer must be running (PostgreSQL for Keycloak)
• Orchestration Layer services for API routing
• Network didi-backend must exist

Downstream Services

• UI Layer will use Kong Gateway for API access
• All services can integrate with Keycloak for SSO

Development 🛠️

Access Service Shells

make shell-kong      # Kong shell
make shell-keycloak  # Keycloak shell

Modify Kong Routes

1. Edit didiKong/declarative/kong.yml
2. Validate: make kong-validate
3. Reload: make kong-reload

Export Keycloak Configuration

make keycloak-export
# Exported to didiKeycloak/realm-export/

Next Steps 📋

1. Configure Keycloak clients for each service
2. Set up Kong OAuth2 plugin with Keycloak
3. Add service-specific rate limiting
4. Configure monitoring and alerting
5. Set up SSL/TLS termination

---

Version: 1.0.0
Network: didi-backend
Project: didiBackend