Maison/samba-api/Architecture.md

# Samba API Architecture Analysis

## Overview

The Samba API serves as an interface between web applications and samba-tool functionalities for Active Directory management. This document analyzes different architectural approaches to handle the security and communication challenges between the API layer and the privileged Samba operations.

## Problem Statement

Samba operations require elevated privileges to manage Active Directory objects (users, groups, computers, OUs). The challenge is to provide a secure, scalable, and maintainable interface while minimizing security risks and maintaining proper separation of concerns.

## Architectural Solutions

### 1. Pass-Through System (Direct Execution)

#### Description
The Samba API container runs with elevated privileges and directly executes samba-tool commands and LDAP operations.

#### Implementation
```
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Web App       │◄──►│   Samba API      │◄──►│  Samba DC       │
│                 │    │  (Privileged)    │    │  (LDAP/Kerberos)│
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │   samba-tool     │
                       │   execution      │
                       └──────────────────┘
```

#### Advantages
- **Simplicity**: Direct implementation with minimal complexity
- **Performance**: No additional communication overhead
- **Real-time Operations**: Immediate execution and response
- **Complete Feature Set**: Access to all samba-tool capabilities
- **Atomic Operations**: Operations complete in single request cycle

#### Drawbacks
- **Security Risk**: API container requires root/domain admin privileges
- **Attack Surface**: Web-facing service with elevated privileges
- **Blast Radius**: Compromise of API means full domain compromise
- **Audit Complexity**: Difficult to track individual operations
- **Resource Intensive**: Each API instance needs full Samba stack
- **Scaling Issues**: Privileged containers are harder to scale securely

#### Security Considerations
- Container must run with `privileged: true` or specific capabilities
- Network access to domain controller required
- Domain admin credentials stored in container
- No privilege separation between web interface and domain operations

---

### 2. File-Based Communication with inotify

#### Description
Separation of concerns using file system communication. The API writes operation requests to files, and a privileged worker container monitors file changes using inotify to execute operations.

#### Implementation
```
┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   Web App       │◄──►│   Samba API      │    │  Samba Worker    │
│                 │    │  (Unprivileged)  │    │  (Privileged)    │
└─────────────────┘    └──────────────────┘    └──────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌─────────────────────────────────────┐
                       │        Shared Volume               │
                       │  /requests/  │  /responses/        │
                       │    *.json    │    *.json          │
                       └─────────────────────────────────────┘
                                                ▲
                                                │
                                         ┌─────────────┐
                                         │   inotify   │
                                         │   watcher   │
                                         └─────────────┘
```

#### Advantages
- **Security Isolation**: API container runs unprivileged
- **Clear Separation**: Web interface isolated from domain operations
- **Audit Trail**: All operations logged as files
- **Scalability**: Multiple API instances can share worker
- **Resilience**: Operations survive container restarts
- **Debugging**: Easy to inspect pending/completed operations

#### Drawbacks
- **Complexity**: Additional components and file management
- **Latency**: File I/O overhead and polling delays
- **Race Conditions**: File locking and concurrent access issues
- **Storage Requirements**: Persistent storage for operation queues
- **Error Handling**: Complex error propagation through files
- **Limited Real-time**: Delays in operation execution
- **File System Dependencies**: Shared volume requirements

#### Implementation Details
```python
# API writes request
request = {
    "id": "uuid-123",
    "operation": "user_create",
    "params": {"username": "john", "password": "***"},
    "timestamp": "2025-10-22T10:30:00Z"
}
# Write to /requests/uuid-123.json

# Worker processes with inotify
import inotify.adapters
i = inotify.adapters.Inotify()
i.add_watch('/requests')
for event in i.event_gen():
    if event and 'IN_CLOSE_WRITE' in event[1]:
        process_request(event[3])  # filename
```

---

### 3. MQTT-Based Communication

#### Description
Message queue architecture using MQTT broker for communication between API and privileged worker containers.

#### Implementation
```
┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   Web App       │◄──►│   Samba API      │    │  Samba Worker    │
│                 │    │  (Unprivileged)  │    │  (Privileged)    │
└─────────────────┘    └──────────┬───────┘    └─────────┬────────┘
                                  │                      │
                                  ▼                      ▼
                       ┌─────────────────────────────────────┐
                       │         MQTT Broker               │
                       │                                   │
                       │  Topics:                          │
                       │  • samba/requests                 │
                       │  • samba/responses                │
                       │  • samba/status                   │
                       └─────────────────────────────────────┘
```

#### Advantages
- **Security Isolation**: API container completely unprivileged
- **Scalability**: Multiple workers, load balancing
- **Reliability**: Message persistence and delivery guarantees
- **Real-time**: Near real-time operation execution
- **Monitoring**: Built-in message tracking and metrics
- **Flexibility**: Easy to add new operation types
- **Resilience**: Message queuing survives container failures
- **Load Distribution**: Work distributed across multiple workers

