# Authelia Setup Guide

This guide walks you through setting up Authelia authentication for your Launchpad Gateway.

## Overview

Authelia provides:
- 🔐 **Single Sign-On (SSO)** for all your services
- 🛡️ **Two-Factor Authentication (2FA)** with TOTP/WebAuthn
- 🌐 **Forward Authentication** integration with Traefik
- 👥 **User Management** with file-based or LDAP backends
- 📧 **Email Notifications** for password resets and 2FA setup

## Quick Start

### 1. Run the Setup Script

**Windows (PowerShell):**
```powershell
.\setup-authelia.ps1
```

**Linux/macOS (Bash):**
```bash
chmod +x setup-authelia.sh
./setup-authelia.sh
```

### 2. Configure Your Environment

Edit `.env` file with your actual values:
```env
DOMAIN=your-domain.com
TZ=America/New_York
ACME_EMAIL=admin@your-domain.com
AUTHELIA_JWT_SECRET=your_generated_jwt_secret
AUTHELIA_SESSION_SECRET=your_generated_session_secret
```

### 3. Update Authelia Configuration

Edit `authelia/configuration.yml`:
- Replace all instances of `example.com` with your actual domain
- Update SMTP settings if you want email notifications
- Adjust access control rules as needed

### 4. Set Up Users

Edit `authelia/users_database.yml`:
- Change the default password for `admin` user
- Add your own users
- Generate password hashes using:
  ```bash
  docker run --rm authelia/authelia:latest authelia crypto hash generate argon2 --password 'your-password'
  ```

### 5. Start Services

```bash
docker-compose up -d
```

## Access URLs

After setup, your services will be available at:
- **Authelia Portal**: `https://auth.gate.YOUR_DOMAIN`
- **Traefik Dashboard**: `https://traefik.gate.YOUR_DOMAIN` (requires authentication)
- **Portainer**: `https://portainer.gate.YOUR_DOMAIN` (requires authentication)
- **Uptime Kuma**: `https://uptime.gate.YOUR_DOMAIN` (requires authentication)

## Default Credentials

**⚠️ CHANGE THESE IMMEDIATELY!**
- **Username**: `admin`
- **Password**: `authelia`

## Configuration Files

### `authelia/configuration.yml`
Main Authelia configuration with:
- Server settings
- Authentication backend (file-based by default)
- Access control rules
- Session configuration
- TOTP/WebAuthn settings

### `authelia/users_database.yml`
User database when using file-based authentication:
- User credentials (hashed passwords)
- User groups
- Email addresses
- Display names

## Access Control Rules

The default configuration includes:
- **Bypass**: Authelia portal itself
- **Two-Factor**: Admin services (Traefik, Portainer) for `admins` group
- **One-Factor**: Other services for any authenticated user

### Example Rules

```yaml
access_control:
  rules:
    # Public access
    - domain: 'public.gate.example.com'
      policy: 'bypass'
    
    # Admin-only with 2FA
    - domain: 
        - 'traefik.gate.example.com'
        - 'portainer.gate.example.com'
      policy: 'two_factor'
      subject:
        - 'group:admins'
    
    # Authenticated users
    - domain: '*.gate.example.com'
      policy: 'one_factor'
```

## Adding New Protected Services

To protect a new service with Authelia:

1. Add the service to your `docker-compose.yml`
2. Add the Authelia middleware to the service labels:
   ```yaml
   labels:
     - traefik.http.routers.myservice.middlewares=authelia,security-headers
   ```

## SMTP Configuration

For email notifications (password reset, 2FA setup), configure SMTP in `configuration.yml`:

```yaml
notifier:
  smtp:
    address: 'smtp://smtp.gmail.com:587'
    username: 'your-email@gmail.com'
    password: 'your-app-password'
    sender: 'Authelia <noreply@your-domain.com>'
```

## Troubleshooting

### Common Issues

1. **"middleware authelia@docker not found"**
   - Ensure Authelia container is running
   - Check that middleware is defined in Authelia labels

2. **Login page not loading**
   - Verify DNS resolves to your server
   - Check SSL certificate is valid
   - Ensure Authelia container is healthy

3. **Authentication fails**
   - Check user exists in `users_database.yml`
   - Verify password hash is correct
   - Check Authelia logs: `docker-compose logs authelia`

### Logs

Check Authelia logs:
```bash
docker-compose logs -f authelia
```

Check Traefik logs:
```bash
docker-compose logs -f traefik
```

## Security Considerations

1. **Change Default Passwords**: Update all default credentials immediately
2. **Use Strong Secrets**: Generate cryptographically secure JWT and session secrets
3. **Enable 2FA**: Configure TOTP or WebAuthn for sensitive services
4. **Regular Updates**: Keep Authelia and other containers updated
5. **Monitor Logs**: Regularly review authentication logs
6. **Backup Configuration**: Keep secure backups of your configuration files

## Advanced Configuration

### LDAP Integration

To use LDAP instead of file-based authentication, update `configuration.yml`:

```yaml
authentication_backend:
  ldap:
    implementation: 'custom'
    address: 'ldap://your-ldap-server:389'
    base_dn: 'dc=example,dc=com'
    # ... additional LDAP settings
```

### External Database

To use PostgreSQL or MySQL instead of SQLite:

```yaml
storage:
  postgres:
    address: 'tcp://postgres:5432'
    database: 'authelia'
    username: 'authelia'
    password: 'your-password'
```

### OIDC Provider

To use Authelia as an OIDC provider for other applications:

```yaml
identity_providers:
  oidc:
    hmac_secret: 'your-hmac-secret'
    issuer_private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      ...
      -----END RSA PRIVATE KEY-----
    clients:
      - id: 'myapp'
        secret: 'hashed-client-secret'
        redirect_uris:
          - 'https://myapp.example.com/callback'
```

## Support

- [Authelia Documentation](https://www.authelia.com/)
- [Traefik Integration Guide](https://www.authelia.com/integration/proxies/traefik/)
- [Community Discord](https://discord.gg/authelia)