Skip to content

https-setup.md

Latest commit

 

History

History
144 lines (111 loc) · 3.8 KB

https-setup.md

File metadata and controls

144 lines (111 loc) · 3.8 KB
Raw

HTTPS Configuration

Overview

The server supports both HTTP and HTTPS modes with automatic TLS configuration, secure session management, and production-ready certificate handling.

Configuration

Environment Variables

The server uses environment variables for configuration (see .env file):

# Basic server settings
SERVER_HOST=127.0.0.1
SERVER_PORT=8080

# TLS Configuration
ENABLE_TLS=true
GENERATE_SELF_SIGNED_CERT=true  # Development mode
TLS_CERT_PATH=./certs/cert.pem  # Production mode
TLS_KEY_PATH=./certs/private.pem # Production mode
TLS_CERT_DIR=certs

# CORS settings for frontend integration
CORS_ENABLED=true
CORS_ORIGINS=https://localhost:4200,https://localhost:3000,http://localhost:4200,http://localhost:3000

Development Setup

Self-Signed Certificates

For development, the server automatically generates self-signed certificates:

# Certificates generated automatically on startup
# Location: ./certs/
# - cert.pem (certificate)
# - private.pem (private key)

Accessing Services

# HTTPS (when ENABLE_TLS=true)
https://localhost:8080/swagger-ui/
https://localhost:8080/health

# HTTP (when ENABLE_TLS=false)
http://localhost:8080/swagger-ui/
http://localhost:8080/health

Production Setup

Custom Certificates

For production, provide your own certificates via environment variables:

# Production environment
ENABLE_TLS=true
GENERATE_SELF_SIGNED_CERT=false
TLS_CERT_PATH=/etc/ssl/certs/your-domain.pem
TLS_KEY_PATH=/etc/ssl/private/your-domain.key
CORS_ORIGINS=https://your-frontend-domain.com

Certificate Requirements

  • Format: PEM-encoded certificates
  • Chain: Include intermediate certificates if required
  • Permissions: Ensure proper file permissions (600 for private key)

Security Features

Session Cookies

When HTTPS is enabled, session cookies are automatically configured with:

  • HttpOnly: Prevents XSS access to cookies
  • SameSite=Lax: CSRF protection while allowing cross-site navigation
  • Secure: Ensures cookies are only sent over HTTPS

CORS Configuration

For security with credentials enabled:

  • Specific Origins: No wildcard (*) allowed with credentials
  • Explicit Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS
  • Allowed Headers: Authorization, Content-Type, X-Requested-With, Accept, Origin, X-CSRF-Token

Testing HTTPS

Certificate Validation

# Check certificate details
openssl x509 -in ./certs/cert.pem -text -noout

# Test HTTPS connection
curl -I https://localhost:8080/health --insecure

Session Authentication

# Login and capture session cookie
curl -X POST https://localhost:8080/auth/api/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}' \
  -c cookies.txt --insecure

# Use session cookie for authenticated request
curl https://localhost:8080/auth/api/me \
  -b cookies.txt --insecure

Integration Testing

The server includes comprehensive HTTPS integration tests:

# Run HTTPS integration tests
cargo test --test https_integration_tests

# Test coverage includes:
# - Self-signed certificate generation
# - Custom certificate loading
# - TLS configuration validation
# - CORS security compliance
# - Session cookie security

Troubleshooting

Common Issues

Certificate Permission Errors

# Fix private key permissions
chmod 600 /path/to/private.key
chown server-user:server-group /path/to/private.key

CORS Preflight Failures

  • Ensure frontend origin is listed in cors_origins
  • Verify HTTPS/HTTP protocol match between frontend and backend
  • Check that credentials are enabled in frontend requests

Self-Signed Certificate Warnings

  • Expected behavior in development
  • Use --insecure flag with curl for testing
  • Import certificate to browser trust store for local development