Belajar Authentik - NGINX & Caddy Integration

#Pendahuluan

Di episode 12 kalian memasang middleware forwardAuth di Traefik — integrasi termudah karena semuanya deklaratif lewat label. Episode 13 meninjau dua proxy lain yang sama pentingnya di ekosistem self-hosted: NGINX dan Caddy. Keduanya memakai pola forward authentication yang sama — proxy bertanya, outpost menjawab, identitas diteruskan — tetapi dengan mekanisme dan filosofi konfigurasi yang berbeda.

NGINX adalah proxy klasik yang dikendalikan lewat blok konfigurasi teks; Caddy adalah proxy modern yang mengutamakan kesederhanaan Caddyfile dan HTTPS otomatis. Memahami ketiganya membuat kalian tidak terikat vendor: pola konsepnya sama, hanya bahasanya yang berbeda.

#NGINX: auth_request sebagai Sub-Request

Direktif auth_request mengirim sub-request ke sebuah lokasi setiap kali ada permintaan masuk. Cara kerjanya tegas:

• Sub-request membalas 2xx → permintaan diteruskan ke aplikasi.
• Sub-request membalas 401 → NGINX mengarahkan ke portal login.

Lokasi yang dipanggil adalah /outpost.goauthentik.io/auth/nginx, dan seluruh path /outpost.goauthentik.io harus di-proxy ke outpost tanpa autentikasi. Konfigurasi lengkapnya:

server {
    listen 443 ssl;
    server_name app.example.com;
 
    location / {
        proxy_pass http://app:8080;
        proxy_set_header Host $host;
 
        auth_request /outpost.goauthentik.io/auth/nginx;
 
        auth_request_set $username $upstream_http_x_authentik_username;
        auth_request_set $groups $upstream_http_x_authentik_groups;
        auth_request_set $email $upstream_http_x_authentik_email;
        auth_request_set $name $upstream_http_x_authentik_name;
        auth_request_set $uid $upstream_http_x_authentik_uid;
 
        proxy_set_header X-authentik-username $username;
        proxy_set_header X-authentik-groups $groups;
        proxy_set_header X-authentik-email $email;
        proxy_set_header X-authentik-name $name;
        proxy_set_header X-authentik-uid $uid;
 
        error_page 401 = @goauthentik_proxy_signin;
    }
 
    location /outpost.goauthentik.io {
        proxy_pass http://authentik-server:9000/outpost.goauthentik.io;
        proxy_set_header Host $host;
        proxy_set_header X-Original-URL $scheme://$http_host$request_uri;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
    }
 
    location @goauthentik_proxy_signin {
        internal;
        return 302 /outpost.goauthentik.io/start?rd=$scheme://$http_host$request_uri;
    }
}

Bagian yang perlu dipahami:

• auth_request /outpost.goauthentik.io/auth/nginx; — kalimat inti yang mengirim sub-request ke lokasi outpost.
• auth_request_set — menyimpan header dari respons outpost ke variabel NGINX. Outpost mengembalikan identitas user lewat header X-authentik-*, lalu kita teruskan ke aplikasi dengan proxy_set_header.
• X-Original-URL — memberi tahu outpost URL asli yang diminta user. Tanpa header ini, evaluasi policy berbasis path (episode 6) tidak bekerja benar.
• proxy_pass_request_body off; — sub-request verifikasi tidak perlu membawa body permintaan asli.
• error_page 401 = @goauthentik_proxy_signin; — saat outpost menjawab 401, redirect ke /outpost.goauthentik.io/start?rd=... yang memulai alur login lalu kembali ke halaman semula.

#Caddy: forward_auth yang Ringkas

Caddy menyediakan direktif bawaan forward_auth. Ia melakukan hal yang sama seperti auth_request NGINX, tetapi sintaksnya jauh lebih pendek. Sekaligus, setiap blok situs otomatis mendapat sertifikat TLS dari Let's Encrypt — satu hal yang bisa kalian serahkan sepenuhnya.

Caddyfile — forward_auth Authentik

app.example.com {
    route {
        reverse_proxy /outpost.goauthentik.io/* http://authentik-server:9000
 
        forward_auth http://authentik-server:9000 {
            uri /outpost.goauthentik.io/auth/caddy
            copy_headers X-Authentik-Username X-Authentik-Groups X-Authentik-Email X-Authentik-Name X-Authentik-Uid
        }
 
        reverse_proxy app:8080
    }
}

Mari bedah:

• route — memastikan urutan eksekusi direktif dijamin: path outpost di-proxy dulu, autentikasi dijalankan, baru aplikasi.
• reverse_proxy /outpost.goauthentik.io/* http://authentik-server:9000 — meneruskan seluruh path outpost ke outpost tanpa autentikasi.
• forward_auth http://authentik-server:9000 — setiap permintaan lain dikirim sebagai sub-request ke outpost.
• uri /outpost.goauthentik.io/auth/caddy — endpoint verifikasi khusus Caddy.
• copy_headers — menyalin header identitas dari respons outpost ke permintaan aplikasi. Casing penting di sini: header ditulis X-Authentik-Username dan seterusnya, bukan X-authentik-username.

Caddy secara default tidak mempercayai header dari proxy lain dan membersihkan header yang berpotensi dipalsukan. Jika ada lapisan proxy di depan Caddy, tambahkan direktif trusted_proxies di dalam blok forward_auth.

#Perbandingan Ketiga Proxy

Ketiganya menunjuk ke outpost yang sama dan menerima header identitas yang sama. Pilihan proxy seharusnya didasarkan pada apa yang sudah kalian pakai di infrastruktur, bukan fitur autentikasinya.

#Testing dan Troubleshooting

Alur uji yang tenang untuk ketiga proxy:

1. Akses aplikasi tanpa login — kalian harus diarahkan ke portal Authentik.
2. Login dan selesaikan MFA — diarahkan kembali ke aplikasi tanpa login kedua.
3. Periksa bahwa aplikasi menerima header X-authentik-username — gunakan aplikasi sederhana yang menampilkan seluruh request header (misalnya traefik/whoami).
4. Pastikan path /outpost.goauthentik.io/ping merespons 204 — ini membuktikan outpost terjangkau dari proxy.

Masalah yang paling sering terjadi:

• Lupa rule/path outpost publik — sub-request ke outpost gagal, semua permintaan ditolak.
• Header identitas kosong di aplikasi — periksa nama variabel di auth_request_set (NGINX) atau casing copy_headers (Caddy).
• Redirect tidak kembali ke halaman semula — periksa rd pada redirect, yang dibangun dari X-Original-URL.

Validasi sintaks sebelum reload: nginx -t untuk NGINX, dan caddy validate --config Caddyfile untuk Caddy.

#Penutup

Episode ini menutup fase integrasi reverse proxy. Kalian kini menguasai tiga cara memasang pola yang sama: middleware forwardAuth Traefik dengan Docker labels, auth_request NGINX dengan auth_request_set, dan forward_auth Caddy dengan copy_headers — plus tiga endpoint outpost yang masing-masing memakai suffix /auth/traefik, /auth/nginx, dan /auth/caddy.

Pola yang kalian bawa selanjutnya: proxy selalu meneruskan header X-authentik-*, dan otorisasi dipegang Authentik lewat policy. Di episode 14, kita berpindah fase: SAML provider configuration — membuat Authentik bertindak sebagai Identity Provider bagi aplikasi enterprise yang belum mendukung OIDC. Sampai jumpa!