Belajar Authentik - Troubleshooting & Debugging

#Pendahuluan

Di episode 27 kalian menutup sebanyak mungkin celah keamanan. Namun tidak ada sistem yang bebas masalah selamanya — aplikasi berubah, dependensi berubah, dan konfigurasi yang tampak benar bisa gagal pada kombinasi tertentu. Ketika masalah muncul, kualitas kalian sebagai operator diuji bukan oleh seberapa cepat kalian menghafal solusi, melainkan oleh seberapa sistematis kalian menyelidiki.

Bayangkan troubleshooting seperti diagnosis dokter: dokter tidak menebak obat dari satu gejala, ia mengumpulkan riwayat, memeriksa tanda vital, lalu mempersempit penyebab. Episode ini akan mengajarkan pola pikir itu untuk Authentik: mulai dari log, kenali enam masalah paling umum, gunakan flow inspector, lalu tahu kapan harus bertanya kepada komunitas.

#Log: Titik Awal Setiap Investigasi

Semua jawaban dimulai dari log. Authentik menulis log terstruktur ke stdout — tempat yang sama yang bisa kalian streaming dari Compose atau Kubernetes:

docker compose logs -f server worker

Log pod server di Kubernetes

kubectl logs -n authentik deploy/authentik-server

Pahami pembagian tugas sebelum membaca: server mencatat semua lalu lintas HTTP — request masuk, flow yang dijalankan, error dari permintaan pengguna. Worker mencatat tugas latar belakang — email yang gagal terkirim, event yang gagal diproses, sinkronisasi yang error. Jika masalahnya "email tidak terkirim", log server tidak akan menjawab; lihat worker. Jika UI error, lihat server.

Jika log biasa belum cukup detail, naikkan AUTHENTIK_LOG_LEVEL ke debug sementara waktu (episode 25). Log debug bisa sangat berisik — aktifkan hanya untuk investigasi dan kembalikan setelah selesai. Untuk alur log yang lebih nyaman dipindai, gabungkan dengan docker compose logs -f --since 10m server agar hanya melihat sepuluh menit terakhir, dan tambahkan --tail saat ingin membatasi jumlah baris.

#Masalah Umum #1: Error 500 di Semua Halaman

Semua halaman menampilkan 500 secara konsisten biasanya berarti satu dari tiga hal: koneksi database terputus, migrasi belum selesai, atau AUTHENTIK_SECRET_KEY tidak konsisten antar pod. Periksa log server untuk jejak koneksi database, dan pastikan migrasi berjalan penuh saat startup. Uji koneksi database secara langsung untuk menyingkirkan kemungkinan jaringan:

docker compose exec postgresql psql -U authentik -d authentik -c "SELECT 1;"

Jika perintah ini berhasil tetapi Authentik tetap 500, arahkan ke dua kemungkinan lain: status migrasi dan konsistensi secret key antar instance.

#Masalah Umum #2: Outpost Connection Refused / Offline

Outpost yang ditandai offline di UI berarti ia tidak bisa berkomunikasi dengan API Authentik. Penyebab paling umum: AUTHENTIK_HOST salah (outpost tidak tahu harus menghubungi alamat mana), token service connection kedaluwarsa atau salah, atau firewall memblokir koneksi keluar dari outpost ke API. Uji dari sisi outpost:

curl -fsS http://localhost:9000/outpost.goauthentik.io/ping

Jika ping gagal, periksa konfigurasi host outpost dan perbarui token lewat halaman outpost di admin. Setelah token diperbarui, outpost akan memuat ulang konfigurasi — proses yang biasanya terlihat di log worker.

#Masalah Umum #3: OIDC Redirect Error

Error seperti redirect_uri does not match adalah yang paling sering ditemui dalam integrasi OIDC. Authentik mencocokkan redirect URI secara ketat: skema, host, port, dan path harus identik. https://app.example.com/callback berbeda dari http://app.example.com/callback — satu huruf "s" yang menghancurkan login.

