parasail-ai/traefik-forward-auth

parasail-ai/traefik-forward-auth

Description: Minimal forward authentication service that provides Google/OpenID oauth based login and authentication for the traefik reverse proxy

License: MIT

Stars: 0

Forks: 0

Open issues: 0

Created: 2025-03-05T19:25:21Z

Pushed: 2024-08-15T06:30:48Z

Default branch: master

Fork: yes

Parent repository: thomseddon/traefik-forward-auth

Archived: no

README:

A minimal forward authentication service that provides OAuth/SSO login and authentication for the traefik reverse proxy/load balancer.

Why?

• Seamlessly overlays any http service with a single endpoint (see: url-path in [Configuration](#configuration))
• Supports multiple providers including Google and OpenID Connect (supported by Azure, Github, Salesforce etc.)
• Supports multiple domains/subdomains by dynamically generating redirect_uri's
• Allows authentication to be selectively applied/bypassed based on request parameters (see rules in [Configuration](#configuration))
• Supports use of centralised authentication host/redirect_uri (see auth-host in [Configuration](#configuration))
• Allows authentication to persist across multiple domains (see [Cookie Domains](#cookie-domains))
• Supports extended authentication beyond Google token lifetime (see: lifetime in [Configuration](#configuration))

Contents

• [Releases](#releases)
• [Usage](#usage)
• [Simple](#simple)
• [Advanced](#advanced)
• [Provider Setup](#provider-setup)
• [Configuration](#configuration)
• [Overview](#overview)
• [Option Details](#option-details)
• [Concepts](#concepts)
• [Forwarded Headers](#forwarded-headers)
• [User Restriction](#user-restriction)
• [Applying Authentication](#applying-authentication)
• [Global Authentication](#global-authentication)
• [Selective Ingress Authentication in Kubernetes](#selective-ingress-authentication-in-kubernetes)
• [Selective Container Authentication in Swarm](#selective-container-authentication-in-swarm)
• [Rules Based Authentication](#rules-based-authentication)
• [Operation Modes](#operation-modes)
• [Overlay Mode](#overlay-mode)
• [Auth Host Mode](#auth-host-mode)
• [Logging Out](#logging-out)
• [Copyright](#copyright)
• [License](#license)

Releases

We recommend using the 2 tag on docker hub (thomseddon/traefik-forward-auth:2).

You can also use the latest incremental releases found on docker hub and github.

ARM releases are also available on docker hub, just append -arm or -arm64 to your desired released (e.g. 2-arm or 2.1-arm64).

We also build binary files for usage without docker starting with releases after 2.2.0 You can find these as assets of the specific GitHub release.

Upgrade Guide

v2 was released in June 2019, whilst this is fully backwards compatible, a number of configuration options were modified, please see the upgrade guide to prevent warnings on startup and ensure you are using the current configuration.

Usage

Simple:

See below for instructions on how to setup your [Provider Setup](#provider-setup).

docker-compose.yml:

version: '3'

services:
traefik:
image: traefik:v2.2
command: --providers.docker
ports:
- "8085:80"
volumes:
- /var/run/docker.sock:/var/run/docker.sock

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"

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

Advanced:

Please see the examples directory for a more complete docker-compose.yml or kubernetes/simple-separate-pod.

Also in the examples directory is docker-compose-auth-host.yml and kubernetes/advanced-separate-pod which shows how to configure a central auth host, along with some other options.

Provider Setup

Below are some general notes on provider setup, specific instructions and examples for a number of providers can be found on the Provider Setup wiki page.

##### Google

Head to https://console.developers.google.com and make sure you've switched to the correct email account.

Create a new project then search for and select "Credentials" in the search bar. Fill out the "OAuth Consent Screen" tab.

Click "Create Credentials" > "OAuth client ID". Select "Web Application", fill in the name of your app, skip "Authorized JavaScript origins" and fill "Authorized redirect URIs" with all the domains you will allow authentication from, appended with the url-path (e.g. https://app.test.com/_oauth)

You must set the providers.google.client-id and providers.google.client-secret config options.

##### OpenID Connect

Any provider that supports OpenID Connect 1.0 can be configured via the OIDC config options below.

You must set the providers.oidc.issuer-url, providers.oidc.client-id and providers.oidc.client-secret config options.

Please see the Provider Setup wiki page for examples.

##### Generic OAuth2

For providers that don't support OpenID Connect, we also have the Generic OAuth2 provider where you can statically configure the OAuth2 and "user" endpoints.

You must set:

• providers.generic-oauth.auth-url - URL the client should…