Maison/samba-api/HTTPS-README.md

Samba API - HTTPS Configuration

This guide explains how to use the Samba API with HTTPS support.

🔒 HTTPS Setup

The Samba API now supports HTTPS with SSL/TLS encryption for secure communication.

Components

1. Self-signed SSL certificates (generated automatically)
2. Direct HTTPS support via Uvicorn
3. Optional Nginx reverse proxy for production use

🚀 Quick Start

1. Standard HTTPS (Direct)

# Start with HTTPS enabled
docker-compose up -d

# The API will be available at:
# - HTTPS: https://localhost:8443
# - HTTP: http://localhost:8000 (fallback)

2. Production with Nginx (Optional)

# Start with Nginx reverse proxy
docker-compose --profile production up -d

# The API will be available at:
# - HTTPS: https://localhost:443 (via Nginx)
# - HTTP: http://localhost:80 (redirects to HTTPS)

📋 Configuration

Environment Variables

Variable	Default	Description
USE_HTTPS	true	Enable HTTPS support
PORT	8000	HTTP port
HTTPS_PORT	8443	HTTPS port
HOST	0.0.0.0	Bind address
DEBUG	true	Enable debug mode

SSL Certificates

The API uses self-signed certificates located in /app/ssl/:

• server.crt - SSL certificate
• server.key - Private key

For production, replace these with certificates from a trusted CA.

🔧 API Endpoints

Base URLs

• HTTPS: https://localhost:8443
• HTTP: http://localhost:8000

Key Endpoints

Endpoint	Method	Description
/	GET	API status
/health	GET	Health check
/docs	GET	Interactive API documentation
/api/v1/auth/login	POST	User authentication
/api/v1/users	GET	List users
/api/v1/groups	GET	List groups

🔑 Authentication

Login Request

curl -k -X POST "https://localhost:8443/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "Administrator@example.com",
    "password": "Admin123!@#"
  }'

Using Bearer Token

# Get token from login response
TOKEN="your-jwt-token"

# Use token in subsequent requests
curl -k -H "Authorization: Bearer $TOKEN" \
  "https://localhost:8443/api/v1/users"

🌐 API Documentation

Access the interactive API documentation:

• Swagger UI: https://localhost:8443/docs
• ReDoc: https://localhost:8443/redoc
• OpenAPI JSON: https://localhost:8443/openapi.json

🔒 Security Features

SSL/TLS Configuration

• Protocols: TLS 1.2, TLS 1.3
• Ciphers: Strong encryption only
• HSTS: Strict Transport Security enabled

Security Headers

• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• X-XSS-Protection: 1; mode=block
• Strict-Transport-Security: max-age=63072000

🔧 Development vs Production

Development (Current Setup)

environment:
  - USE_HTTPS=true
  - DEBUG=true
ports:
  - "8000:8000"   # HTTP
  - "8443:8443"   # HTTPS

Production with Nginx

# Use docker-compose-https.yml
services:
  nginx-ssl:
    ports:
      - "80:80"     # HTTP (redirects)
      - "443:443"   # HTTPS

📝 Testing

Health Check

# HTTPS
curl -k https://localhost:8443/health

# HTTP
curl http://localhost:8000/health

API Status

curl -k https://localhost:8443/

Authentication Test

curl -k -X POST "https://localhost:8443/api/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"username": "Administrator@example.com", "password": "Admin123!@#"}'

🐛 Troubleshooting

Common Issues

1. Certificate Warnings

   • Use -k flag with curl for self-signed certificates
   • For browsers, accept the security warning

2. Connection Refused

   • Check if the container is running: docker-compose ps
   • Verify logs: docker-compose logs samba-api

3. Authentication Failures

   • Verify Samba DC is running: docker-compose logs samba-dc
   • Check LDAP connectivity from API container

Logs

# View API logs
docker-compose logs -f samba-api

# View Samba DC logs
docker-compose logs -f samba-dc

# View all logs
docker-compose logs -f

🔄 Certificate Renewal

For production use, set up automatic certificate renewal:

# Example with Let's Encrypt (certbot)
certbot certonly --webroot -w /data/apps/samba-api/ssl \
  -d your-domain.com

# Copy certificates
cp /etc/letsencrypt/live/your-domain.com/fullchain.pem ./ssl/server.crt
cp /etc/letsencrypt/live/your-domain.com/privkey.pem ./ssl/server.key

# Restart services
docker-compose restart

📚 Additional Resources

• FastAPI HTTPS Documentation
• Uvicorn SSL Configuration
• Docker Compose Profiles

---

Note: The current setup uses self-signed certificates for development. For production environments, use certificates from a trusted Certificate Authority (CA) or Let's Encrypt.