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

Clone the repository:

git clone <repository-url>
cd samba-api

Copy environment file:

cp .env.example .env

Update the configuration in .env file with your domain settings.
Start the services:

docker-compose up -d

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

Using Kubernetes

Build and push the Docker image:

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

Update the image in k8s/deployment.yaml
Update secrets and configuration in k8s/configmap.yaml
Deploy to Kubernetes:

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

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

Install dependencies:

pip install -r requirements.txt

Set up environment variables:

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

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

LDAP Connection Failed
- Check LDAP server URL and credentials
- Verify network connectivity to domain controller
- Check if LDAP service is running
Authentication Errors
- Verify JWT secret key configuration
- Check user credentials and permissions
- Ensure domain controller is accessible
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

Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Submit a pull request

License

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

Support

For issues and questions:

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