685 improve passthrough (#687)

* Improve passthrough - bugfixes, security

Signed-off-by: Mihai Criveti <[email protected]>

* Improve passthrough - bugfixes, security

Signed-off-by: Mihai Criveti <[email protected]>

* Improve passthrough - bugfixes, security

Signed-off-by: Mihai Criveti <[email protected]>

---------

Signed-off-by: Mihai Criveti <[email protected]>

Author: crivetimihai

.env.example

@@ -119,10 +119,16 @@ MCPGATEWAY_ADMIN_API_ENABLED=true
 # Header Passthrough Configuration
 #####################################
 
-# Default headers to pass through from client requests to backing MCP servers
-# Comma-separated list or JSON array format
-# Example: ["Authorization", "X-Tenant-Id", "X-Trace-Id"]
-DEFAULT_PASSTHROUGH_HEADERS=["Authorization", "X-Tenant-Id", "X-Trace-Id"]
+# SECURITY WARNING: Header passthrough is disabled by default for security.
+# Only enable if you understand the security implications and have reviewed
+# which headers should be passed through to backing MCP servers.
+# ENABLE_HEADER_PASSTHROUGH=false
+
+# Default headers to pass through (when feature is enabled)
+# JSON array format recommended: ["X-Tenant-Id", "X-Trace-Id"]
+# Comma-separated also supported: X-Tenant-Id,X-Trace-Id
+# NOTE: Authorization header removed from defaults for security
+# DEFAULT_PASSTHROUGH_HEADERS=["X-Tenant-Id", "X-Trace-Id"]
 
 #####################################
 # Security and CORS

docs/docs/overview/passthrough.md

@@ -1,5 +1,7 @@
 # HTTP Header Passthrough
 
+⚠️ **Security Notice**: HTTP Header Passthrough is **disabled by default** for security reasons. Only enable this feature if you understand the security implications and have reviewed which headers should be passed through to backing MCP servers.
+
 The MCP Gateway supports **HTTP Header Passthrough**, allowing specific headers from incoming client requests to be forwarded to backing MCP servers. This feature is essential for maintaining authentication context and request tracing across the gateway infrastructure.
 
 ## Overview
@@ -8,66 +10,118 @@ When clients make requests through the MCP Gateway, certain headers (like authen
 
 ## Key Features
 
+- **🔒 Security by Default**: Feature disabled by default - must be explicitly enabled
+- **🛡️ Header Validation**: Server-side and client-side header name and value validation
+- **🧹 Sanitization**: Automatic removal of dangerous characters and length limits
 - **Global Configuration**: Set default passthrough headers for all gateways
 - **Per-Gateway Override**: Customize header passthrough on a per-gateway basis
 - **Conflict Prevention**: Automatically prevents overriding existing authentication headers
 - **Admin UI Integration**: Configure passthrough headers through the web interface
 - **API Management**: Programmatic control via REST endpoints
+- **Rate Limiting**: Built-in rate limiting for configuration endpoints
 
 ## Configuration
 
+### ⚠️ Enable the Feature (Required)
+
+**The header passthrough feature is disabled by default for security.** You must explicitly enable it:
+
+```bash
+# Enable the feature (disabled by default)
+ENABLE_HEADER_PASSTHROUGH=true
+
+# Or in .env file
+ENABLE_HEADER_PASSTHROUGH=true
+```
+
+**Warning**: Only enable this feature if you:
+- Understand the security implications
+- Have reviewed which headers should be passed through
+- Trust the backing MCP servers with the forwarded headers
+- Have implemented proper network security
+
 ### Environment Variables
 
 Set global default headers using the `DEFAULT_PASSTHROUGH_HEADERS` environment variable:
 
 ```bash
-# JSON array format
-DEFAULT_PASSTHROUGH_HEADERS=["Authorization", "X-Tenant-Id", "X-Trace-Id"]
+# JSON array format (recommended)
+DEFAULT_PASSTHROUGH_HEADERS=["X-Tenant-Id", "X-Trace-Id"]
+
+# Comma-separated format (also supported)
+DEFAULT_PASSTHROUGH_HEADERS=X-Tenant-Id,X-Trace-Id
 
 # Or in .env file
-DEFAULT_PASSTHROUGH_HEADERS=["Authorization", "X-Tenant-Id", "X-Trace-Id"]
+DEFAULT_PASSTHROUGH_HEADERS=["X-Tenant-Id", "X-Trace-Id"]
 ```
 
+**Security Notes**:
+- `Authorization` header is **not included in defaults** for security
+- Only add `Authorization` if you fully understand the token leakage risks
+- Header names are validated against pattern: `^[A-Za-z0-9-]+$`
+- Header values are sanitized (newlines removed, length limited to 4KB)
+
 ### Admin UI Configuration
 
+**Prerequisites**:
+1. Set `ENABLE_HEADER_PASSTHROUGH=true` in your environment
+2. Restart the MCP Gateway service
+
 #### Global Configuration
 Access the admin interface to set global passthrough headers that apply to all gateways by default.
 
+🛡️ **Client-side validation** automatically checks:
+- Header names match pattern `^[A-Za-z0-9-]+$`
+- Header values don't contain newlines or excessive length
+- Invalid headers are rejected with clear error messages
+
 #### Per-Gateway Configuration
 When creating or editing gateways:
 
 1. Navigate to the **Gateways** section in the admin UI
 2. Click **Add Gateway** or edit an existing gateway
 3. In the **Passthrough Headers** field, enter a comma-separated list:
    ```
-   Authorization, X-Tenant-Id, X-Trace-Id
+   X-Tenant-Id, X-Trace-Id, X-Request-Id
    ```
+   **⚠️ Avoid including `Authorization` unless absolutely necessary**
 4. Gateway-specific headers override global defaults
+5. The UI validates headers in real-time and shows security warnings
 
 ### API Configuration
 
+**Rate Limited**: Configuration endpoints are rate-limited (20-30 requests/minute) for security.
+
 #### Get Global Configuration
 ```bash
 GET /admin/config/passthrough-headers
+Authorization: Bearer <your-jwt-token>
 ```
 
 Response:
 ```json
 {
-  "passthrough_headers": ["Authorization", "X-Tenant-Id", "X-Trace-Id"]
+  "passthrough_headers": ["X-Tenant-Id", "X-Trace-Id"]
 }
 ```
 
 #### Update Global Configuration
 ```bash
 PUT /admin/config/passthrough-headers
 Content-Type: application/json
+Authorization: Bearer <your-jwt-token>
 
 {
-  "passthrough_headers": ["Authorization", "X-Custom-Header"]
+  "passthrough_headers": ["X-Tenant-Id", "X-Custom-Header"]
 }
 ```
 
+**Security Validation**: The API automatically:
+- Validates header names against `^[A-Za-z0-9-]+$` pattern
+- Rejects invalid characters and formats
+- Sanitizes header values when used
+- Logs all configuration changes for audit
+
 ## How It Works
 
 ### Header Processing Flow
@@ -101,23 +155,46 @@ graph LR
 
 ## Security Considerations
 
+### 🛡️ Security-by-Default Features
+
+**Feature Flag Protection**:
+- Header passthrough is **disabled by default** (`ENABLE_HEADER_PASSTHROUGH=false`)
+- Must be explicitly enabled with full awareness of security implications
+- Can be disabled instantly by setting the flag to `false`
+
+**Header Sanitization**:
+- **Injection Prevention**: Removes newlines (`\r\n`) that could enable header injection attacks
+- **Length Limiting**: Restricts header values to 4KB maximum to prevent DoS
+- **Control Character Filtering**: Removes dangerous control characters (except tab)
+- **Validation**: Header names must match `^[A-Za-z0-9-]+$` pattern
+
+**Rate Limiting**:
+- Configuration endpoints limited to 20-30 requests/minute
+- Prevents automated attacks on configuration
+- Configurable via existing rate limiting settings
+
 ### Conflict Prevention
 
 The system automatically prevents header conflicts:
 
 - **Basic Auth**: Skips `Authorization` header if gateway uses basic authentication
 - **Bearer Auth**: Skips `Authorization` header if gateway uses bearer token authentication
+- **Existing Headers**: Won't override pre-existing headers in base request
 - **Warnings**: Logs warnings when headers are skipped due to conflicts
 
 ### Header Validation
 
-- Headers are validated before forwarding
-- Empty or invalid headers are filtered out
-- Only explicitly configured headers are passed through
+- **Server-side validation**: Headers validated against security patterns
+- **Client-side validation**: Admin UI provides real-time validation feedback
+- **Case-insensitive matching**: Handles header case variations safely
+- **Empty filtering**: Empty or invalid headers are filtered out
+- **Explicit configuration**: Only explicitly configured headers are passed through
 
 ## Use Cases
 
 ### Authentication Context
+⚠️ **Security Warning**: Be extremely careful when forwarding authentication tokens.
+
 Forward authentication tokens to maintain user context:
 ```bash
 # Client request includes
@@ -150,14 +227,14 @@ X-Organization: acme_corp
 
 ### Basic Setup
 ```bash
-# .env file
-DEFAULT_PASSTHROUGH_HEADERS=["Authorization"]
+# .env file (Authorization not recommended in defaults)
+DEFAULT_PASSTHROUGH_HEADERS=["X-Tenant-Id"]
 ```
 
 ### Multi-Header Configuration
 ```bash
-# .env file with multiple headers
-DEFAULT_PASSTHROUGH_HEADERS=["Authorization", "X-Tenant-Id", "X-Trace-Id", "X-Request-Id"]
+# .env file with multiple headers (safer defaults)
+DEFAULT_PASSTHROUGH_HEADERS=["X-Tenant-Id", "X-Trace-Id", "X-Request-Id"]
 ```
 
 ### Gateway-Specific Override
@@ -175,9 +252,17 @@ DEFAULT_PASSTHROUGH_HEADERS=["Authorization", "X-Tenant-Id", "X-Trace-Id", "X-Re
 ### Common Issues
 
 #### Headers Not Being Forwarded
-- Verify header names in configuration match exactly (case-sensitive)
+
+**Most Common Cause - Feature Disabled**:
+- ✅ **Check**: Is `ENABLE_HEADER_PASSTHROUGH=true` set in your environment?
+- ✅ **Check**: Did you restart the gateway after setting the flag?
+- ✅ **Check**: Are you seeing "Header passthrough is disabled" in debug logs?
+
+**Other Causes**:
+- Verify header names in configuration match exactly (case-insensitive matching)
 - Check for authentication conflicts in logs
 - Ensure gateway configuration overrides aren't blocking headers
+- Verify header names pass validation (only letters, numbers, hyphens allowed)
 
 #### Authentication Conflicts
 If you see warnings like:
@@ -194,6 +279,19 @@ Skipping passthrough header 'Authorization' - conflicts with existing basic auth
 - Restart the gateway after environment variable changes
 - Verify database migration has been applied
 - Check admin API responses to confirm configuration is saved
+- Verify rate limiting isn't blocking your configuration requests (20-30/min limit)
+
+#### Header Validation Errors
+If you see validation errors in the Admin UI or API:
+
+**Header Name Validation**:
+- Only letters, numbers, and hyphens allowed: `A-Za-z0-9-`
+- Examples: ✅ `X-Tenant-Id`, `Authorization` ❌ `X_Tenant_ID`, `My Header`
+
+**Header Value Issues**:
+- No newlines (`\r` or `\n`) allowed in values
+- Maximum length: 4KB per header value
+- Control characters are automatically removed
 
 ### Debug Logging
 
@@ -203,9 +301,12 @@ LOG_LEVEL=DEBUG
 ```
 
 Look for log entries containing:
-- `Passthrough headers configured`
-- `Skipping passthrough header`
-- `Adding passthrough header`
+- `Header passthrough is disabled` - Feature flag is off
+- `Passthrough headers configured` - Headers are being processed
+- `Skipping passthrough header` - Header blocked due to conflict
+- `Adding passthrough header` - Header successfully forwarded
+- `Invalid header name` - Header name validation failed
+- `Header value became empty after sanitization` - Header value was sanitized away
 
 ## API Reference