Initialisation depot
This commit is contained in:
Serge NOEL
292
samba-api/Architecture.md
Normal file
292
samba-api/Architecture.md
Normal file
@@ -0,0 +1,292 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user