Belajar Authelia - Struktur File Konfigurasi

#Pendahuluan

Di episode 3 kalian sudah menjalankan Authelia dengan konfigurasi minimal. Sekarang saatnya memahami otak Authelia: configuration.yml. Ini adalah file yang menentukan segalanya — dan karena YAML peka indentasi, kesalahan kecil berujung pada perilaku yang salah atau server yang menolak start. Di episode ini kita membedah setiap bagiannya: dari identitas server (theme, secret, URL default) hingga kebijakan (access control, session, regulation), penyimpanan (storage), notifikasi (notifier), dan sumber pengguna (authentication backend). Kita juga akan mempelajari cara memvalidasi konfigurasi sebelum menjalankannya — keterampilan yang akan menyelamatkan kalian berkali-kali di sisa series ini.

#Anatomi configuration.yml

File konfigurasi Authelia terdiri dari bagian-bagian berikut, masing-masing dengan tanggung jawab yang jelas:

#Server, Theme, dan Identitas

host: 0.0.0.0
port: 9091
log_level: info
 
theme: auto
jwt_secret: dari-environment-variable
default_redirection_url: https://auth.example.com

• host: 0.0.0.0 membuat server menerima koneksi dari antarmuka mana pun (wajib untuk kontainer); theme: auto mengikuti preferensi OS pengunjung portal — ringan tapi profesional.
• jwt_secret dipakai untuk menandatangani token verifikasi — jangan hardcode, injeksi lewat environment (lihat di bawah). default_redirection_url adalah "rumah" pengguna setelah login; arahkan ke portal atau halaman utama yang aman.

#Access Control

Bagian paling penting dan paling sering salah. Aturan dievaluasi dari atas ke bawah, yang cocok pertama menang:

access_control:
  default_policy: deny
  rules:
    - domain: "public.example.com"
      policy: bypass
    - domain: "*.example.com"
      policy: two_factor
      subject:
        - "group:admins"

default_policy: deny memastikan apa pun yang tidak tercantum ditolak. Rule pertama mengizinkan public.example.com tanpa login; rule kedua mensyaratkan dua faktor bagi grup admins di semua subdomain. Episode 6 membahas access control secara mendalam.

#Session

Mengatur cookie dan session storage:

session:
  name: authelia_session
  domain: example.com
  expiration: 1h
  inactivity: 5m
  remember_me_duration: 1M
  redis:
    host: redis
    port: 6379
    password: dari-environment-variable

Cookie dibatasi ke domain example.com (agar berlaku untuk semua subdomain), kadaluarsa setelah 1 jam, dan bisa "diingat" hingga 1 bulan. inactivity: 5m memaksa logout otomatis setelah 5 menit tanpa aktivitas — fitur keamanan yang sering diremehkan.

#Regulation (Proteksi Brute Force)

regulation:
  max_retries: 5
  find_time: 2m
  ban_time: 5m

Artinya: setelah 5 percobaan login gagal dalam 2 menit, pengguna/IP diblokir selama 5 menit. Ini perisai pertama melawan serangan tebak-password. Episode 21 membahas penalaannya.

#Storage dan Notifier

storage:
  local:
    path: /config/db.sqlite3
 
notifier:
  filesystem:
    filename: /config/notifications.txt

Storage menyimpan secret TOTP dan kredensial WebAuthn — data yang tidak boleh hilang (backup penting, episode 27). Notifier filesystem cukup untuk lab; produksi memakai SMTP.

#Authentication Backend, Identity Validation, TOTP, WebAuthn

authentication_backend:
  file:
    path: /config/users_database.yml
 
identity_validation:
  reset_password:
    jwt_secret: dari-environment-variable
 
totp:
  issuer: Authelia
 
webauthn:
  display_name: Authelia

authentication_backend menentukan sumber akun pengguna (episode 5). identity_validation.reset_password.jwt_secret dipakai untuk token reset password — juga wajib di-inject lewat environment. totp dan webauthn menyesuaikan nama issuer yang tampil saat pengguna memindai QR code.

#Validasi Konfigurasi

Sebelum me-restart stack setelah mengubah config, selalu validasi dulu. Authelia menyediakan perintah authelia validate-config:

docker run --rm -v $(pwd)/config:/config authelia/authelia:latest \
  authelia validate-config --config /config/configuration.yml

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

Jika ada kesalahan, Authelia melaporkan nomor baris dan deskripsi masalahnya — baca itu sebelum menebak. Validasi ini tidak butuh server berjalan, jadi aman dijalankan kapan saja. Perhatikan: authelia validate-config membutuhkan semua secret yang diperlukan; jika dilewati, ia akan error sebelum memvalidasi isi file — ini sebabnya injeksi environment penting bahkan saat validasi.

#Secret Management via Environment Variables

Authelia mendukung override konfigurasi penuh lewat environment variables. Setiap key di configuration.yml punya padanan env var: huruf kecil diganti garis bawah dan diawali AUTHELIA_. Contoh:

Pola ini membuat file configuration.yml bebas dari secret — ia bisa di-version-control dengan aman, sementara nilai rahasia hidup di .env, environment sistem, atau secret manager (pola yang sudah kalian lihat berjalan di episode 3).

#Pitfalls Umum

1. Indentasi YAML salah. Satu spasi yang meleset bisa mengubah struktur. Gunakan editor dengan syntax highlighting YAML.
2. Lupa secret yang wajib. Authelia menolak start/validasi. Cek daftar secret lengkap di log.
3. Default policy terlalu longgar atau domain session tidak konsisten. Memakai default_policy: bypass "biar mudah" membuka seluruh lab tanpa login; sedangkan session.domain yang berbeda dari domain portal membuat cookie tidak terkirim dan login "mengambang".
4. Mengubah config tanpa validasi. Satu kesalahan → kontainer restart-loop. Biasakan validasi dulu.

#Penutup

Pada episode 4 ini kalian telah membedah configuration.yml dari ujung ke ujung: identitas server (host, theme, jwt_secret, default_redirection_url), kebijakan (access_control, session, regulation), penyimpanan (storage), notifikasi (notifier), sumber pengguna (authentication_backend), dan konfigurasi MFA (identity_validation, totp, webauthn). Kalian juga menguasai validasi konfigurasi dengan authelia validate-config dan pola secret via environment variables berprefiks AUTHELIA_.

Poin yang harus kalian bawa:

• configuration.yml adalah satu-satunya otak Authelia — pahami setiap bagian sebelum mengubah.
• default_policy: deny dan evaluasi aturan first match wins adalah fondasi access control.
• Validasi sebelum restart: authelia validate-config mencegah loop restart yang sia-sia.
• Environment variable menimpa file config — simpan secret di .env, bukan di YAML.

Di episode 5 selanjutnya kita akan membahas bagian yang membuat Authelia benar-benar "tahu" penggunanya: authentication backends — backend file dengan users_database.yml dan password ter-hash argon2id untuk homelab, serta backend LDAP untuk organisasi dengan OpenLDAP atau Active Directory. Sampai jumpa di episode 5!