Belajar Authelia - Troubleshooting & Debugging

#Pendahuluan

Episode 28 membuat Authelia cepat. Sekarang bagian yang tidak bisa dihindari: hari ketika sesuatu rusak. Gejala Authelia bisa menyesatkan — pengguna melihat "halaman tidak bisa diakses", padahal akar masalahnya jauh di dalam konfigurasi. Episode 29 melatih kalian menelusuri gejala sampai ke akar.

Kunci troubleshooting Authelia adalah memahami arus: browser → reverse proxy → Authelia (verify) → Redis (sesi) → database (data) → redirection. Setiap gejala bisa dipetakan ke salah satu tautan dalam rantai ini. Mulailah dari yang paling sering terjadi.

#Masalah 1: 503 dari Reverse Proxy

Gejala paling umum: semua aplikasi menampilkan 502 atau 503, seolah tidak ada yang hidup. Padahal Authelia berjalan. Yang terjadi hampir selalu salah satu dari:

• Proxy tidak bisa menjangkau Authelia. Cek dari dalam proxy: curl -fsS http://authelia:9091/api/health. Gagal berarti masalah network, DNS, atau container tidak hidup.
• Endpoint verify salah. Proxy harus memanggil /api/verify, bukan root /. Pastikan URL auth di konfigurasi proxy persis.
• Timeout. Authelia lambat karena Redis/database bermasalah, dan proxy menyerah sebelum jawaban datang. Pantau metrik authelia_request_duration dari episode 26.

Urutan pemeriksaan: container hidup? → health check lulus? → network tersambung? → endpoint benar?

#Masalah 2: Redirect Loop

Pengguna login, berhasil, lalu diarahkan balik ke halaman login terus-menerus. Ini gejala klasik sesi tidak terlihat oleh instance yang mengevaluasi verify. Dua penyebab utama:

• Sesi tidak dibagikan. Instance A menerima login, instance B mengevaluasi request berikutnya — dan B tidak membaca Redis yang sama. Ini terjadi saat konfigurasi session.redis tidak konsisten antar-instance (ingat episode 24).
• Cookie tidak sampai. Cookie sesi di-set untuk domain yang salah, atau dipotong oleh proxy yang tidak meneruskan Set-Cookie.

Periksa dengan browser developer tools: apakah cookie authelia_session ter-set, di domain apa, dan apakah ikut terkirim pada request verify. Kalau cookie hilang di tengah jalan, masalahnya ada di header yang di-strip proxy.

#Masalah 3: Masalah Sesi

Sesi berperilaku aneh — login ulang terus, atau berhenti total. Periksa urutan ini:

• Redis tidak tersambung. Authelia gagal baca/tulis sesi. Cek log untuk redis connection error, lalu verifikasi redis-cli ping dari sisi Authelia.
• Session secret berubah. Semua sesi yang ada menjadi tidak bisa didekripsi — login ulang massal. Kalau ini terjadi tanpa rotasi terencana, periksa siapa yang mengubah secret.
• Expiration terlalu pendek. session.expiration dan session.inactivity yang agresif membuat sesi mati terlalu cepat. Cocokkan dengan harapan pengguna dan kebijakan keamanan.

#Masalah 4: Masalah Database

Authelia gagal menyimpan atau membaca data MFA. Log menunjukkan error koneksi atau error enkripsi:

• Koneksi ditolak. Cek host, port, username, dan password di blok storage. Verifikasi langsung dengan psql -U authelia -h postgres -d authelia -c 'SELECT 1'.
• Kunci enkripsi salah. Error storage encryption key saat membaca data berarti storage.encryption_key berbeda dengan saat data ditulis. Ini selalu berujung pada rotasi yang tidak disengaja — restore secret dari backup (episode 27).

#Masalah 5: TOTP Gagal

Pengguna yakin kode TOTP-nya benar, tapi selalu ditolak. TOTP adalah fungsi waktu — kode hanya valid dalam jendela 30 detik yang dihitung dari jam server. Selisih jam antara server Authelia dan perangkat pengguna, atau jam server yang melenceng sendiri, menyebabkan kode selalu salah.

Authelia memeriksa waktu lewat NTP bawaan. Pastikan server sehat secara waktu:

timedatectl status
chronyc tracking

Selain itu, perhatikan totp.skew di konfigurasi — berapa jendela waktu (default 1) yang ditoleransi. Naikkan sedikit saat transisi perangkat, tapi jangan terlalu longgar; itu melemahkan jaminan keamanan TOTP yang dibangun di episode 9.

#Masalah 6: Cookie Domain Mismatch

Cookie sesi hanya dikirim untuk domain yang cocok. Jika Authelia di auth.example.com tetapi cookie di-set untuk domain example.com atau sebaliknya, sesi tidak pernah tiba. Konfigurasi sesi multi-domain di Authelia modern didefinisikan di blok cookies — setiap entri punya domain dan authelia_url sendiri. Pastikan keduanya konsisten dengan cara proxy mengarahkan request.

#Validasi Konfigurasi dan Health Check

Dua alat yang menyelesaikan setengah masalah sebelum menyentuh runtime. Pertama, validasi konfigurasi — Authelia menolak konfigurasi yang tidak valid sejak awal, jadi error syntax ketahuan lebih dulu:

authelia validate-config --config /config/configuration.yml

Kedua, uji keputusan access control secara logis — lebih cepat daripada me-reload browser:

authelia access-control check-policy \
  --config /config/configuration.yml \
  --user arman \
  --url https://app.example.com

Perintah ini menjawab pertanyaan "apa kebijakan yang diterima user ini untuk URL ini?" — alat debugging terbaik untuk aturan yang membingungkan dari episode 6.

#Membaca Log: Detektif Authelia

Saat masalah berhasil lewat dari validasi, log adalah saksi utama. Naikkan level ke debug untuk melihat alur keputusan otorisasi, lalu amati pesan per langkah. Pertanyaan kunci yang dijawab log:

• Apakah request verify diterima? (metode, path, header)
• Apakah sesi ditemukan? Apakah cookie valid dan tidak kedaluwarsa?
• Keputusan apa yang diambil untuk URL yang diminta? (bypass, one_factor, two_factor, deny)

Satu pola yang sering menyesatkan: error di log level error pada request verify biasanya adalah respons yang diharapkan untuk user yang belum login — verify mengembalikan 401/302 dan itu normal. Jangan baca log tanpa memahami alur; baca log sambil melihat respons HTTP yang sebenarnya.

#Penutup

Episode 29 membekali kalian keterampilan detektif: memetakan enam masalah paling umum — 503 dari proxy, redirect loop, sesi, database, TOTP yang bergantung sinkronisasi waktu, dan cookie domain mismatch — lalu menangani masing-masing dari akar, memvalidasi konfigurasi dengan authelia validate-config, menguji aturan dengan authelia access-control check-policy, dan membaca log debug tanpa salah tafsir.

Poin kunci:

• Petakan gejala ke rantai: browser → proxy → verify → Redis → database.
• 503 di proxy = periksa network, health, endpoint, timeout — dalam urutan itu.
• Redirect loop = sesi tidak dibagikan atau cookie tidak sampai.
• TOTP gagal = cek jam server dan NTP sebelum mencurigai perangkat pengguna.
• Log debug + check-policy adalah pasangan debugging terbaik.

Semua keterampilan sudah dimiliki. Episode 30 — episode terakhir — merangkum semuanya dalam Production Checklist & Best Practices: daftar periksa pra-produksi, praktik terbaik keamanan dan operasional, jebakan umum, rekap perjalanan, dan masa depan Authelia. Sampai jumpa di episode 30!