Using Traefik Forward Auth with KeyCloak¶
While the Traefik Forward Auth recipe demonstrated a quick way to protect a set of explicitly-specified URLs using OIDC credentials from a Google account, this recipe will illustrate how to use your own KeyCloak instance to secure any URLs within your DNS domain.
- DNS entry for your auth host ("auth.yourdomain.com" is a good choice), pointed to your keepalived IP
/var/data/config/traefik/traefik-forward-auth.env as follows (change "master" if you created a different realm):
CLIENT_ID=<your keycloak client name> CLIENT_SECRET=<your keycloak client secret> OIDC_ISSUER=https://<your keycloak URL>/auth/realms/master SECRET=<a random string to secure your cookie> AUTH_HOST=<the FQDN to use for your auth host> COOKIE_DOMAIN=<the root FQDN of your domain>
Prepare the docker service config¶
This is a small container, you can simply add the following content to the existing
traefik-app.yml deployed in the previous Traefik recipe:
traefik-forward-auth: image: funkypenguin/traefik-forward-auth env_file: /var/data/config/traefik/traefik-forward-auth.env networks: - traefik_public deploy: labels: - traefik.port=4181 - traefik.frontend.rule=Host:auth.example.com - traefik.frontend.auth.forward.address=http://traefik-forward-auth:4181 - traefik.frontend.auth.forward.trustForwardHeader=true
If you're not confident that forward authentication is working, add a simple "whoami" test container, to help debug traefik forward auth, before attempting to add it to a more complex container.
# This simply validates that traefik forward authentication is working whoami: image: containous/whoami networks: - traefik_public deploy: labels: - traefik.frontend.rule=Host:whoami.example.com - traefik.port=80 - traefik.frontend.auth.forward.address=http://traefik-forward-auth:4181 - traefik.frontend.auth.forward.authResponseHeaders=X-Forwarded-User - traefik.frontend.auth.forward.trustForwardHeader=true
I automatically and instantly share (with my sponsors) a private "premix" git repository, which includes necessary docker-compose and env files for all published recipes. This means that sponsors can launch any recipe with just a
git pull and a
docker stack deploy 👍.
🚀 Update: Premix now includes an ansible playbook, so that sponsors can deploy an entire stack + recipes, with a single ansible command! (more here)
Redeploy traefik with
docker stack deploy traefik-app -c /var/data/traefik/traeifk-app.yml, to launch the traefik-forward-auth container.
Browse to https://whoami.example.com (obviously, customized for your domain and having created a DNS record), and all going according to plan, you'll be redirected to a KeyCloak login. Once successfully logged in, you'll be directed to the basic whoami page.
To protect any other service, ensure the service itself is exposed by Traefik (if you were previously using an oauth_proxy for this, you may have to migrate some labels from the oauth_proxy serivce to the service itself). Add the following 3 labels:
- traefik.frontend.auth.forward.address=http://traefik-forward-auth:4181 - traefik.frontend.auth.forward.authResponseHeaders=X-Forwarded-User - traefik.frontend.auth.forward.trustForwardHeader=true
And re-deploy your services :)
What have we achieved? By adding an additional three simple labels to any service, we can secure any service behind our KeyCloak OIDC provider, with minimal processing / handling overhead.
- Traefik-forward-auth configured to authenticate against KeyCloak
Chef's notes 📓¶
KeyCloak is very powerful. You can add 2FA and all other clever things outside of the scope of this simple recipe ;) ↩
Tip your waiter (sponsor) 👏¶
Did you receive excellent service? Want to make your waiter happy? (..and support development of current and future recipes!) Sponsor me on Github / Patreon, or see the contribute page for more (free or paid) ways to say thank you! 👏
Flirt with waiter (subscribe) 💌¶
Want to know now when this recipe gets updated, or when future recipes are added? Subscribe to the RSS feed, or leave your email address below, and we'll keep you updated. (*double-opt-in, no monkey business, no spam)