authelia/README.md

<!-- 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 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](docs/CI_CD_VAULT_SETUP.md)**

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

## 🔗 OAuth/OIDC Integration

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

**📖 [OAuth Setup Guide](docs/OAUTH_SETUP.md)**

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
```bash
# 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:
```yaml
# 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:
```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"
```

### 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"
```

## 🔍 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](docs/README.md)**

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](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!