This container is maintained by Funky Penguin's Geek Cookbook, a collection of "recipes" to run popular applications on Docker Swarm or Kubernetes, in a cheeky, geek format.
Got more details at:
What is funkypenguin/traefik-forward-auth ?
A fork of https://github.com/noelcatt/traefik-forward-auth, which is in turn a fork of https://github.com/thomseddon/traefik-forward-auth.
Why all the forkery? @thomseddon's version supports only Google OIDC, while @noelcatt's version supports any OIDC, but doesn't have a docker image build pipeline setup. At some point, I hope thaht @thomseddon's version will be extended to support multiple OIDCs, but until then, I'll maintain my own copy.
Why should I use this?
How do I use this?
A minimal forward authentication service that provides Google oauth based login and authentication for the traefik reverse proxy.
- Seamlessly overlays any http service with a single endpoint (see:
- Supports multiple domains/subdomains by dynamically generating redirect_uri's
- Allows authentication to persist across multiple domains (see Cookie Domains)
- Supports extended authentication beyond Google token lifetime (see:
See the (examples) directory for example docker compose and traefik configuration files that demonstrates the forward authentication configuration for traefik and passing required configuration values to traefik-forward-auth.
The following configuration is supported:
|-client-id||string||*Google Client ID (required)|
|-client-secret||string||*Google Client Secret (required)|
|-secret||string||*Secret used for signing (required)|
|-oidcIssuer||string||*OIDC Issuer URL (required)|
|-config||string||Path to config file|
|-auth-host||string||Central auth login (see below)|
|-cookie-domains||string||Comma separated list of cookie domains (see below)|
|-cookie-name||string||Cookie Name (default "_forward_auth")|
|-cookie-secure||bool||Use secure cookies (default true)|
|-csrf-cookie-name||string||CSRF Cookie Name (default "_forward_auth_csrf")|
|-domain||string||Comma separated list of email domains to allow|
|-whitelist||string||Comma separated list of email addresses to allow|
|-lifetime||int||Session length in seconds (default 43200)|
|-url-path||string||Callback URL (default "_oauth")|
|-prompt||string||Space separated list of OpenID prompt options|
|-log-level||string||Log level: trace, debug, info, warn, error, fatal, panic (default "warn")|
|-log-format||string||Log format: text, json, pretty (default "text")|
Configuration can also be supplied as environment variables (use upper case and swap
Configuration can also be supplied via a file, you can specify the location with
-config flag, the format is
flag value one per line, e.g.
Head to https://console.developers.google.com & 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.
url-path (e.g. https://app.test.com/_oauth)
The authenticated user is set in the
X-Forwarded-User header, to pass this on add this to the
authResponseHeaders as shown here.
You can restrict who can login with the following parameters:
-domain- Use this to limit logins to a specific domain, e.g. test.com only
-whitelist- Use this to only allow specific users to login e.g. email@example.com only
Note, if you pass
whitelist then only this is checked and
domain is effectively ignored.
You can supply a comma separated list of cookie domains, if the host of the original request is a subdomain of any given cookie domain, the authentication cookie will set with the given domain.
For example, if cookie domain is
test.com and a request comes in on
app1.test.com, the 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.
Beware however, if using cookie domains whilst running multiple instances of traefik/traefik-forward-auth for the same domain, the cookies will clash. You can fix this by using the same
cookie-secret in both instances, or using a different
cookie-name on each.
Overlay is the default operation mode, in this mode the authorisation endpoint is overlayed onto any domain. By default the
/_oauth path is used, this can be customised using the
If a request comes in for
www.myapp.com/home then the user will be redirected to the google login, following this they will be sent back to
www.myapp.com/_oauth, where their token will be validated (this request will not be forwarded to your application). Following successful authoristion, the user will return to their originally requested url of
As the hostname in the
redirect_uri is dynamically generated based on the orignal request, every hostname must be permitted in the Google OAuth console (e.g.
www.myappp.com would need to be added in the above example)
This is an optional mode of operation that is useful when dealing with a large number of subdomains, it is activated by using the
-auth-host config option (see this example docker-compose.yml).
For example, if you have a few applications:
appN.test.com, adding every domain to Google's console can become laborious.
To utilise an auth host, permit domain level cookies by setting the cookie domain to
test.com then set the
The user flow will then be:
- Request to
- User redirected to Google login
- After Google login, user is redirected to
- Token, user and CSRF cookie is validated, auth cookie is set to
- User is redirected to
- Request is allowed
With this setup, only
auth.test.com must be permitted in the Google console.
Two criteria must be met for an
auth-host to be used:
- Request matches given
auth-hostis also subdomain of same
2018 Thom Seddon