gunet/simple-forward-auth-server repository overview

A ForwardAuth endpoint for Traefik. Includes a Flask application to implement the endpoint and a helper script to create JWTs A ForwardAuth endpoint for Traefik. Includes a Flask application to implement the endpoint and a helper script to create JWTs.

⁠Basics

• Environment variables:
  • JWT_SECRET: Our JWT secret
  • JWT_ALGORITHM: Our JWT algorithm (defaults to HS256)
  • JWT_ISSUER: The JWT issuer (defaults to http://traefik-forwardauth/auth)
  • API_KEY_HEADER: The HTTP header containing the API JWT Key (defaults to Api-Key)
  • API_BEARER_FORMAT: If set to non-zero then we assume that the API JWT Key value will be Bearer <key> (defaults to 0)
  • JWT_GLOBAL_AUDIENCE: Set the audience that will be accepted even if we requested ForwardAuth to only accept a specific aud value. Defaults to none which disables the feature
• The aud (audience) for the JWT token will be traefik-forward-auth unless specified in the command-line
• Build: docker build -t gunet/simple-forward-auth-server .
• Create JWT:
  • Global: docker run --rm --entrypoint python gunet/simple-forward-auth-server jwt_generate.py
    • If no expiration argument given, the token will have a lifetime of 1 hour
  • For specific IP: docker run --rm --entrypoint python gunet/simple-forward-auth-server jwt_generate.py --permitted-ip 1.2.3.4 (a comma-separated list of multiple IPs is also acceptable)
  • Additional arguments:
    • --no-expiration: No expiration for the JWT token
    • --expiration N<size>: Set the expiration as an integer of size s, m, h, M, y for seconds, months, hours, Months, years
    • --subject <subject>: Set the subject for the JWT token (defaults to forwardauth-subject)
    • --audience <audience>: Set the audience for the JWT token (defaults to traefik-forward-auth)
• Run server: docker run --rm -p 8080:8080 gunet/simple-forward-auth-server
  • Expects requests on /auth with the API HTTP header and returns 200 if all is ok, 401 if API key is missing or invalid, 403 if IP is not permitted
  • Can accept a audience parameter which will only authenticate sucessfully requests with that specific aud (so /auth?audience=<value>). If the env var JWT_GLOBAL_AUDIENCE is set to something other than none then that will also be an acceptable aud value. If an audience parameter is not available, the default accepted audience is traefik-forward-auth (which is also the default value used by jwt_generate.py)

⁠Traefik

Example Docker Compose configuration with service labels and middlewares:

services:
  whoami:
    image: traefik/whoami
    labels:
      # Explicitly instruct Traefik to expose this service
      - traefik.enable=true
      # Router configuration
      ## One should replace the `whoami` name with the name of their service
      ## Listen to the `web` entrypoint
      - traefik.http.routers.whoami.entrypoints=web
      ## Rule based on the Host of the request and PathPrefixes
      - traefik.http.routers.whoami.rule=Host(`www.gunet.gr`) && (PathPrefix(`/gunet/health`) || PathPrefix(`/test/health`))
      ## Configuration for middlewares
      ## * Add ipallowlist middleware to restrict access based on source IP
      ## * Add forwardauth middleware to validate requests
      ## * Add limit middleware to limit request body size
      ## * Add inflightreq middleware to limit inflight requests
      ## * Add ratelimit middleware to limit request rate
      ## * Add stripprefix middleware to remove the /gunet/ prefix before forwarding to the service
      - traefik.http.routers.whoami.middlewares=ipallowlist,forwardauth,limit,inflightreq,ratelimit
      - "traefik.http.middlewares.ipallowlist.ipallowlist.sourcerange=127.0.0.1/32, 172.0.0.0/8, 123.123.10.0/24"
      - traefik.http.middlewares.forwardauth.forwardauth.address=http://forwardauth:8080/auth
      - traefik.http.middlewares.limit.buffering.maxRequestBodyBytes=200000
      - traefik.http.middlewares.inflightreq.inflightreq.amount=10
      - traefik.http.middlewares.ratelimit.ratelimit.average=100
      - traefik.http.middlewares.ratelimit.ratelimit.period=5s
      - traefik.http.middlewares.ratelimit.ratelimit.burst=200
      - traefik.http.middlewares.stripprefix.stripprefix.prefixes=/gunet,/test
      # Service configuration
      ## 80 is the port that the whoami container is listening to
      - traefik.http.services.whoami_service.loadbalancer.server.port=80
  forwardauth:
    image: gunet/simple-forward-auth-server
    environment:
      - JWT_SECRET=your_secret
      - API_KEY_HEADER=Api-Key