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