traefik-simple-auth

A simple, up-to-date, re-implementation of traefik-forward-auth.

⚠️ Breaking change in v0.11.0

v0.11.0 once supports one domain. The command line argument -domains is replaced by -domain. To support multiple domains, run one instance of traefik-simple-auth per domain.

Goals

traefik-simple-auth provides an implementation of Traefik's forwardAuth middleware. The most well-known implementation of that middleware is Thom Seddon'straefik-forward-auth, or one of its many forks. However, that implementation hasn't been updated in over 3 years.

I wrote traefik-simple-auth with the following goals:

to learn about Traefik's forwardAuth middleware and the oauth approach that traefik-forward-auth uses;
have an implementation that uses recent versions of Go and underlying modules (incorporating any security fixes since the last version of traefik-forward-auth was released);
provide more operational observability into how forwardAuth is used;
fun!

traefik-forward-auth offers many features that I wasn't necessarily interested in: overlay mode, rules, etc. Those are not implemented in the current version of traefik-simple-auth. That may change in the future.

Design

The forwardAuth middleware delegates authentication to an external service. If the service answers with a 2XX code, access is granted, and the original request is performed. Otherwise, the response from the authentication server is returned.

traefik-simple-auth (like traefik-forward-auth) implements this authentication as a session Cookie: if the browser passes a valid cookie, we consider the user as a valid user and can tell Traefik to perform the original request.

For traefik-simple-auth, a valid cookie:

has the name _traefik_simple_auth;
comes from an authenticated user (more below);
hasn't expired (as determined by the expiry parameter documented below);
is secure (by creating a SHA256 HMAC of the above two values, using the secret parameter to generate the HMAC, to ensure it was issued by us);
is sent to us by the browser, i.e. the final destination needs to be part of the domain configured for traefik-simple-auth.

If an incoming request does not contain a valid session cookie, the user needs to be authenticated:

We forward the user to the auth provider's login page, so the user can be authenticated;
When the user has logged in, the provider sends the request back to traefik-simple-auth, specifically to the address <auth-prefix>.<domain>/_oauth, which routes the request to traefik-simple-auth's authCallback handler;
The handler uses the request to retrieve the authenticated user's email address and see if it is part of the users whitelist;
If so, it creates a new session cookie, and redirects the user to the original destination, with the session cookie;
This results in the request being sent back to traefik-simple-auth, with the session cookie, so it passes and the request is sent to the final destination.

Given the asynchronous nature of the handshake during the authentication, traefik-simple-auth needs to validate the request received from the auth provider, to protect against cross-site request forgery (CSRF). The approach is as follows:

When the authCallback handler forwards the user to the auth provider, it passes a random 'state', that it associates with the original request (i.e. the final destination)
When the auth provider sends the request back to traefik-simple-auth, it passes the same 'state' with the request.
traefik-simple-auth only keeps the state (with the final destination) for 10 minutes, which should be ample time for the user to log in.

Installation

Container images are available on ghcr.io. Images are available for linux/amd64, linux/arm and linux/arm64.

Configuration

Using Google as auth provider

Head to https://console.developers.google.com and create a new project. Create new Credentials and select OAuth Client ID with "web application" as its application type.

Give the credentials a name and define the authorized redirect URIs. We currently supports one redirect URI, so all applications need to be grouped under the same domain. E.g. if you need to support the following application URLs:

* app1.example.com
* app2.example.com
* app3.example.com

then the redirectURL should use the domain example.com and the redirect URL should be auth.example.com/_oauth.

Note the Client ID and Client Secret as you will need to configure these for traefik-simple-auth.

Traefik

Middleware

With your auth credentials defined, set up a forward-auth middleware. This causes Traefik to forward each incoming request for a router configured with this middleware for authentication.

In Kubernetes, this can be done with the following manifest:

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: traefik-simple-auth
spec:
  forwardAuth:
    address: http://traefik-simple-auth:8080
    trustForwardHeader: true
    authResponseHeaders:
      - "X-Forwarded-User"

This created a new middleware traefik-simple-auth that forwards incoming requests to http://traefik-simple-auth:8080 (the service pointing to traefik-simple-auth) for authentication.

traefik-simple-auth will add the email address of the authenticated used in the X-Forwarded-User header.

Ingress for Authentication

To authenticate a user, traefik-simple-auth redirects the user to the auth provider's login page. Upon successful login, the provider forwards the request to the redirectURL (as configured in section Using Google as auth provider). You therefore need an ingress to route the request to traefik-simple-auth:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: traefik-simple-auth
  namespace: traefik
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
spec:
  rules:
    - host: auth.example.com
      http:
        paths:
          - path: /_oauth
            pathType: Prefix
            backend:
              service:
                name: traefik-simple-auth
                port:
                  number: 8080

This forwards the request to traefik-simple-auth.

Note: unlike with github/thomseddon/traefik-forward-auth, the ingress for the authentication callback flow does not need the forwardAuth middleware (i.e. it does not include a traefik.ingress.kubernetes.io/router.middlewares: <traefik-simple-auth> annotation).

Authenticating access to an ingress

To enable traefik-simple-auth to authenticate access to an ingress, add the middleware as an annotation:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: grafana-external
  namespace: monitoring
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: websecure
    traefik.ingress.kubernetes.io/router.middlewares: traefik-traefik-simple-auth@kubernetescrd
spec:
  rules:
    [...]

Each access to the ingress causes traefik to first forward the request to the middleware. If the middleware responds with an HTTP 2xx code (meaning the request has a valid session cookie), traefik honours the request.

Note: traefik prepends the namespace to the name of the middleware defined via a kubernetes resource. So, the middleware traefik-simple-auth in the traefik namespace becomes traefik-traefik-simple-auth.