# Gateway & Auth Layer - DIDI Backend 🔐

## Quick Start 🚀

```bash
# 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 🎯

```bash
# 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
```env
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
```env
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)
```bash
# 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)
```bash
# Check Keycloak health
curl http://localhost:18280/health/ready

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

## Troubleshooting 🔧

### Kong won't start?
```bash
# 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?
```bash
# 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?
```bash
# 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
```bash
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
```bash
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`