Proxy Setup

Install and configure the Queen MQ proxy server.

Deployment Options

Option	Proxy Auth	Queen JWT	Use Case
Proxy Only	✅	❌	Simple setup, internal networks
Proxy + JWT	✅	✅	Defense in depth, zero-trust
Direct JWT	❌	✅	IoT devices, microservices (no proxy needed)

See Server Authentication for direct JWT without proxy.

Installation

cd proxy
npm install

Configuration

Create .env:

PORT=3000
QUEEN_URL=http://localhost:6632
PG_HOST=localhost
PG_PORT=5432
PG_USER=queen
PG_PASSWORD=password
PG_DB=queen
JWT_SECRET=your-secret-key
SESSION_SECRET=your-session-secret

Create Users

node src/create-user.js

Then follow the prompts to create users with different roles.

Create Microservice Tokens

For microservices that need to authenticate programmatically, you can generate long-lived or non-expiring tokens directly when creating a user:

node src/create-user.js

Follow the prompts:

=== Queen Proxy - Create User ===

Username: order-service
Password: ********

Roles:
  1) admin       - Full access
  2) read-write  - Read-write access
  3) read-only   - Read-only access

Select role (1-3): 2

Token expiration:
  1) 24h    - 24 hours (default)
  2) 7d     - 7 days
  3) 30d    - 30 days
  4) 1y     - 1 year
  5) never  - No expiration (for microservices)
  6) skip   - Do not generate token now

Select token expiration (1-6) [1]: 5

✓ User created successfully!
  Username: order-service
  Role: read-write
  ID: 42
  Token expiry: Never

  Bearer Token:
  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6NDIsInVzZXJuYW1lIjoib3JkZXItc2VydmljZSIsInJvbGUiOiJyZWFkLXdyaXRlIiwiaWF0IjoxNzM1MzA3MjAwfQ.xxxxx

  Use this token in the Authorization header:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token Expiration Options

• 24h/7d/30d - For temporary access or testing
• 1y - For long-running services with annual rotation
• never - For microservices that shouldn't expire (rotate manually if compromised)
• skip - Create user without generating a token (use login flow instead)

Security

Store tokens securely in environment variables or secrets management (e.g., Kubernetes Secrets, HashiCorp Vault). Never commit tokens to version control.

Run

npm start

Proxy available at http://localhost:3000.

Docker

docker build -t queen-proxy .
docker run -p 3000:3000 \
  -e QUEEN_URL=http://queen:6632 \
  -e PG_HOST=postgres \
  queen-proxy

nginx SSL

server {
    listen 443 ssl;
    server_name queen.example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
    }
}

Proxy + JWT (Combined Authentication)

For defense in depth, you can enable JWT authentication on both the proxy and Queen server. The proxy generates JWT tokens on login and forwards them to Queen, which validates them independently.

Configuration

Both proxy and Queen must use the same JWT_SECRET:

# Start Queen with JWT authentication
JWT_ENABLED=true \
JWT_ALGORITHM=HS256 \
JWT_SECRET=your-shared-secret-key \
./bin/queen-server

# Start Proxy with same secret
JWT_SECRET=your-shared-secret-key \
QUEEN_SERVER_URL=http://localhost:6632 \
node proxy/src/server.js

How It Works

┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  [User] ──login──> [Proxy] ──generates JWT──> [Cookie]      │
│                                                             │
│  [User] ──request with cookie──> [Proxy] ──validates JWT──> │
│                                      │                      │
│                                      │ forwards JWT         │
│                                      ▼                      │
│                               [Queen Server]                │
│                                      │                      │
│                                validates JWT                │
│                                      │                      │
│                               [Request processed]           │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Benefits

• Defense in depth - Two layers of authentication
• Zero-trust - Queen validates every request even from trusted proxy
• Audit trail - Both services can log authenticated user info
• Graceful migration - Can enable Queen JWT without breaking existing proxy setup

Docker Compose Example

version: '3.8'
services:
  queen:
    image: smartnessai/queen-mq:latest
    environment:
      - PG_HOST=postgres
      - JWT_ENABLED=true
      - JWT_ALGORITHM=HS256
      - JWT_SECRET=${JWT_SECRET}
    ports:
      - "6632:6632"
  
  proxy:
    build: ./proxy
    environment:
      - QUEEN_SERVER_URL=http://queen:6632
      - JWT_SECRET=${JWT_SECRET}
      - PG_HOST=postgres
    ports:
      - "3000:3000"
  
  postgres:
    image: postgres:15
    environment:
      - POSTGRES_PASSWORD=password

TIP

When using Proxy + JWT, users can still log in via the proxy's /login page with username/password. The proxy generates a JWT that works for both the proxy's session management and Queen's authentication.

Complete guide