# 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 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!