RdpBroker/web-gateway/README.md

RDP Web Gateway

HTML5 WebSocket-based gateway for accessing RDP connections through a web browser. This service sits in front of RdpBroker and provides a modern web interface for remote desktop access.

Features

• 🌐 Browser-Based Access - Connect to RDP sessions from any modern web browser
• 🔒 Secure WebSocket - Real-time bidirectional communication
• 🎨 Modern UI - Clean, responsive interface
• 🔑 Simplified Authentication - Credentials passed directly to RdpBroker
• 📊 Service Health Monitoring - Automatic RdpBroker availability checks
• 🎯 Dynamic Target Loading - Targets fetched from configuration or RdpBroker
• ⚡ Low Latency - Optimized for performance
• ☁️ Kubernetes Native - Console-only logging for cloud environments

Architecture

User Browser (HTML5/WebSocket)
          ↓
    RDP Web Gateway (Node.js)
          ↓
      RdpBroker (RDP)
          ↓
    Target RDP Servers

Prerequisites

• Node.js 18+
• RdpBroker service running
• Modern web browser with WebSocket support

Installation

Local Development

cd web-gateway

# Install dependencies
npm install

# Copy environment file
cp .env.example .env

# Edit configuration
nano .env

# Start development server
npm run dev

Docker Build

docker build -t rdp-web-gateway:latest .

Configuration

Edit .env file:

PORT=8080
RDP_BROKER_HOST=rdpbroker
RDP_BROKER_PORT=3389
NODE_ENV=production

# Optional: Pre-configure RDP targets (JSON array)
# If not set, RdpBroker will provide targets dynamically
RDP_TARGETS=[{"name":"Server1","host":"srv1.example.com","port":3389,"description":"Production Server"}]

Environment Variables

Variable	Description	Default
PORT	Web server listening port	8080
RDP_BROKER_HOST	RdpBroker hostname	rdpbroker
RDP_BROKER_PORT	RdpBroker port	3389
RDP_TARGETS	JSON array of pre-configured targets	null
NODE_ENV	Environment mode	development

Usage

Access the Web Interface

1. Open your browser to http://localhost:8080
2. Enter your credentials (validated against Samba AD via RdpBroker)
3. Select a target from the list
4. Connect and use the remote desktop

API Endpoints

GET /health

Health check endpoint for monitoring the web gateway.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 12345
}

GET /api/broker-status

Check if RdpBroker service is available.

Response:

{
  "available": true,
  "broker": "rdpbroker:3389",
  "timestamp": "2025-12-04T10:30:00.000Z"
}

GET /api/targets

Fetch available RDP targets.

Success Response (200):

{
  "targets": [
    {
      "name": "Windows Server 2022",
      "host": "ws2022.example.com",
      "port": 3389,
      "description": "Production Windows Server"
    }
  ],
  "timestamp": "2025-12-04T10:30:00.000Z"
}

Service Unavailable (503):

{
  "error": "RdpBroker service is unavailable. Please contact your administrator.",
  "timestamp": "2025-12-04T10:30:00.000Z"
}

WebSocket Protocol

Connect to ws://localhost:8080/ws/rdp

Client → Server Messages

Connect to target:

{
  "type": "connect",
  "username": "user@domain.com",
  "password": "password123",
  "target": {
    "name": "Server 01",
    "host": "192.168.1.10",
    "port": 3389
  }
}

Mouse event:

{
  "type": "mouse",
  "action": "move|down|up|wheel",
  "x": 100,
  "y": 200,
  "button": 0,
  "deltaY": 0
}

Keyboard event:

{
  "type": "keyboard",
  "action": "down|up",
  "key": "a",
  "code": "KeyA",
  "ctrlKey": false,
  "altKey": false,
  "shiftKey": false
}

Special command:

{
  "type": "special",
  "action": "ctrl-alt-del"
}

Server → Client Messages

Connected:

{
  "type": "connected",
  "target": "Server 01"
}

Resize canvas:

{
  "type": "resize",
  "width": 1920,
  "height": 1080
}

Error:

{
  "type": "error",
  "error": "Error message"
}

Deployment

See the Helm chart in chart/rdp-web-gateway/ for Kubernetes deployment.

helm install rdp-web-gateway ./chart/rdp-web-gateway -n rdpbroker

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Opera 76+

Security Considerations

• Use HTTPS/WSS in production
• Credentials are passed directly to RdpBroker (no storage in web-gateway)
• Implement rate limiting at ingress level
• Enable CORS restrictions
• Regular security audits
• All authentication handled by RdpBroker → Samba ADs
• Regular security audits

Performance Tuning

• Configure WebSocket buffer sizes
• Use CDN for static assets in production
• Enable HTTP compression (already included)
• Adjust resource limits in Kubernetes
• Use CDN for static assets in production

Troubleshooting

Can't connect to RdpBroker

Check environment variables:

echo $RDP_BROKER_HOST
echo $RDP_BROKER_PORT

Test connectivity:

nc -zv rdpbroker 3389

WebSocket connection fails

Ensure WebSocket upgrade is allowed through any proxies/load balancers.

For nginx:

location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

High memory usage

Adjust resource limits in Kubernetes values.yaml

Logging

All logs go to stdout/stderr for Kubernetes:

# View logs
kubectl logs -f deployment/rdp-web-gateway -n rdpbroker

# Follow logs for all pods
kubectl logs -f -l app=rdp-web-gateway -n rdpbroker

Reduce session timeout or implement session limits per user.

Development

Running Tests

npm test

Code Style

npm run lint

License

MIT License - see LICENSE file

Support

For issues and questions, check the logs:

# View logs
kubectl logs -f deployment/rdp-web-gateway -n rdpbroker

# Check health
curl http://localhost:8080/health