Belajar Authentik - Traefik Integration

#Pendahuluan

Di episode 11 kita memahami fondasi proxy provider: konsep forward authentication, outpost sebagai komponen yang menjalankan provider, dan alur authorization dari permintaan masuk hingga header identitas disuntikkan ke aplikasi. Episode ini menerapkan fondasi itu pada proxy yang paling akrab dengan dunia container: Traefik.

Authentik memakai pola yang sudah kita kenal: sebelum permintaan diteruskan ke aplikasi, reverse proxy bertanya ke outpost. Traefik menyediakan fasilitas ini lewat middleware forwardAuth — sebuah pipa pemrosesan yang mengirim permintaan ke alamat outpost dan menilai nasib permintaan asli dari responsnya.

Analogi: kalian punya satpam (Traefik) yang menerima tamu di depan gedung. Sebelum membukakan pintu, satpam menelpon pusat keamanan (Authentik outpost). Hanya jika pusat keamanan menjawab "orang ini dikenal", pintu dibuka dan identitas tamu diumumkan lewat pengeras suara — itulah header X-authentik-*.

#Konsep Middleware forwardAuth

Middleware forwardAuth di Traefik bekerja sederhana:

• Respons 2xx dari outpost berarti permintaan diteruskan ke aplikasi.
• Respons selain itu (biasanya redirect ke portal login) diserahkan ke browser untuk diproses.

Konfigurasi intinya didefinisikan dalam dynamic config Traefik:

http:
  middlewares:
    authentik:
      forwardAuth:
        address: "http://outpost.example.com:9000/outpost.goauthentik.io/auth/traefik"
        trustForwardHeader: true
        authResponseHeaders:
          - X-authentik-username
          - X-authentik-groups
          - X-authentik-email
          - X-authentik-name
          - X-authentik-uid
          - X-authentik-jwt

Opsi yang perlu dipahami:

• address — endpoint outpost untuk mode forward auth Traefik. Perhatikan path /outpost.goauthentik.io/auth/traefik, bukan portal Authentik. Port 9000 adalah port HTTP outpost proxy.
• trustForwardHeader — memberitahu outpost untuk mempercayai header X-Forwarded-* yang dikirim Traefik. Header inilah yang dipakai Authentik untuk mengetahui skema, host, dan IP asli permintaan.
• authResponseHeaders — daftar header dari respons outpost yang disalin ke permintaan yang diteruskan ke aplikasi. Inilah mekanisme Trusted Header SSO: aplikasi mengenali user dari header ini tanpa form login.

Header yang paling sering dipakai aplikasi adalah X-authentik-username, X-authentik-email, X-authentik-name, X-authentik-groups, dan X-authentik-uid. Versi Authentik terbaru juga menyediakan X-authentik-jwt untuk token JWT, serta header X-authentik-meta-* yang membawa metadata outpost dan provider.

#Pemasangan lewat Docker Labels

Keunggulan Traefik di ekosistem Docker: konfigurasi routing bisa dideklarasikan langsung lewat label container. Middleware yang sama bisa dipasang ke sebuah layanan hanya dengan satu baris:

services:
  whoami:
    image: traefik/whoami
    labels:
      traefik.enable: "true"
      traefik.http.routers.whoami.rule: "Host(`whoami.example.com`)"
      traefik.http.routers.whoami.entryPoints: "websecure"
      traefik.http.routers.whoami.tls: "true"
      traefik.http.routers.whoami.middlewares: "authentik@file"

Kalimat ajaibnya ada di baris terakhir: traefik.http.routers.whoami.middlewares: "authentik@file". Suffix @file menunjukkan middleware authentik didefinisikan di file provider, bukan lewat label. Jika ingin mendefinisikan middleware lewat label, prefix-nya menjadi traefik.http.middlewares.authentik.forwardauth.* dan suffix-nya @docker.