Periksa juga dua hal lain: waktu (jam server yang melenceng membuat verifikasi token gagal — pastikan NTP berjalan) dan signing key (jika kunci JWT berubah, aplikasi yang menyimpan kunci lama akan menolak token baru). Bandingkan persis URI yang didaftarkan di provider dengan yang dikirim aplikasi saat login. Untuk SPA yang memakai PKCE, pastikan juga code_challenge dikirim dengan metode yang sama yang didukung provider — mismatch metode antara plain dan S256 adalah penyebab error yang jarang disadari.

#Masalah Umum #4: SAML Attribute Mismatch

Dengan SAML, masalah paling umum bukan di autentikasi itu sendiri, melainkan di atribut. User berhasil login tetapi aplikasi tidak mengenalinya — biasanya karena nama atribut tidak cocok, NameID format berbeda, atau mapping salah (episode 14). Gunakan extension SAML tracer di browser untuk melihat assertion yang diterima aplikasi: bandingkan nama atribut yang dikirim Authentik dengan yang diharapkan aplikasi.

Error tanda tangan yang gagal biasanya berarti ketidakcocokan sertifikat: service provider memegang sertifikat IdP lama, atau metadata belum diimpor ulang. Dan jangan lupakan jam: SAML sangat sensitif terhadap perbedaan waktu karena assertion punya masa berlaku.

#Masalah Umum #5: Koneksi Database

Kesalahan koneksi database muncul dengan berbagai wajah: fe_sendauth: no password supplied (kredensial tidak terkirim), connection refused (host/port salah atau database belum naik), atau too many connections (batas max_connections terlampaui). Untuk kredensial, periksa variabel AUTHENTIK_POSTGRESQL__HOST, user, password, dan pastikan sesuai dengan yang disetel di database. Jika too many connections, pertimbangkan connection pooler seperti PgBouncer dan periksa koneksi idle yang menumpuk.

#Masalah Umum #6: Masalah Sesi

Pengguna yang terus-menerus di-logout biasanya berakar pada cookie. Periksa AUTHENTIK_COOKIE_DOMAIN — cookie domain yang salah membuat browser menolak atau mengirim cookie ke domain yang keliru. Perhatikan juga browser yang memblokir third-party cookie: jika Authentik berjalan di domain berbeda dari aplikasi, beberapa browser akan memblokir cookie yang diperlukan untuk forward auth. Terakhir, rotasi AUTHENTIK_SECRET_KEY akan menandatangani ulang semua sesi — user yang tiba-tiba di-logout massal setelah upgrade adalah tanda kunci berubah.

#Flow Inspector: Mikroskop untuk Alur Autentikasi

Ketika masalah berada di dalam flow, log sering tidak cukup detail. Flow inspector adalah alat yang dibuat persis untuk ini: ia menjalankan flow langkah demi langkah dan menampilkan setiap stage yang dieksekusi, hasil setiap policy, dan context yang lewat. Aktifkan dari halaman flow, lalu jalankan flow sebagai pengguna yang bermasalah.

Ini seperti menonton rekaman ulang pertandingan dengan gerakan lambat: kalian bisa melihat persis stage mana yang menolak, policy mana yang mengembalikan False, dan field mana yang menyebabkan flow berhenti. Untuk kebijakan, gunakan juga policy tester untuk mengevaluasi ekspresi tanpa harus menjalankan flow penuh.

#Event Log: Bukti, Bukan Tebakan

Sementara flow inspector menjawab bagaimana sebuah flow berjalan, event log menjawab apa yang terjadi di seluruh sistem. Menu Events di admin menyimpan jejak login, logout, aksi admin, dan kegagalan autentikasi beserta konteksnya — siapa, dari IP mana, kapan, dan hasilnya apa. Ini adalah saksi bisu yang paling bisa diandalkan saat mengejar masalah "tidak semua orang bisa login, hanya sebagian".

