Maison/samba-api/README.md

Samba API

A REST API for managing Samba Active Directory users, groups, organizational units, and computers. Built with FastAPI and designed to run in Kubernetes.

Features

• User Management: Create, read, update, delete users with full LDAP integration
• Group Management: Manage security and distribution groups with membership control
• Organizational Units: Create and manage OU hierarchies
• Computer Management: Handle computer accounts and domain joins
• JWT Authentication: Secure API with token-based authentication
• LDAP Integration: Direct integration with Samba/Active Directory via LDAP
• Kubernetes Ready: Full Kubernetes deployment manifests included
• Docker Support: Containerized application with Samba tools

Architecture

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   Frontend/     │    │  Samba API   │    │  Samba DC /     │
│   Client App    │◄──►│  (FastAPI)   │◄──►│  Active         │
│                 │    │              │    │  Directory      │
└─────────────────┘    └──────────────┘    └─────────────────┘
                              │
                              ▼
                      ┌──────────────┐
                      │ samba-tool / │
                      │ LDAP Queries │
                      └──────────────┘

Quick Start

Using Docker Compose

1. Clone the repository:

git clone <repository-url>
cd samba-api

2. Copy environment file:

cp .env.example .env

3. Update the configuration in .env file with your domain settings.

4. Start the services:

docker-compose up -d

5. Access the API documentation at: http://localhost:8000/docs

Using Kubernetes

1. Build and push the Docker image:

docker build -t your-registry/samba-api:latest .
docker push your-registry/samba-api:latest

2. Update the image in k8s/deployment.yaml

3. Update secrets and configuration in k8s/configmap.yaml

4. Deploy to Kubernetes:

chmod +x k8s/deploy.sh
./k8s/deploy.sh

5. Access the API:

kubectl port-forward svc/samba-api-service 8000:80 -n samba-api

API Endpoints

Authentication

• POST /api/v1/auth/login - Login and get JWT token
• GET /api/v1/auth/me - Get current user info
• POST /api/v1/auth/logout - Logout
• POST /api/v1/auth/refresh - Refresh JWT token

Users

• GET /api/v1/users - List users (with pagination and search)
• POST /api/v1/users - Create new user
• GET /api/v1/users/{username} - Get user details
• PUT /api/v1/users/{username} - Update user
• DELETE /api/v1/users/{username} - Delete user
• POST /api/v1/users/{username}/password - Change password
• POST /api/v1/users/{username}/enable - Enable user account
• POST /api/v1/users/{username}/disable - Disable user account

Groups

• GET /api/v1/groups - List groups
• POST /api/v1/groups - Create new group
• GET /api/v1/groups/{group_name} - Get group details
• PUT /api/v1/groups/{group_name} - Update group
• DELETE /api/v1/groups/{group_name} - Delete group
• POST /api/v1/groups/{group_name}/members - Add members to group
• DELETE /api/v1/groups/{group_name}/members - Remove members from group

Organizational Units

• GET /api/v1/ous - List OUs
• POST /api/v1/ous - Create new OU
• GET /api/v1/ous/tree - Get OU tree structure
• GET /api/v1/ous/{ou_dn} - Get OU details
• PUT /api/v1/ous/{ou_dn} - Update OU
• DELETE /api/v1/ous/{ou_dn} - Delete OU

Computers

• GET /api/v1/computers - List computers
• POST /api/v1/computers - Create computer account
• GET /api/v1/computers/{computer_name} - Get computer details
• PUT /api/v1/computers/{computer_name} - Update computer
• DELETE /api/v1/computers/{computer_name} - Delete computer
• POST /api/v1/computers/join - Join computer to domain
• POST /api/v1/computers/{computer_name}/reset-password - Reset computer password

Configuration

Environment Variables

Variable	Description	Default
HOST	API host	0.0.0.0
PORT	API port	8000
DEBUG	Debug mode	false
SECRET_KEY	JWT secret key	Required
ACCESS_TOKEN_EXPIRE_MINUTES	Token expiration	30
SAMBA_DOMAIN	Samba domain	Required
SAMBA_DC	Domain controller hostname	Required
SAMBA_ADMIN_USER	Admin username	Administrator
SAMBA_ADMIN_PASSWORD	Admin password	Required
SAMBA_BASE_DN	Base DN	Required
LDAP_SERVER	LDAP server URL	Required
LDAP_USE_SSL	Use SSL for LDAP	false
LDAP_BIND_DN	LDAP bind DN	Required
LDAP_BIND_PASSWORD	LDAP bind password	Required

Kubernetes Configuration

The application is configured for Kubernetes deployment with:

• High Availability: 3 replicas with pod disruption budget
• Auto Scaling: HPA based on CPU and memory usage
• Security: Non-root containers, read-only filesystem, RBAC
• Monitoring: Health checks and readiness probes
• Storage: Persistent volumes for Samba DC data

Development

Local Development Setup

1. Install dependencies:

pip install -r requirements.txt

2. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Run the application:

python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

Running Tests

pytest tests/ -v

Code Structure

src/
├── core/           # Core configuration and exceptions
├── models/         # Pydantic models for API
├── routers/        # API route handlers
├── services/       # Business logic and Samba integration
└── main.py         # FastAPI application setup

Security Considerations

• Change default passwords in production
• Use strong JWT secret keys (minimum 32 characters)
• Enable SSL/TLS for LDAP connections in production
• Implement proper network segmentation
• Use Kubernetes secrets for sensitive configuration
• Regularly update base images and dependencies

Troubleshooting

Common Issues

1. LDAP Connection Failed

   • Check LDAP server URL and credentials
   • Verify network connectivity to domain controller
   • Check if LDAP service is running

2. Authentication Errors

   • Verify JWT secret key configuration
   • Check user credentials and permissions
   • Ensure domain controller is accessible

3. Samba Tool Errors

   • Verify samba-tool is installed in container
   • Check domain configuration
   • Ensure proper DNS resolution

Logs and Monitoring

• Application logs are available in container stdout
• Configure log level with LOG_LEVEL environment variable
• Use Kubernetes logging and monitoring solutions for production

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section
2. Search existing issues in the repository
3. Create a new issue with detailed information