263 lines
No EOL
7.7 KiB
Markdown
263 lines
No EOL
7.7 KiB
Markdown
# 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` |