Perhatikan pola dalam event: banyak kegagalan dari IP yang sama menunjuk ke brute force atau firewall yang memblokir NAT besar; kegagalan yang konsisten dari aplikasi tertentu menunjuk ke misconfigurasi provider aplikasi itu. Untuk investigasi yang lebih dalam, event juga bisa diambil lewat API menggunakan token dari episode 21 — curl -H 'Authorization: Bearer TOKEN' https://auth.example.com/api/v3/events/events/ — sehingga bisa digabung dengan data dari luar.

Jangan lupa memeriksa System Tasks: daftar tugas terjadwal seperti sinkronisasi dan pembersihan event yang berjalan di worker. Tugas yang gagal berulang adalah akar dari banyak masalah "aneh" — misalnya sinkronisasi LDAP yang berhenti membuat user baru tidak muncul, atau pembersihan event yang berhenti membuat database membengkak.

#Struktur Investigasi dan Kapan Bertanya

Susun penyelidikan dengan urutan: log server → log worker → health check → database → konfigurasi host → flow inspector. Dua pertanyaan yang mempersempit setengah masalah: "Kapan terakhir kali berfungsi?" dan "Apa yang berubah sejak saat itu?" — upgrade, perubahan DNS, atau rotasi kunci adalah tersangka utama.

Jika kalian harus bertanya ke komunitas, siapkan informasi yang baik: versi (ak version), cara deploy (Compose/Kubernetes), log error yang relevan tanpa data sensitif, dan langkah reproduksi. Pertanyaan dengan tiga hal itu jauh lebih cepat dijawab daripada "Authentik saya error, tolong".

docker compose exec server ak version

Kanal yang tepat: GitHub Issues untuk kemungkinan bug (cari dulu, jangan tanya yang sudah ada), Discord komunitas untuk diskusi dan bantuan cepat, serta dokumentasi resmi yang terus diperbarui. Dokumentasi resmi adalah kurva belajar terbaik — sebagian besar "masalah aneh" ternyata adalah perilaku yang sudah didokumentasikan.

Terakhir, biasakan mendokumentasikan setiap masalah yang sudah dipecahkan. Runbook yang berisi gejala, penyebab, dan solusi akan terasa tidak berguna sampai masalah yang sama muncul dua bulan kemudian — dan saat itulah kalian berterima kasih kepada diri sendiri. Satu-satunya penemuan yang lebih berharga daripada solusi adalah solusi yang tidak perlu ditemukan dua kali.

#Penutup

Pada episode 28 ini kalian telah belajar menyelidiki masalah Authentik secara sistematis: membaca log server dan worker dengan memahami pembagian tugas keduanya, menangani enam masalah umum dari error 500, outpost yang offline, redirect OIDC yang ditolak, atribut SAML yang tidak cocok, koneksi database, hingga masalah sesi — plus memanfaatkan flow inspector dan policy tester untuk investigasi di dalam flow, dan mengetahui cara bertanya ke komunitas dengan informasi yang memadai.

Inti yang harus kalian bawa:

• Mulai dari log; bedakan masalah server vs worker sejak awal.
• Redirect URI OIDC harus cocok persis; SAML peka terhadap atribut dan jam.
• Flow inspector dan policy tester mengubah tebakan menjadi bukti.
• Selalu tanyakan dua hal: kapan terakhir berfungsi, dan apa yang berubah.
• Laporan ke komunitas yang baik memuat versi, cara deploy, dan log relevan.

Setelah Authentik kalian berjalan mulus, pertanyaan berikutnya adalah bagaimana jika datang dari sistem lain. Di episode 29 berikutnya kita akan membahas Migration from Other IdPs: berpindah dari Keycloak, Authelia, atau Dex secara bertahap, mengekspor user dan grup, memanfaatkan sinkronisasi LDAP/AD, membangun ulang provider lewat blueprint, melakukan swap aplikasi per aplikasi, serta merancang cutover dan rollback yang aman. Sampai jumpa di episode 29!