218 lines
7.0 KiB
Markdown
218 lines
7.0 KiB
Markdown
<!-- build 5 -->
|
|
# Authelia with Traefik (ATLAS)
|
|
## Authentication Traffic LDAP Application Security
|
|
|
|
A comprehensive, production-ready authentication solution using Authelia with Traefik reverse proxy, featuring automated CI/CD, comprehensive testing, and robust secrets management.
|
|
|
|
## 🌟 Features
|
|
|
|
- **🔐 Complete Authentication Stack**: Authelia + LLDAP + MariaDB + Redis
|
|
- **🚀 Production-Ready Deployment**: Docker Swarm with Traefik integration
|
|
- **🧪 Comprehensive Testing**: Automated pre-commit tests and CI/CD validation
|
|
- **🔑 Robust Secrets Management**: Automated generation and rotation capabilities
|
|
- **⚡ Development Environment**: Isolated dev setup with hot-reload capabilities
|
|
- **🔄 OIDC Integration**: Full OpenID Connect support for client applications
|
|
- **📊 Health Monitoring**: Built-in health checks and monitoring endpoints
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### Prerequisites
|
|
- Docker and Docker Compose
|
|
- OpenSSL (for secrets generation)
|
|
- Git with pre-commit hooks support
|
|
|
|
### Development Setup
|
|
|
|
1. **Clone the repository**:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd authelia
|
|
```
|
|
|
|
2. **Start development environment**:
|
|
```bash
|
|
docker compose -f docker-compose.dev.yml up -d
|
|
```
|
|
|
|
3. **Access services**:
|
|
- **Authelia**: http://localhost:9091
|
|
- **LLDAP Admin**: http://localhost:17170
|
|
- Username: `admin`
|
|
- Password: `/ETAToLiZPWo6QK171abAUqsa3WDpd9IgneZnTA4zU0=`
|
|
|
|
4. **Run tests**:
|
|
```bash
|
|
./tests/precommit.sh
|
|
```
|
|
|
|
## 🔑 Secrets Management
|
|
|
|
### Initial Setup
|
|
Generate production secrets (⚠️ **Use with extreme caution**):
|
|
```bash
|
|
./generate-secrets.sh
|
|
```
|
|
|
|
**CRITICAL**: This script will:
|
|
- Invalidate all existing sessions and tokens
|
|
- Require updating all 10 secrets in Woodpecker CI vault
|
|
- Potentially require recreating database volumes
|
|
- Cause service downtime until deployment completes
|
|
|
|
### Required Secrets (10 total)
|
|
|
|
#### Core Secrets (5)
|
|
- `AUTHENTICATION_BACKEND_LDAP_PASSWORD` - LDAP authentication backend password
|
|
- `IDENTITY_VALIDATION_RESET_PASSWORD_JWT_SECRET` - JWT secret for password reset tokens
|
|
- `STORAGE_ENCRYPTION_KEY` - Database encryption key
|
|
- `SESSION_SECRET` - Session encryption secret
|
|
- `NOTIFIER_SMTP_PASSWORD` - SMTP email notifications password
|
|
|
|
#### OIDC Secrets (3)
|
|
- `IDENTITY_PROVIDERS_OIDC_HMAC_SECRET` - OIDC HMAC signing secret
|
|
- `IDENTITY_PROVIDERS_OIDC_ISSUER_PRIVATE_KEY` - OIDC token signing private key (RSA)
|
|
- `IDENTITY_PROVIDERS_OIDC_JWKS_KEY` - OIDC JWKS validation key (RSA)
|
|
|
|
#### Client Secrets (2)
|
|
- `CLIENT_SECRET_HEADSCALE` - Headscale VPN OIDC client secret
|
|
- `CLIENT_SECRET_HEADADMIN` - Headscale admin panel OIDC client secret
|
|
|
|
## 🧪 Testing
|
|
|
|
### Automated Testing
|
|
The project includes comprehensive testing:
|
|
|
|
- **Pre-commit hooks**: `./tests/precommit.sh`
|
|
- **Authentication tests**: `./tests/precommit-auth.sh`
|
|
- **CI/CD pipeline**: Automated testing on every push
|
|
|
|
### Test Coverage
|
|
- ✅ Authelia health endpoints
|
|
- ✅ Web interface accessibility
|
|
- ✅ API endpoint validation
|
|
- ✅ Container health status
|
|
- ✅ LLDAP integration
|
|
- ✅ Service interconnectivity
|
|
|
|
## 🚀 Deployment
|
|
|
|
### CI/CD Pipeline
|
|
Automated deployment through Woodpecker CI:
|
|
|
|
1. **Build & Test**: Comprehensive testing on every commit
|
|
2. **Build Images**: Multi-stage Docker builds for production
|
|
3. **Secret Management**: Automatic Docker secrets recreation
|
|
4. **Deploy**: Zero-downtime deployment to Docker Swarm
|
|
5. **Verification**: Post-deployment health checks
|
|
|
|
### Manual Deployment
|
|
```bash
|
|
# Push changes to trigger CI/CD
|
|
git add .
|
|
git commit -m "your changes"
|
|
git push
|
|
|
|
# Monitor deployment
|
|
ssh macmini7 'docker service logs authelia_authelia --follow'
|
|
```
|
|
|
|
## 🔧 Configuration
|
|
|
|
### Development vs Production
|
|
- **Development**: Uses local secrets in `docker-compose.dev.yml`
|
|
- **Production**: Uses Docker Swarm secrets from CI/CD vault
|
|
|
|
### Environment Variables
|
|
Key environment variables for customization:
|
|
- `X_AUTHELIA_SITE_NAME` - Site display name
|
|
- `X_AUTHELIA_EMAIL` - Notification email address
|
|
- `TRAEFIK_DOMAIN` - Base domain for services
|
|
|
|
## 📱 Client Integration Examples
|
|
|
|
### Headscale VPN Integration
|
|
```yaml
|
|
labels:
|
|
traefik.enable: "true"
|
|
traefik.http.routers.headscale.rule: "Host(`headscale.nixc.us`)"
|
|
traefik.http.routers.headscale.entrypoints: "websecure"
|
|
traefik.http.routers.headscale.tls.certresolver: "letsencryptresolver"
|
|
traefik.http.services.headscale.loadbalancer.server.port: "8080"
|
|
```
|
|
|
|
### Protected Web Service
|
|
```yaml
|
|
labels:
|
|
traefik.enable: "true"
|
|
traefik.http.routers.myapp.rule: "Host(`myapp.nixc.us`)"
|
|
traefik.http.routers.myapp.middlewares: "authelia_authelia@docker"
|
|
traefik.http.services.myapp.loadbalancer.server.port: "8080"
|
|
```
|
|
|
|
## 🔍 Monitoring & Troubleshooting
|
|
|
|
### Health Checks
|
|
- **Authelia**: `http://localhost:9091/api/health`
|
|
- **Service Status**: `docker service ls`
|
|
- **Logs**: `docker service logs authelia_authelia`
|
|
|
|
### Common Issues
|
|
1. **Service won't start**: Check secrets configuration
|
|
2. **Authentication fails**: Verify LLDAP connectivity
|
|
3. **OIDC issues**: Check RSA key format in JWKS configuration
|
|
|
|
## 🛠️ Development Workflow
|
|
|
|
1. **Make changes** to configuration or code
|
|
2. **Test locally**: `./tests/precommit.sh`
|
|
3. **Commit changes**: Git pre-commit hooks run automatically
|
|
4. **Push to repository**: Triggers CI/CD pipeline
|
|
5. **Monitor deployment**: Check service health in production
|
|
|
|
## 📋 Requirements
|
|
|
|
### Core Infrastructure
|
|
- **Docker & Docker Compose**: Container orchestration
|
|
- **Traefik**: Reverse proxy and load balancer
|
|
- **Authelia**: Authentication and authorization server
|
|
- **LLDAP**: Lightweight LDAP server for user management
|
|
- **MariaDB**: Database backend
|
|
- **Redis**: Session storage and caching
|
|
|
|
### Development Tools
|
|
- **Woodpecker CI**: Continuous integration and deployment
|
|
- **Git**: Version control with pre-commit hooks
|
|
- **OpenSSL**: Cryptographic operations and secrets generation
|
|
|
|
## 🔐 Security Considerations
|
|
|
|
- **Secrets Rotation**: Use `./generate-secrets.sh` for periodic rotation
|
|
- **Database Encryption**: All sensitive data encrypted at rest
|
|
- **TLS Everywhere**: HTTPS/TLS for all client communications
|
|
- **Session Security**: Secure session management with Redis
|
|
- **OIDC Standards**: Industry-standard OpenID Connect implementation
|
|
|
|
## 📞 Support & Contributing
|
|
|
|
### Reporting Issues
|
|
- Create detailed bug reports with logs and steps to reproduce
|
|
- Include environment details and configuration (without secrets!)
|
|
|
|
### Contributing
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Add tests for new functionality
|
|
4. Ensure all tests pass
|
|
5. Submit a pull request
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
This project leverages several excellent open-source projects:
|
|
- **[Authelia](https://www.authelia.com/)** - Authentication and authorization server
|
|
- **[Traefik](https://traefik.io/)** - Cloud-native reverse proxy
|
|
- **[LLDAP](https://github.com/nitnelave/lldap)** - Lightweight LDAP implementation
|
|
- **[Woodpecker CI](https://woodpecker-ci.org/)** - Continuous integration platform
|
|
|
|
---
|
|
|
|
**⚠️ Important**: Always keep `secrets.md` secure and never commit it to version control! |