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

# 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

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