242 lines
7.4 KiB
Markdown
242 lines
7.4 KiB
Markdown
# 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:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd samba-api
|
|
```
|
|
|
|
2. Copy environment file:
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
3. Update the configuration in `.env` file with your domain settings.
|
|
|
|
4. Start the services:
|
|
```bash
|
|
docker-compose up -d
|
|
```
|
|
|
|
5. Access the API documentation at: http://localhost:8000/docs
|
|
|
|
### Using Kubernetes
|
|
|
|
1. Build and push the Docker image:
|
|
```bash
|
|
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:
|
|
```bash
|
|
chmod +x k8s/deploy.sh
|
|
./k8s/deploy.sh
|
|
```
|
|
|
|
5. Access the API:
|
|
```bash
|
|
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:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
2. Set up environment variables:
|
|
```bash
|
|
cp .env.example .env
|
|
# Edit .env with your configuration
|
|
```
|
|
|
|
3. Run the application:
|
|
```bash
|
|
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
|
|
```
|
|
|
|
### Running Tests
|
|
|
|
```bash
|
|
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 |