elliotechnology/ellio_traefik_forward_auth repository overview

⁠ELLIO ForwardAuth for Traefik

Secure forward authentication middleware for Traefik that integrates with ELLIO EDL Management Platform⁠.

Docker Hub: elliotechnology/ellio_traefik_forward_auth⁠

⁠Quick Start

⁠1. Get Your Bootstrap Token

Log in to platform.ellio.tech⁠ and generate a bootstrap token for your deployment.

⁠2. Add to Your Docker Compose

Add the ForwardAuth service to your existing docker-compose.yml:

version: '3.8'

services:
  traefik:
    image: traefik:v3.0
    command:
      - "--providers.docker=true"
      - "--entrypoints.web.address=:80"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    networks:
      - web

  forwardauth:
    image: elliotechnology/ellio_traefik_forward_auth:latest
    environment:
      - ELLIO_BOOTSTRAP=your_bootstrap_token_here  # Replace with your token
      # Optional: Override IP header (defaults to X-Forwarded-For)
      # - IP_HEADER_OVERRIDE=X-Real-IP
    labels:
      # Define the middleware
      - "traefik.http.middlewares.ellio-auth.forwardAuth.address=http://forwardauth:8080/auth"
    networks:
      - web

  # Your protected service
  your-app:
    image: your-app:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.your-app.rule=Host(`app.example.com`)"
      - "traefik.http.routers.your-app.middlewares=ellio-auth"  # Apply the middleware
    networks:
      - web

networks:
  web:
    driver: bridge

That's it! Your services are now protected by ELLIO EDL.

⁠Understanding the Labels

The ForwardAuth middleware is configured through Traefik labels:

⁠On the ForwardAuth service

• traefik.http.middlewares.ellio-auth.forwardAuth.address
  Tells Traefik where to send authentication requests. The middleware validates every request through this endpoint before allowing access to protected services.

⁠On your protected services

• traefik.http.routers.your-app.middlewares=ellio-auth
  Applies the authentication middleware to your service. Every incoming request will be validated against the EDL before reaching your application.

⁠How EDL Metadata Controls Access

The ForwardAuth middleware adapts its behavior based on your EDL deployment configuration in the ELLIO platform:

⁠EDL Purpose Types

• Allowlist: Only IP addresses in the EDL are granted access. All other IPs are blocked.
• Blocklist: IP addresses in the EDL are denied access. All other IPs are allowed.
• Other/Custom: Defaults to blocklist behavior for security.

⁠Supported IP Formats

The EDL supports multiple IP address formats:

• IPv4 addresses (e.g., 192.168.1.1)
• IPv6 addresses (e.g., 2001:db8::1)
• CIDR notation for both IPv4 and IPv6 (e.g., 10.0.0.0/8, 2001:db8::/32)

⁠Automatic Configuration

• Update Frequency: Automatically synchronized from your EDL metadata settings
• Dynamic Updates: The middleware fetches EDL updates at the configured interval without service interruption
• Zero-downtime: Updates are applied atomically with no impact on active connections

⁠Failsafe Behavior

In the event of deployment issues:

• Disabled Deployment: If the deployment is disabled in the ELLIO platform, the middleware falls back to allowing all traffic to prevent service disruption
• Deleted Deployment: Similar failsafe applies - all traffic is allowed to maintain availability
• Network Issues: The last successfully fetched EDL remains active until connectivity is restored

⁠How It Works

1. Request arrives at Traefik for your protected service
2. Traefik forwards the request to ForwardAuth middleware
3. ForwardAuth extracts the client IP from X-Forwarded-For header (or custom header if configured)
4. IP validation against the current EDL based on the configured purpose (allowlist/blocklist)
5. Access decision: Returns 200 (allowed) or 403 (denied) to Traefik
6. EDL synchronization occurs automatically based on metadata configuration

⁠Support

• Issues: GitHub Issues⁠
• Platform: platform.ellio.tech⁠

⁠License

Apache License 2.0 - see LICENSE⁠ file for details.

⁠Acknowledgments

⁠Trademarks and Copyrights

• ELLIO® is a registered trademark of ELLIO Technology s.r.o.
• Traefik® is a registered trademark of Traefik Labs.
• The Go gopher was designed by Renée French.
• All other trademarks, service marks, and trade names referenced herein are the property of their respective owners.

Copyright © ELLIO Technology s.r.o. | Part of the ELLIO EDL Management Platform⁠