Ada satu syarat penting: semua permintaan di bawah path /outpost.goauthentik.io harus tetap bisa diakses tanpa autentikasi. Path ini dipakai outpost untuk menerima respons OAuth2 setelah user login di portal. Tambahkan router khusus dengan rule Host(whoami.example.com) dan PathPrefix(/outpost.goauthentik.io) yang diteruskan langsung ke outpost.

#Outpost: Embedded atau Standalone

Proxy provider dijalankan oleh outpost. Ada dua pilihan deployment yang umum:

1. Embedded outpost — outpost berjalan di dalam container Authentik server. Address middleware cukup menunjuk ke http://authentik-server:9000/... (nama service compose).
2. Standalone proxy outpost — container terpisah dengan image ghcr.io/goauthentik/proxy:latest, diatur lewat dua environment variable:

docker run -d \
  --name authentik-proxy \
  -p 9000:9000 \
  -e AUTHENTIK_HOST=http://auth.example.com \
  -e AUTHENTIK_TOKEN=token-rahasia-outpost \
  ghcr.io/goauthentik/proxy:latest

AUTHENTIK_HOST adalah URL eksternal Authentik, dan AUTHENTIK_TOKEN adalah token outpost yang dibuat di UI (Outpost → token). Middleware Traefik lalu menunjuk ke http://authentik-proxy:9000/outpost.goauthentik.io/auth/traefik.

#Catatan Casing Header di Traefik v3

Traefik v3 menormalkan nama header yang disalin menjadi huruf kecil saat diteruskan ke aplikasi. HTTP memperlakukan nama header tanpa membedakan besar-kecil huruf, sehingga aplikasi yang membaca header secara case-insensitive tidak bermasalah. Jika aplikasi menuntut casing tertentu, gunakan authResponseHeadersRegex: "^X-authentik-" untuk menyalin semua header berprefiks X-authentik- sekaligus.

#Otorisasi per Aplikasi

Middleware hanya menangani apakah user sudah login. Otorisasi — apakah user boleh membuka aplikasi ini — dievaluasi Authentik lewat policy bindings pada aplikasi (ingat kembali episode 6). Artinya kalian bisa melindungi sepuluh aplikasi dengan middleware yang sama, tapi memberi policy berbeda pada tiap aplikasi: aplikasi admin membutuhkan grup ops, aplikasi dashboard cukup siapa pun yang login.

Untuk jalur yang boleh diakses tanpa autentikasi (misalnya /healthz atau endpoint callback), atur Unauthenticated Paths pada proxy provider.

#Logout dan Testing

Logout dilakukan lewat /outpost.goauthentik.io/sign_out pada host aplikasi yang dilindungi — outpost menghapus sesi Authentik lalu mengarahkan kembali ke aplikasi.

Sebelum menguji alur login penuh, pastikan outpost bisa dijangkau publik di bawah domain aplikasi:

curl -v https://whoami.example.com/outpost.goauthentik.io/ping

Respons HTTP/2 204 (No Content) berarti path outpost terbuka dan siap dipakai. Jika muncul 404 atau 502, periksa rule router khusus untuk /outpost.goauthentik.io — ini penyebab kegagalan nomor satu integrasi Traefik.

#Penutup

Episode ini mengintegrasikan Authentik dengan Traefik: memahami middleware forwardAuth dan endpoint /outpost.goauthentik.io/auth/traefik, mendefinisikan middleware di dynamic config maupun Docker labels, memilih opsi address, trustForwardHeader, dan authResponseHeaders dengan benar, memilih embedded atau standalone outpost, serta menguji path outpost dengan curl.

Traefik menunjukkan betapa mudahnya pola forward authentication di dunia container — satu middleware, dipakai ulang oleh semua layanan. Di episode 13 kita meninjau dua proxy lain yang sama populernya: NGINX dengan auth_request dan Caddy dengan forward_auth, lalu membandingkan ketiganya. Sampai jumpa!