Initialisation depot

samba-api/HTTPS-README.md

@@ -0,0 +1,219 @@
+# 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)
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+# 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)
+```yaml
+environment:
+  - USE_HTTPS=true
+  - DEBUG=true
+ports:
+  - "8000:8000"   # HTTP
+  - "8443:8443"   # HTTPS
+```
+
+### Production with Nginx
+```yaml
+# Use docker-compose-https.yml
+services:
+  nginx-ssl:
+    ports:
+      - "80:80"     # HTTP (redirects)
+      - "443:443"   # HTTPS
+```
+
+## 📝 Testing
+
+### Health Check
+```bash
+# HTTPS
+curl -k https://localhost:8443/health
+
+# HTTP
+curl http://localhost:8000/health
+```
+
+### API Status
+```bash
+curl -k https://localhost:8443/
+```
+
+### Authentication Test
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+# 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](https://fastapi.tiangolo.com/deployment/https/)
+- [Uvicorn SSL Configuration](https://www.uvicorn.org/settings/#https)
+- [Docker Compose Profiles](https://docs.docker.com/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.