Authelia

💡 快速導航

• 🎯 我為什麼用它
• 🧱 在 Home Lab 裡的角色
• 🔁 NPM Forward Auth 流程
• 👤 認證後端與使用者資料
• 🛡️ Access Control 模型
• 🔐 2FA、Session 與 OIDC
• 💾 MariaDB 與備份還原
• ⚠️ 維運原則與安全邊界
• Home Lab 總覽

Authelia 是我 Home Lab 的身份驗證與存取控制層。它通常不是直接面對使用者的應用，而是站在 Nginx Proxy Manager 後面，替敏感服務加上一層集中式登入、2FA 和 access policy。

NPM 負責「流量入口與反向代理」，Authelia 負責「這個 request 是否應該被允許進去」。這兩者搭在一起，才讓對外服務不只是有 HTTPS，而是有更清楚的身份與權限邊界。

Important

這篇是公開筆記，所以不會放任何實際 domain、內網 IP、使用者名稱、email、群組、密碼 hash、session secret、JWT secret、OIDC key、SMTP 帳號或 access-control 規則全文。

---

🎯 我為什麼用它

不是每個服務都值得直接暴露登入頁

很多自架服務都有自己的登入頁，但這不代表它們都適合直接暴露到外部網路。服務越多，登入方式、2FA 支援、密碼策略和安全更新品質就越不一致。

Authelia 的價值是把第一道入口收斂：

• 敏感服務先經過集中式登入
• 需要時要求 2FA
• 不同服務可以套不同 access policy
• 後端服務不需要各自重新實作同一套前置保護

讓 NPM 不只是轉發流量

單純的 reverse proxy 只回答「這個網域要轉去哪裡」。加上 Authelia 後，入口層還可以回答「這個人是否可以進去」。

這對管理後台、內部 dashboard、文件系統、監控頁面和其他敏感服務特別重要。

---

🧱 在 Home Lab 裡的角色

flowchart TD
    U[使用者 / 瀏覽器] --> NPM[Nginx Proxy Manager]
    NPM --> AUTH[Authelia]
    AUTH --> USERS[(Local Users)]
    AUTH --> DB[(MariaDB Storage)]
    NPM --> APP[Protected Services]
    APP --> DATA[(Service Data)]

Authelia 位在入口安全層，不直接取代後端服務自己的帳號權限。它比較像門口的保全：先確認身份與條件，再把符合規則的 request 放行到後端。

部署摘要

項目	目前做法
部署方式	Docker Compose
Image	authelia/authelia:latest
Restart policy	unless-stopped
設定目錄	bind mount 到 /config
Active config	/config/configuration.yml
認證後端	File-based local users
密碼雜湊	Argon2id
Storage backend	MariaDB / MySQL
Notifier	SMTP
2FA	TOTP 已設定
OIDC	Identity provider 設定存在

Note

目前 image 使用 latest。這對快速更新很方便，但不利於可重現還原。長期更穩的做法是改用明確版本 tag，搭配升級前備份與回滾紀錄。

---

🔁 NPM Forward Auth 流程

Authelia 在我的架構中主要透過 NPM 的 forward-auth / auth_request 模式使用。

sequenceDiagram
    participant User as User
    participant NPM as NPM
    participant Auth as Authelia
    participant App as Backend Service

    User->>NPM: Request protected URL
    NPM->>Auth: Check authentication and policy
    Auth-->>NPM: Allow or deny
    NPM->>App: Proxy request if allowed
    App-->>User: Response through NPM

目前有多個 NPM proxy host 使用 Authelia 保護。這些服務在真正進入後端前，會先經過 Authelia 判斷是否已登入、是否需要 2FA，以及是否符合 access policy。

分工

元件	負責內容
NPM	domain、TLS、proxy host、header、WebSocket、upstream
Authelia	登入、2FA、session、access-control decision、OIDC
Backend service	自己的使用者權限、應用內授權、資料安全

NPM 也會把通過驗證後的身份資訊以 header 形式傳給後端服務。公開筆記只記錄這個模式，不列出實際 header snippet 或受保護 domain。

---

👤 認證後端與使用者資料

目前 Authelia 使用 file-based local user database。這對小型家庭環境足夠直覺，也比一開始就導入 LDAP 更容易維護。

使用者資料庫包含敏感內容，公開筆記不會列出：

