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)

```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.