thomseddon/traefik-forward-auth: OAuth SSO for Traefik in one small container

What problem thomseddon/traefik-forward-auth solves

Traefik routes traffic but does not authenticate users. Anything you expose through it is either public or protected by something you wrote yourself. This project fills that gap with a single container that Traefik calls before it forwards a request, and that answers with a redirect to an OAuth provider when the caller has no valid session.

The intended user is someone who already runs Traefik as a reverse proxy and wants login on internal tools, dashboards or staging environments. The README lists the motivations directly: overlay any HTTP service with one endpoint, support Google and OpenID Connect, generate redirect URIs for multiple domains dynamically, and allow authentication to be bypassed selectively through rules. It also supports a centralised auth host and cookies that persist across domains.

That scope matters. This is not a user directory, not a policy engine, and not a replacement for an identity provider. It is the piece that sits between Traefik and your provider and decides whether a request continues.

How the forward auth mechanism works

Traefik's forward auth middleware sends an HTTP request to a configured address before serving the real backend. In the README's compose example the address is `http://traefik-forward-auth:4181`, and the service listens on port 4181. If the auth service returns a success status, Traefik proceeds; otherwise the response, typically a redirect to the provider, goes back to the browser.

Authentication state lives in a cookie signed with the `SECRET` value. The README notes that redirect URIs are generated dynamically per domain, which is why the same container can protect several hostnames. Two operation modes are documented: overlay mode, where the auth endpoint is mounted under each protected host at a path such as `/_oauth`, and auth host mode, where a single central host handles the login flow for every service.

After login, the service can pass identity downstream through forwarded headers. The compose example configures `traefik.http.middlewares.traefik-forward-auth.forwardauth.authResponseHeaders=X-Forwarded-User`, so the backend receives the authenticated user's identity as a header rather than having to parse a cookie. Downstream services should treat that header as trusted only because it comes from Traefik, never from the public internet.

Installing thomseddon/traefik-forward-auth with Docker

The README recommends the `2` tag on Docker Hub, `thomseddon/traefik-forward-auth:2`. ARM images are published with `-arm` or `-arm64` appended, and binary releases exist as GitHub release assets for versions after 2.2.0. There is no package manager install path documented in the README.

The smallest working setup is a compose file with Traefik, the auth service and one protected app. The README gives this shape, with the Google client credentials, a random `SECRET`, and `INSECURE_COOKIE=true` for a test environment without HTTPS.

services:
  traefik-forward-auth:
    image: thomseddon/traefik-forward-auth:2
    environment:
      - PROVIDERS_GOOGLE_CLIENT_ID=your-client-id
      - PROVIDERS_GOOGLE_CLIENT_SECRET=your-client-secret
      - SECRET=something-random
      - INSECURE_COOKIE=true # Example assumes no https, do not use in production
    labels:
      - "traefik.http.middlewares.traefik-forward-auth.forwardauth.address=http://traefik-forward-auth:4181"
      - "traefik.http.middlewares.traefik-forward-auth.forwardauth.authResponseHeaders=X-Forwarded-User"
      - "traefik.http.services.traefik-forward-auth.loadbalancer.server.port=4181"

Attach the middleware to a router to protect it. In the README's example the protected service gets a host rule and a middleware reference, and the auth service is registered on port 4181.

  whoami:
    image: containous/whoami
    labels:
      - "traefik.http.routers.whoami.rule=Host(`whoami.mycompany.com`)"
      - "traefik.http.routers.whoami.middlewares=traefik-forward-auth"

On the provider side, the Google instructions say to create an OAuth client ID of type Web Application and fill Authorized redirect URIs with every domain you will authenticate from, appended with the `url-path`, for example `https://app.test.com/_oauth`. If that list does not match the hostnames you protect, the provider will reject the callback and you will see the error at the provider rather than in the container logs.

For providers that speak OpenID Connect 1.0, the README requires `providers.oidc.issuer-url`, `providers.oidc.client-id` and `providers.oidc.client-secret`. For anything else, the generic OAuth2 provider takes `providers.generic-oauth.auth-url`, `providers.generic-oauth.token-url` and `providers.generic-oauth.user-url`.

Where the design constrains you

The service has no user store. Anyone who can complete the OAuth flow at your provider is a valid user, subject to the restriction rules the README describes. If your requirement is that only members of a particular group reach a particular backend, that logic has to live somewhere else, because this project does not document group or role mapping.

Session lifetime is another boundary. The README mentions a `lifetime` option that supports extended authentication beyond the Google token lifetime, which means the default behaviour is tied to the provider's token lifetime. Teams expecting a long-lived session without setting that option will find users redirected to the provider more often than they expect.

The `SECRET` value signs cookies. Rotating it invalidates every existing session, and the README does not document a key rotation procedure or a way to accept two secrets at once. The README also does not document rollback if a new release changes behaviour; the upgrade guide for v2 is the closest thing to migration documentation, and it exists because v2 modified a number of configuration options while staying backwards compatible.

Finally, this is a Go binary built into a scratch container. The Dockerfile copies only the binary and the CA certificates, so there is no shell, no package manager and no debugging tooling inside the image. Troubleshooting happens through logs and through the provider's own error pages.

oauth2-proxy compared with traefik-forward-auth

The closest alternative in the same space is oauth2-proxy, which is also a reverse proxy authentication service and is listed among this project's own topics. The difference in approach is where the proxy sits. oauth2-proxy is designed to be the entry point itself, terminating requests and proxying to upstreams it knows about. traefik-forward-auth does not proxy anything; it answers Traefik's forward auth call and lets Traefik do the routing it was already doing.

That makes the choice mostly about your existing topology. If Traefik already owns routing, TLS and middleware, adding a forward auth endpoint is a smaller change than inserting a second proxy into the request path. If you are not running Traefik, or you want the auth layer to own upstream routing, oauth2-proxy fits better. Authelia and Authentik appear in the related searches and take a different direction again: they are identity platforms with their own user stores and portals, whereas this project delegates all identity to the provider and keeps no directory of its own.

Maintenance, releases and licence

The repository is not archived. The last push was on 2026-04-03, which is within six months of the current date, and the recent release list shows v2.3.0 on 2024-05-06, with v2.2.0 in 2020 and v2.1.0 in 2020. So the release cadence is uneven: a four-year gap sits between v2.2.0 and v2.3.0. The README recommends the moving `2` tag, which means a container restart can pull a newer image than the one you validated. Pinning to a specific tag such as `2.3.0` is the way to avoid that, at the cost of applying updates manually.

The module targets Go 1.25 with a pinned toolchain, and the dependency list includes `github.com/traefik/traefik/v2` at v2.11.34, so the project tracks Traefik v2 APIs. The go.mod file also contains replace directives pointing several dependencies at Containous forks, including a gorilla/mux replacement dated 2025. Those forks are part of the supply chain you inherit when you build from source.

The licence is MIT. That permits commercial and private use, modification and redistribution provided the copyright notice and permission notice are kept. It is not legal advice; if you redistribute the binary or embed the code, read LICENSE.md and your own obligations.

Editorial conclusion

Adopt it if you already run Traefik and want Google or OIDC login in front of a handful of internal services without operating a full identity stack. Do not adopt it if you need per-user authorisation, a user database, or group-based access control; the README documents user restriction, not role management. Before rolling it out, verify that your provider's redirect URIs match the url-path you choose, and check the v2 upgrade guide so the container does not start with configuration warnings.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. thomseddon/traefik-forward-auth on GitHub