Traefik Forward Auth

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)
• 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)
• Supports use of centralised authentication host/redirect_uri (see auth-host in Configuration)
• Allows authentication to persist across multiple domains (see Cookie Domains)
• Supports extended authentication beyond Google token lifetime (see: lifetime in Configuration)

Contents

• Releases
• Usage
• Simple
• Advanced
• Provider Setup
• Configuration
• Overview
• Option Details
• Concepts
• Forwarded Headers
• User Restriction
• Applying Authentication
  • Global Authentication
  • Selective Ingress Authentication in Kubernetes
  • Selective Container Authentication in Swarm
  • Rules Based Authentication
• Operation Modes
  • Overlay Mode
  • Auth Host Mode
• Logging Out
• Copyright
• 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.

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 be sent to authenticate the authenticate - providers.generic-oauth.token-url - URL the service should call to exchange an auth code for an access token - providers.generic-oauth.user-url - URL used to retrieve user info (service makes a GET request) - providers.generic-oauth.client-id - Client ID - providers.generic-oauth.client-secret - Client Secret

You can also set: - providers.generic-oauth.scope- Any scopes that should be included in the request (default: profile, email) - providers.generic-oauth.token-style - How token is presented when querying the User URL. Can be header or query, defaults to header. With header the token is provided in an Authorization header, with query the token is provided in the access_token query string value.

Please see the Provider Setup wiki page for examples.

Configuration

Overview

The following configuration options are supported:

Usage:
  traefik-forward-auth [OPTIONS]

Application Options:
  --log-level=[trace|debug|info|warn|error|fatal|panic] Log level (default: warn) [$LOG_LEVEL]
  --log-format=[text|json|pretty]                       Log format (default: text) [$LOG_FORMAT]
  --auth-host=                                          Single host to use when returning from 3rd party auth [$AUTH_HOST]
  --config=                                             Path to config file [$CONFIG]
  --cookie-domain=                                      Domain to set auth cookie on, can be set multiple times [$COOKIE_DOMAIN]
  --insecure-cookie                                     Use insecure cookies [$INSECURE_COOKIE]
  --cookie-name=                                        Cookie Name (default: _forward_auth) [$COOKIE_NAME]
  --csrf-cookie-name=                                   CSRF Cookie Name (default: _forward_auth_csrf) [$CSRF_COOKIE_NAME]
  --default-action=[auth|allow]                         Default action (default: auth) [$DEFAULT_ACTION]
  --default-provider=[google|oidc|generic-oauth]        Default provider (default: google) [$DEFAULT_PROVIDER]
  --domain=                                             Only allow given email domains, can be set multiple times [$DOMAIN]
  --lifetime=                                           Lifetime in seconds (default: 43200) [$LIFETIME]
  --logout-redirect=                                    URL to redirect to following logout [$LOGOUT_REDIRECT]
  --url-path=                                           Callback URL Path (default: /_oauth) [$URL_PATH]
  --secret=                                             Secret used for signing (required) [$SECRET]
  --whitelist=                                          Only allow given email addresses, can be set multiple times [$WHITELIST]
  --port=                                               Port to listen on (default: 4181) [$PORT]
  --rule.<name>.<param>=                                Rule definitions, param can be: "action", "rule" or "provider"

Google Provider:
  --providers.google.client-id=                         Client ID [$PROVIDERS_GOOGLE_CLIENT_ID]
  --providers.google.client-secret=                     Client Secret [$PROVIDERS_GOOGLE_CLIENT_SECRET]
  --providers.google.prompt=                            Space separated list of OpenID prompt options [$PROVIDERS_GOOGLE_PROMPT]

OIDC Provider:
  --providers.oidc.issuer-url=                          Issuer URL [$PROVIDERS_OIDC_ISSUER_URL]
  --providers.oidc.client-id=                           Client ID [$PROVIDERS_OIDC_CLIENT_ID]
  --providers.oidc.client-secret=                       Client Secret [$PROVIDERS_OIDC_CLIENT_SECRET]
  --providers.oidc.resource=                            Optional resource indicator [$PROVIDERS_OIDC_RESOURCE]

Generic OAuth2 Provider:
  --providers.generic-oauth.auth-url=                   Auth/Login URL [$PROVIDERS_GENERIC_OAUTH_AUTH_URL]
  --providers.generic-oauth.token-url=                  Token URL [$PROVIDERS_GENERIC_OAUTH_TOKEN_URL]
  --providers.generic-oauth.user-url=                   URL used to retrieve user info [$PROVIDERS_GENERIC_OAUTH_USER_URL]
  --providers.generic-oauth.client-id=                  Client ID [$PROVIDERS_GENERIC_OAUTH_CLIENT_ID]
  --providers.generic-oauth.client-secret=              Client Secret [$PROVIDERS_GENERIC_OAUTH_CLIENT_SECRET]
  --providers.generic-oauth.scope=                      Scopes (default: profile, email) [$PROVIDERS_GENERIC_OAUTH_SCOPE]
  --providers.generic-oauth.token-style=[header|query]  How token is presented when querying the User URL (default: header)
                                                        [$PROVIDERS_GENERIC_OAUTH_TOKEN_STYLE]
  --providers.generic-oauth.resource=                   Optional resource indicator [$PROVIDERS_GENERIC_OAUTH_RESOURCE]

Help Options:
  -h, --help                                            Show this help message

All options can be supplied in any of the following ways, in the following precedence (first is highest precedence):

1. Command Arguments/Flags - As shown above
2. Environment Variables - As shown in square brackets above
3. File
   1. Use INI format (e.g. url-path = _oauthpath)
   2. Specify the file location via the --config flag or $CONFIG environment variable
   3. Can be specified multiple times, each file will be read in the order they are passed

Option Details

• auth-host

When set, when a user returns from authentication with a 3rd party provider they will always be forwarded to this host. By using one central host, this means you only need to add this auth-host as a valid redirect uri to your 3rd party provider.

The host should be specified without protocol or path, for example:

--auth-host="auth.example.com"

For more details, please also read the Auth Host Mode, operation mode in the concepts section.

Please Note - this should be considered advanced usage, if you are having problems please try disabling this option and then re-read the Auth Host Mode section.

• config

Used to specify the path to a configuration file, can be set multiple times, each file will be read in the order they are passed. Options should be set in an INI format, for example:

url-path = _oauthpath

• cookie-domain

When set, if a user successfully completes authentication, then if the host of the original request requiring authentication is a subdomain of a given cookie domain, then the authentication cookie will be set for the higher level cookie domain. This means that a cookie can allow access to multiple subdomains without re-authentication. Can be specificed multiple times.

For example: --cookie-domain="example.com" --cookie-domain="test.org"

For example, if the cookie domain test.com has been set, and a request comes in on app1.test.com, following authentication the auth cookie will be set for the whole test.com domain. As such, if another request is forwarded for authentication from app2.test.com, the original cookie will be sent and so the request will be allowed without further authentication.

Bewar