• username
• display name
• email
• group membership
• password hash
• TOTP / recovery 相關資料

我會公開記錄的只有原則

• 使用者資料庫必須備份
• password hash 不等於可以公開
• 2FA 註冊與備援碼要有私有保存流程
• 家人加入前，要先確認還原流程與帳號恢復方式

---

🛡️ Access Control 模型

Authelia 的 access-control 是整套系統最敏感的部分之一，因此公開筆記只描述模型，不列出實際規則。

目前配置具備：

• default policy 為 deny
• auth portal 本身有必要的 bypass 規則
• 部分服務套用 two-factor 保護
• 不同服務可以依 domain / user / group / network 條件套用不同政策

我的原則

1. Default deny：沒有明確允許的入口，不應該被放行。
2. 敏感服務使用 2FA：尤其是管理後台、密碼庫、內部 dashboard。
3. 不要只依賴外層保護：後端服務仍要保留自己的登入與權限。
4. 規則改動要小步驗證：access-control 改錯可能會把自己鎖在外面，也可能意外放寬入口。

---

🔐 2FA、Session 與 OIDC

TOTP

目前 Authelia 已設定 TOTP。這是我最常用的第二因素，適合保護不該只靠密碼進入的服務。

我不會在公開筆記放：

• issuer / domain
• 使用者 2FA 狀態
• TOTP secret
• recovery code

Session / Cookie

Session 與 cookie 設定會牽涉 root domain、auth portal URL、cookie domain 和 session secret。這些都是公開筆記中必須隱藏的內容。

公開可記錄的原則是：Authelia、NPM 和各服務 domain 之間的 cookie 邊界要一致，否則很容易出現登入後又被導回登入頁、跨子網域 session 失效等問題。

OIDC

目前配置中存在 OIDC identity-provider 設定。這代表 Authelia 不只可以做 forward-auth，也可以成為支援 OIDC 的服務登入來源。

OIDC 的 client id、client secret、private key、redirect URI 和實際 client 清單都不應公開。

---

💾 MariaDB 與備份還原

Authelia 的 storage backend 使用 MariaDB / MySQL。這代表備份不能只備份 /config 目錄。

需要保護的內容

類型	說明
/config 設定	configuration.yml、users database、備份參考設定
MariaDB 狀態	Authelia storage backend 的持久化資料
Secrets	storage encryption key、session/JWT/reset/OIDC 相關 secret
NPM 設定	forward-auth snippets 與 proxy host 設定也影響保護是否生效

還原後檢查

1. Authelia container 是否啟動
2. MariaDB storage 是否可連線
3. 登入流程是否正常
4. TOTP 是否正常
5. NPM forward-auth 是否仍保護預期服務
6. OIDC client 是否仍可登入
7. 被保護服務是否仍保留自己的權限控制

Warning

如果遺失 storage encryption key、OIDC key 或 session/JWT 相關 secret，即使資料庫還在，也可能導致登入狀態、OIDC 或部分加密資料無法正確恢復。

---

⚠️ 維運原則與安全邊界

不要把 Authelia 當萬能盾

Authelia 是入口保護，不是後端服務的替代安全模型。後端服務仍要：

• 使用強密碼或自己的 2FA
• 定期更新
• 關閉不需要的註冊或公開功能
• 限制管理員權限
• 保留備份與還原流程

更新要先保護自己不要鎖死

修改 access-control、session、cookie、OIDC 或 forward-auth 設定前，我會先保留可回滾版本。這類錯誤不一定會讓 container 掛掉，但可能讓登入流程壞掉。

公開筆記只放模型，不放配置全文

Authelia 的 configuration.yml 和 users database 都不適合公開。即使把密碼遮掉，也很容易留下 domain、policy、header、group、email 或其他可被利用的資訊。

---

結論

Authelia 讓我的 Home Lab 入口層從「有反向代理與 HTTPS」進一步變成「有集中式身份驗證與存取控制」。它和 Nginx Proxy Manager 的分工很清楚：NPM 管入口與路由，Authelia 管身份與規則。

但 Authelia 也屬於非常敏感的基礎設施。公開分享時，最重要的不是展示完整設定，而是記錄架構原則、備份範圍、還原檢查和安全邊界。

延伸閱讀：Home Lab 總覽、Nginx Proxy Manager、OpenMediaVault