# 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