Repo initialisation
This commit is contained in:
Serge NOEL
454
web-gateway/INTEGRATION.md
Normal file
454
web-gateway/INTEGRATION.md
Normal file
@@ -0,0 +1,454 @@
|
||||
# RDP Web Gateway Integration Guide
|
||||
|
||||
This guide explains how to integrate the RDP Web Gateway with RdpBroker for a complete browser-based RDP solution.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ User Browser │
|
||||
│ (HTML5/WS) │
|
||||
└────────┬────────┘
|
||||
│ HTTP/WebSocket
|
||||
│ Port 80/443
|
||||
↓
|
||||
┌─────────────────────┐
|
||||
│ RDP Web Gateway │
|
||||
│ (Node.js) │
|
||||
│ - Session Mgmt │
|
||||
│ - WebSocket Proxy │
|
||||
└────────┬────────────┘
|
||||
│ RDP Protocol
|
||||
│ Port 3389
|
||||
↓
|
||||
┌─────────────────────┐
|
||||
│ RdpBroker │
|
||||
│ (C Application) │
|
||||
│ - Samba AD Auth │
|
||||
│ - Target Selection │
|
||||
│ - RDP Forwarding │
|
||||
└────────┬────────────┘
|
||||
│ RDP Protocol
|
||||
│ Port 3389
|
||||
↓
|
||||
┌─────────────────────┐
|
||||
│ Target RDP Servers │
|
||||
│ (Windows/Linux) │
|
||||
└─────────────────────┘
|
||||
```
|
||||
|
||||
## Deployment Steps
|
||||
|
||||
### 1. Deploy RdpBroker
|
||||
|
||||
First, ensure RdpBroker is running:
|
||||
|
||||
```bash
|
||||
# Deploy RdpBroker
|
||||
cd /data/apps/RdpBroker
|
||||
helm install rdpbroker ./chart/rdpbroker \
|
||||
-f rdpbroker-values.yaml \
|
||||
-n rdpbroker \
|
||||
--create-namespace
|
||||
|
||||
# Verify deployment
|
||||
kubectl get pods -n rdpbroker
|
||||
```
|
||||
|
||||
### 2. Deploy RDP Web Gateway
|
||||
|
||||
```bash
|
||||
# Build the web gateway image
|
||||
cd /data/apps/RdpBroker/web-gateway
|
||||
docker build -t rdp-web-gateway:1.0.0 .
|
||||
|
||||
# Tag and push to registry
|
||||
docker tag rdp-web-gateway:1.0.0 yourusername/rdp-web-gateway:1.0.0
|
||||
docker push yourusername/rdp-web-gateway:1.0.0
|
||||
|
||||
# Deploy with Helm
|
||||
helm install rdp-web-gateway ./chart/rdp-web-gateway \
|
||||
-f web-gateway-values.yaml \
|
||||
-n rdpbroker
|
||||
```
|
||||
|
||||
### 3. Configure Integration
|
||||
|
||||
Create `web-gateway-values.yaml`:
|
||||
|
||||
```yaml
|
||||
image:
|
||||
repository: yourusername/rdp-web-gateway
|
||||
tag: "1.0.0"
|
||||
|
||||
replicaCount: 2
|
||||
|
||||
config:
|
||||
rdpBroker:
|
||||
host: "rdpbroker" # Service name in Kubernetes
|
||||
port: 3389
|
||||
|
||||
server:
|
||||
port: 8080
|
||||
logLevel: "info"
|
||||
|
||||
session:
|
||||
timeout: 3600000 # 1 hour
|
||||
|
||||
service:
|
||||
type: LoadBalancer
|
||||
port: 80
|
||||
|
||||
autoscaling:
|
||||
enabled: true
|
||||
minReplicas: 2
|
||||
maxReplicas: 10
|
||||
|
||||
# Optional: Enable ingress for HTTPS
|
||||
ingress:
|
||||
enabled: true
|
||||
className: "nginx"
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: "letsencrypt-prod"
|
||||
hosts:
|
||||
- host: rdp.example.com
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
tls:
|
||||
- secretName: rdp-tls
|
||||
hosts:
|
||||
- rdp.example.com
|
||||
```
|
||||
|
||||
## Network Configuration
|
||||
|
||||
### Service Communication
|
||||
|
||||
The web gateway needs to communicate with RdpBroker:
|
||||
|
||||
```yaml
|
||||
# In RdpBroker values
|
||||
service:
|
||||
type: ClusterIP # Internal only
|
||||
port: 3389
|
||||
|
||||
# In Web Gateway values
|
||||
config:
|
||||
rdpBroker:
|
||||
host: "rdpbroker" # Kubernetes service name
|
||||
port: 3389
|
||||
```
|
||||
|
||||
### Network Policies (Optional)
|
||||
|
||||
For enhanced security, configure network policies:
|
||||
|
||||
```yaml
|
||||
# Web Gateway can access RdpBroker
|
||||
networkPolicy:
|
||||
enabled: true
|
||||
egress:
|
||||
- to:
|
||||
- podSelector:
|
||||
matchLabels:
|
||||
app: rdpbroker
|
||||
ports:
|
||||
- protocol: TCP
|
||||
port: 3389
|
||||
```
|
||||
|
||||
## Testing the Integration
|
||||
|
||||
### 1. Verify Services
|
||||
|
||||
```bash
|
||||
# Check both services are running
|
||||
kubectl get svc -n rdpbroker
|
||||
|
||||
# Expected output:
|
||||
# NAME TYPE PORT(S)
|
||||
# rdpbroker ClusterIP 3389/TCP
|
||||
# rdp-web-gateway LoadBalancer 80:xxxxx/TCP
|
||||
```
|
||||
|
||||
### 2. Test Connectivity
|
||||
|
||||
```bash
|
||||
# Get web gateway URL
|
||||
export WEB_GATEWAY_IP=$(kubectl get svc rdp-web-gateway -n rdpbroker -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
|
||||
echo "Web Gateway: http://$WEB_GATEWAY_IP"
|
||||
|
||||
# Test health endpoint
|
||||
curl http://$WEB_GATEWAY_IP/health
|
||||
```
|
||||
|
||||
### 3. Test Web Interface
|
||||
|
||||
1. Open browser to `http://$WEB_GATEWAY_IP`
|
||||
2. Login with Samba AD credentials
|
||||
3. Select a target from the list
|
||||
4. Verify RDP connection works
|
||||
|
||||
### 4. Monitor Logs
|
||||
|
||||
```bash
|
||||
# Web gateway logs
|
||||
kubectl logs -f deployment/rdp-web-gateway -n rdpbroker
|
||||
|
||||
# RdpBroker logs
|
||||
kubectl logs -f deployment/rdpbroker -n rdpbroker
|
||||
```
|
||||
|
||||
## Flow Diagram
|
||||
|
||||
### Authentication Flow
|
||||
|
||||
```
|
||||
Browser → Web Gateway: POST /api/auth/login
|
||||
{username, password}
|
||||
← Web Gateway: {sessionId: "uuid"}
|
||||
|
||||
Web Gateway → RdpBroker: RDP Connection
|
||||
Auth: username/password
|
||||
← RdpBroker: → Samba AD: LDAP Bind
|
||||
← Auth Result
|
||||
|
||||
Web Gateway → Browser: Login Success
|
||||
```
|
||||
|
||||
### Connection Flow
|
||||
|
||||
```
|
||||
Browser → Web Gateway: WebSocket /ws/rdp
|
||||
{type: "connect", target}
|
||||
|
||||
Web Gateway → RdpBroker: TCP Socket (port 3389)
|
||||
Auth + Target Selection
|
||||
← RdpBroker: Target Menu Response
|
||||
|
||||
Web Gateway → RdpBroker: Selected Target
|
||||
← RdpBroker: → Target RDP Server
|
||||
← RDP Stream
|
||||
|
||||
Web Gateway → Browser: RDP Frames (Binary WebSocket)
|
||||
|
||||
Browser → Web Gateway: Mouse/Keyboard Events
|
||||
Web Gateway → RdpBroker: RDP Protocol Events
|
||||
RdpBroker → Target: Forward Events
|
||||
```
|
||||
|
||||
## Production Configuration
|
||||
|
||||
### Enable HTTPS/WSS
|
||||
|
||||
```yaml
|
||||
# values.yaml
|
||||
ingress:
|
||||
enabled: true
|
||||
className: "nginx"
|
||||
annotations:
|
||||
cert-manager.io/cluster-issuer: "letsencrypt-prod"
|
||||
nginx.ingress.kubernetes.io/websocket-services: "rdp-web-gateway"
|
||||
hosts:
|
||||
- host: rdp.example.com
|
||||
paths:
|
||||
- path: /
|
||||
pathType: Prefix
|
||||
tls:
|
||||
- secretName: rdp-tls
|
||||
hosts:
|
||||
- rdp.example.com
|
||||
```
|
||||
|
||||
### Session Security
|
||||
|
||||
```yaml
|
||||
secrets:
|
||||
sessionSecret: "your-secure-random-key-here"
|
||||
```
|
||||
|
||||
Generate secure key:
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
### Resource Limits
|
||||
|
||||
```yaml
|
||||
resources:
|
||||
limits:
|
||||
cpu: 1000m
|
||||
memory: 1Gi
|
||||
requests:
|
||||
cpu: 200m
|
||||
memory: 256Mi
|
||||
|
||||
autoscaling:
|
||||
enabled: true
|
||||
minReplicas: 2
|
||||
maxReplicas: 10
|
||||
targetCPUUtilizationPercentage: 70
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Web Gateway Can't Connect to RdpBroker
|
||||
|
||||
```bash
|
||||
# Test from web gateway pod
|
||||
kubectl exec -it deployment/rdp-web-gateway -n rdpbroker -- sh
|
||||
|
||||
# Inside pod
|
||||
nc -zv rdpbroker 3389
|
||||
nslookup rdpbroker
|
||||
```
|
||||
|
||||
### WebSocket Connection Fails
|
||||
|
||||
Check ingress configuration for WebSocket support:
|
||||
|
||||
```yaml
|
||||
# For nginx ingress
|
||||
annotations:
|
||||
nginx.ingress.kubernetes.io/websocket-services: "rdp-web-gateway"
|
||||
```
|
||||
|
||||
### Authentication Fails
|
||||
|
||||
Check logs on both services:
|
||||
|
||||
```bash
|
||||
# Web gateway
|
||||
kubectl logs deployment/rdp-web-gateway -n rdpbroker | grep -i auth
|
||||
|
||||
# RdpBroker
|
||||
kubectl logs deployment/rdpbroker -n rdpbroker | grep -i auth
|
||||
```
|
||||
|
||||
### High Latency
|
||||
|
||||
1. Check network latency between services
|
||||
2. Ensure services are in same cluster/region
|
||||
3. Consider increasing resources
|
||||
4. Enable connection pooling
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Metrics to Monitor
|
||||
|
||||
- Active WebSocket connections
|
||||
- RDP session count
|
||||
- Authentication success/failure rate
|
||||
- Response times
|
||||
- Resource usage (CPU/Memory)
|
||||
|
||||
### Prometheus Integration
|
||||
|
||||
```yaml
|
||||
# serviceMonitor.yaml
|
||||
apiVersion: monitoring.coreos.com/v1
|
||||
kind: ServiceMonitor
|
||||
metadata:
|
||||
name: rdp-web-gateway
|
||||
spec:
|
||||
selector:
|
||||
matchLabels:
|
||||
app: rdp-web-gateway
|
||||
endpoints:
|
||||
- port: http
|
||||
path: /metrics
|
||||
```
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
1. **Always use HTTPS/WSS in production**
|
||||
2. **Implement rate limiting** on authentication endpoints
|
||||
3. **Use strong session secrets**
|
||||
4. **Enable network policies** to restrict traffic
|
||||
5. **Regular security audits** and updates
|
||||
6. **Monitor for suspicious activity**
|
||||
7. **Implement session timeout** and cleanup
|
||||
8. **Use CSP headers** for XSS protection
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
1. **Enable compression** for HTTP responses
|
||||
2. **Use CDN** for static assets
|
||||
3. **Implement caching** where appropriate
|
||||
4. **Optimize WebSocket buffer sizes**
|
||||
5. **Use horizontal pod autoscaling**
|
||||
6. **Consider using Redis** for session storage in multi-replica setup
|
||||
|
||||
## Upgrading
|
||||
|
||||
### Rolling Update
|
||||
|
||||
```bash
|
||||
# Update web gateway
|
||||
helm upgrade rdp-web-gateway ./chart/rdp-web-gateway \
|
||||
-f web-gateway-values.yaml \
|
||||
-n rdpbroker
|
||||
|
||||
# Monitor rollout
|
||||
kubectl rollout status deployment/rdp-web-gateway -n rdpbroker
|
||||
```
|
||||
|
||||
### Zero-Downtime Deployment
|
||||
|
||||
Ensure proper liveness/readiness probes:
|
||||
|
||||
```yaml
|
||||
livenessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: http
|
||||
initialDelaySeconds: 30
|
||||
|
||||
readinessProbe:
|
||||
httpGet:
|
||||
path: /health
|
||||
port: http
|
||||
initialDelaySeconds: 10
|
||||
```
|
||||
|
||||
## Complete Example Deployment
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# 1. Deploy RdpBroker
|
||||
helm install rdpbroker ./chart/rdpbroker \
|
||||
--set image.repository=yourusername/rdpbroker \
|
||||
--set image.tag=1.0.0 \
|
||||
--set config.sambaAD.server=ad.example.com \
|
||||
--set config.sambaAD.baseDN="DC=example,DC=com" \
|
||||
-n rdpbroker --create-namespace
|
||||
|
||||
# 2. Wait for RdpBroker to be ready
|
||||
kubectl wait --for=condition=available --timeout=300s \
|
||||
deployment/rdpbroker -n rdpbroker
|
||||
|
||||
# 3. Deploy Web Gateway
|
||||
helm install rdp-web-gateway ./chart/rdp-web-gateway \
|
||||
--set image.repository=yourusername/rdp-web-gateway \
|
||||
--set image.tag=1.0.0 \
|
||||
--set config.rdpBroker.host=rdpbroker \
|
||||
--set ingress.enabled=true \
|
||||
--set ingress.hosts[0].host=rdp.example.com \
|
||||
-n rdpbroker
|
||||
|
||||
# 4. Get access URL
|
||||
kubectl get ingress -n rdpbroker
|
||||
```
|
||||
|
||||
## Support
|
||||
|
||||
For issues:
|
||||
1. Check logs on both services
|
||||
2. Verify network connectivity
|
||||
3. Review configuration
|
||||
4. Check resource usage
|
||||
5. Consult documentation
|
||||
|
||||
For questions, open an issue on the project repository.
|
||||
Reference in New Issue
Block a user