Traefik Forward Auth with Keycloak for SSO

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.

Ingredients

Preparation

Setup environment

Create /var/data/config/traefik/traefik-forward-auth.env as per the following example (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

Serving

Launch

Redeploy traefik with docker stack deploy traefik-app -c /var/data/traefik/traeifk-app.yml, to launch the traefik-forward-auth container.

Test

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.

Protect services

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 :)

Summary

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.

Keycloak vs Authelia

Keycloak is the "big daddy" of self-hosted authentication platforms - it has a beautiful GUI, and a very advanced and mature featureset. Like Authelia, Keycloak can use an LDAP server as a backend, but unlike Authelia, Keycloak allows for 2-way sync between that LDAP backend, meaning Keycloak can be used to create and update the LDAP entries (Authelia's is just a one-way LDAP lookup - you'll need another tool to actually administer your LDAP database).

Chef's notes 📓

Tip your waiter (sponsor) 👏

Did you receive excellent service? Want to compliment the chef? (..and support development of current and future recipes!) Sponsor me on Github / Ko-Fi / Patreon, or see the contribute page for more (free or paid) ways to say thank you! 👏

Employ your chef (engage) 🤝

Is this too much of a geeky PITA? Do you just want results, stat? I do this for a living - I'm a full-time Kubernetes contractor, providing consulting and engineering expertise to businesses needing short-term, short-notice support in the cloud-native space, including AWS/Azure/GKE, Kubernetes, CI/CD and automation.

Learn more about working with me here.

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.

Your comments? 💬