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:

   git clone <repository-url>
   cd authelia
   

2. Start development environment:

   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:

   ./tests/precommit.sh
   

🔑 Secrets Management

Initial Setup

Generate production secrets (⚠️ Use with extreme caution):

./generate-secrets.sh

CRITICAL: This script will:

• Invalidate all existing sessions and tokens
• Require updating all 12 secrets in Woodpecker CI vault
• Potentially require recreating database volumes
• Cause service downtime until deployment completes

CI/CD Vault Management

For comprehensive CI/CD vault setup and secret management:

📖 CI/CD Vault Setup Guide

Required Secrets (12 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 (4)

• CLIENT_SECRET_HEADSCALE - Headscale VPN OIDC client secret
• CLIENT_SECRET_HEADADMIN - Headscale admin panel OIDC client secret
• CLIENT_SECRET_PORTAINER - Portainer OAuth client secret
• CLIENT_SECRET_GITEA - Gitea OAuth 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

# 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

🔗 OAuth/OIDC Integration

For advanced OAuth/OIDC setup with services like Portainer and Gitea, see the comprehensive guide:

📖 OAuth Setup Guide

This includes:

• OAuth client configuration for Portainer and Gitea
• Client secret generation and management
• CI/CD vault setup instructions
• Step-by-step authentication flow setup

Quick OAuth Setup

# Generate OAuth client secrets
./scripts/generate-oauth-secrets.sh

# Follow the instructions to update your CI/CD vault
# Then configure OAuth in your services

📱 Client Integration Examples

OAuth Integration (Recommended)

Use OAuth for better user experience and native service integration:

# Portainer with OAuth - no Traefik middleware needed
labels:
  traefik.enable: "true"
  traefik.http.routers.portainer.rule: "Host(`portainer.nixc.us`)"
  # OAuth configured in Portainer admin panel

Traefik Middleware Protection

Use Authelia middleware for services without OAuth support:

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"

Headscale VPN Integration

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"

🔍 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

📖 Documentation

For comprehensive guides and setup instructions:

📁 Documentation Directory

Available guides:

• OAuth/OIDC Setup: Complete OAuth integration guide
• CI/CD Vault Setup: Secret management and vault configuration
• Troubleshooting: Common issues and solutions

📞 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 - Authentication and authorization server
• Traefik - Cloud-native reverse proxy
• LLDAP - Lightweight LDAP implementation
• Woodpecker CI - Continuous integration platform

---

⚠️ Important: Always keep secrets.md secure and never commit it to version control!