#### Drawbacks
- **Infrastructure Complexity**: Additional MQTT broker service
- **Network Dependencies**: Broker availability critical
- **Message Overhead**: JSON serialization/deserialization
- **Debugging Complexity**: Distributed system debugging
- **Additional Security**: MQTT broker security configuration
- **Resource Usage**: Additional memory and CPU for broker
- **Message Size Limits**: Large payloads may need special handling

#### Implementation Details
```python
# API publishes request
import paho.mqtt.client as mqtt

request = {
    "id": "uuid-123",
    "operation": "user_create",
    "params": {"username": "john", "password": "***"},
    "reply_to": "samba/responses/uuid-123"
}

client.publish("samba/requests", json.dumps(request))

# Worker subscribes and processes
def on_message(client, userdata, message):
    request = json.loads(message.payload)
    result = execute_samba_operation(request)
    client.publish(request["reply_to"], json.dumps(result))
```

---

### 4. gRPC-Based Microservice (Alternative Solution)

#### Description
Dedicated privileged microservice exposing gRPC interface for Samba operations.

#### Implementation
```
┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   Web App       │◄──►│   Samba API      │◄──►│  Samba Service   │
│                 │    │  (Unprivileged)  │    │  (Privileged)    │
└─────────────────┘    └──────────────────┘    └──────────────────┘
                                │                        │
                                │      gRPC/HTTP         │
                                └────────────────────────┘
```

#### Advantages
- **Type Safety**: Strongly typed interfaces with Protocol Buffers
- **Performance**: Binary protocol, efficient serialization
- **Security**: mTLS authentication and encryption
- **Standardized**: Well-established patterns and tooling
- **Streaming**: Support for real-time operation streams
- **Multi-language**: Easy client generation for different languages
- **Service Discovery**: Built-in load balancing and discovery

#### Drawbacks
- **Complexity**: gRPC setup and maintenance
- **Debugging**: Binary protocol harder to debug
- **Firewall Issues**: HTTP/2 may have network restrictions
- **Learning Curve**: Team familiarity with gRPC required

---

### 5. Unix Domain Sockets (Alternative Solution)

#### Description
Communication through Unix domain sockets with a privileged daemon.

#### Advantages
- **Performance**: Fastest IPC mechanism
- **Security**: File system permissions control access
- **Simplicity**: No network configuration required

#### Drawbacks
- **Single Host**: Cannot scale across multiple machines
- **Socket Management**: File cleanup and permissions complexity
- **Container Limitations**: Requires shared volume mounts

---

## Recommendation Matrix

| Criteria | Pass-Through | File-based | MQTT | gRPC | Unix Sockets |
|----------|--------------|------------|------|------|--------------|
| Security | ❌ Poor | ✅ Good | ✅ Good | ✅ Good | ⚠️ Medium |
| Performance | ✅ Excellent | ⚠️ Medium | ✅ Good | ✅ Excellent | ✅ Excellent |
| Scalability | ❌ Poor | ⚠️ Medium | ✅ Excellent | ✅ Good | ❌ Poor |
| Complexity | ✅ Simple | ⚠️ Medium | ❌ Complex | ❌ Complex | ✅ Simple |
| Reliability | ⚠️ Medium | ✅ Good | ✅ Excellent | ✅ Good | ⚠️ Medium |
| Audit Trail | ❌ Poor | ✅ Excellent | ✅ Good | ⚠️ Medium | ❌ Poor |
| Real-time | ✅ Excellent | ❌ Poor | ✅ Good | ✅ Excellent | ✅ Excellent |
| Maintenance | ✅ Simple | ⚠️ Medium | ❌ Complex | ❌ Complex | ✅ Simple |

## Final Recommendation

### **Recommended Solution: MQTT-Based Architecture**

For production environments, the **MQTT-based approach** is recommended because:

1. **Security First**: Complete isolation of privileged operations
2. **Enterprise Scale**: Supports multiple workers and high availability
3. **Operational Excellence**: Built-in monitoring, logging, and error handling
4. **Future-Proof**: Easy to extend with new features and integrations

### **Development/Testing Alternative: File-Based**

For development or smaller deployments, the **file-based approach** offers:
- Good security with simpler implementation
- Excellent debugging capabilities
- Lower resource requirements
- Easier troubleshooting

### **Implementation Phases**

1. **Phase 1**: Start with file-based for MVP and testing
2. **Phase 2**: Migrate to MQTT for production deployment
3. **Phase 3**: Add advanced features like operation batching and workflow management

## Security Best Practices

Regardless of chosen architecture:

1. **Principle of Least Privilege**: Minimize permissions at every level
2. **Input Validation**: Sanitize all inputs before processing
3. **Audit Logging**: Log all operations with user attribution
4. **Encryption**: Encrypt communication channels and stored credentials
5. **Network Segmentation**: Isolate Samba operations network
6. **Regular Updates**: Keep all components updated with security patches
7. **Monitoring**: Implement comprehensive monitoring and alerting

## Conclusion

The choice of architecture depends on specific requirements:
- **Security-critical environments**: MQTT or gRPC
- **Simple deployments**: File-based or Unix sockets
- **Performance-critical**: Pass-through (with additional security measures)

The recommended MQTT approach provides the best balance of security, scalability, and maintainability for enterprise deployments.