Authentik 自架 SSO：Docker Compose 與 Traefik 設定

每個自架應用程式使用同一組登入

Authentik 是自架的 SSO（單一登入）伺服器：使用者只需登入一次，後方的所有應用程式都會接受這個工作階段，不必各自要求密碼。安裝方式是使用官方 Docker Compose 檔案，並產生 2 組 secret。真正需要仔細規劃的是後續設定：將反向代理指向 Authentik，並將一個現有應用程式置於 forward auth 保護之後。

Authentik 在該 Compose 檔案中以 3 個服務執行：PostgreSQL 資料庫、server 程序，以及 worker 程序。伺服器容器也會執行內嵌 outpost；這個元件會針對每個受保護的應用程式回答「此請求是否已登入？」。截至 July 2026，Version 2026.5 是目前的版本；該專案要求主機至少具備 2 個 CPU 核心與 2 GB RAM。請將此規格視為最低需求。主機運作一天後，PostgreSQL 與 worker 都會持續占用記憶體。

開始前的準備

你需要安裝 Docker Engine 與 Compose v2 plugin，可使用 docker compose version 確認。若該指令輸出錯誤而不是版本資訊，請先安裝 plugin，再繼續後續步驟；基本操作請參閱 在 VPS 上使用 Docker Compose 執行應用程式。你也需要一筆指向該伺服器的 DNS A 記錄，以下範例中的 auth.example.com 即為此記錄，因為 Authentik 會根據瀏覽器使用的主機名稱建立重新導向 URL。

請以一般使用者執行此 stack，並將該使用者加入 docker 群組，不要以 root 執行。該群組的權限等同於主機上的 root，因此只應授予一個部署帳號，不要授予其他人；相關做法可參閱 VPS 上的最小權限使用者帳號。

使用官方 Compose 檔案安裝

sudo install -d -o "$USER" -g "$USER" /opt/authentik
cd /opt/authentik
wget https://docs.goauthentik.io/compose.yml
echo "PG_PASS=$(openssl rand -base64 36 | tr -d '\n')" >> .env
echo "AUTHENTIK_SECRET_KEY=$(openssl rand -base64 60 | tr -d '\n')" >> .env
docker compose pull
docker compose up -d

docker compose ps 應列出 3 個容器，其中 postgresql 應回報 healthy，server 應回報 worker 和 running。首次啟動時會執行資料庫遷移，因此請等待 1 分鐘，讓網頁介面完成回應。

這 2 個產生的值都很重要，但原因不同。PG_PASS 是 PostgreSQL 密碼，長度上限為 99 個字元。AUTHENTIK_SECRET_KEY 用於簽署工作階段和 token，因此之後若變更此值，所有使用者都會被登出，且已發行的 API token 也會全部失效。將 .env 的權限維持為 mode 600，並在安全位置保留一份副本，因為還原的資料庫若沒有相符的 secret key，就沒有人能登入該資料庫。

Compose 檔案會使用 ${PG_PASS:?database password required} 形式讀取這 2 個值；如果檔案不存在，Compose 就會拒絕啟動。從錯誤的目錄執行 docker compose up -d 時，會顯示 required variable AUTHENTIK_SECRET_KEY is missing a value: secret key required 並停止。這是路徑問題，不是設定問題。

重要的環境變數

其他設定都放在同一個 .env 檔案中。Authentik 會將兩個底線對應至巢狀設定鍵，因此 AUTHENTIK_EMAIL__HOST 會設定 email.host。單一底線會遭到忽略，且不會顯示警告。這是設定看似沒有作用的最常見原因。

• AUTHENTIK_BOOTSTRAP_PASSWORD 會在首次啟動時設定內建 akadmin 使用者的密碼，因此不必在公開 Web 表單中輸入密碼。AUTHENTIK_BOOTSTRAP_EMAIL 和 AUTHENTIK_BOOTSTRAP_TOKEN 會以相同方式設定該使用者的地址與 API token。
• COMPOSE_PORT_HTTP 和 COMPOSE_PORT_HTTPS 會將對外發布的埠移離預設的 9000 和 9443。
• AUTHENTIK_EMAIL__HOST、AUTHENTIK_EMAIL__PORT、AUTHENTIK_EMAIL__USERNAME、AUTHENTIK_EMAIL__PASSWORD、AUTHENTIK_EMAIL__USE_TLS 和 AUTHENTIK_EMAIL__FROM 會設定對外寄信功能。未設定這些值時，Authentik 會嘗試透過埠 25 連線至 localhost，因此密碼重設郵件會在 worker log 中以連線錯誤結束。
• AUTHENTIK_LOG_LEVEL=debug 會在登入流程異常時啟用所需的詳細資訊。完成後請恢復為 info。
• AUTHENTIK_ERROR_REPORTING__ENABLED 預設為 false。只有在你願意將當機報告傳送給上游時，才將其設為 true。

這些是儲存在純文字檔案中的 secret，因此應以管理其他認證資料存放區的方式管理該目錄。復原副本最好存放在 自架的 Vaultwarden 實例等密碼管理工具中，而不是記在筆記型電腦的備忘錄裡。

首次登入與管理員帳戶

在瀏覽器中開啟 http://SERVER_IP:9000。Authentik 會顯示初始設定流程，並要求你為預設的 akadmin 使用者設定密碼。如果你已經設定 AUTHENTIK_BOOTSTRAP_PASSWORD，則可略過此步驟，直接進入登入頁面。

在 Directory，接著進入 Users，建立一般管理員帳號，將其加入 authentik Admins 群組，然後使用該帳號登入。將 akadmin 保留為緊急備援帳號，並把長密碼離線保存。日常工作若使用共用的內建帳號，稽核日誌就會失去作用，因為每個事件都只顯示 akadmin，無法得知實際操作者。這項原則同樣適用於 Authentik 下游的服務：例如 可讓每個人擁有自己代理程式的自架 OneCLI 工具，只有在傳入的身分屬於單一使用者，而不是整個團隊共用的登入帳號時，才能留下可讀取的追蹤紀錄。

讓 Authentik 位於反向代理後方

將連接埠 9000 發布至網際網路可以運作，但您需要 TLS（transport layer security）與正式主機名稱。如果您已經依照使用 Traefik 作為多個 Compose 應用程式的反向代理完成設定，請使用 override 檔案，將 Authentik 加入相同的外部 proxy network。在 compose.yml 旁建立 docker-compose.override.yml：

services:
  server:
    networks:
      - default
      - proxy
    labels:
      traefik.enable: "true"
      traefik.docker.network: proxy
      traefik.http.routers.authentik.rule: Host(`auth.example.com`)
      traefik.http.routers.authentik.entrypoints: websecure
      traefik.http.routers.authentik.tls.certresolver: le
      traefik.http.services.authentik.loadbalancer.server.port: "9000"

networks:
  proxy:
    external: true

使用 docker compose up -d 套用。Compose 會自動合併 override，因此 server service 會保留官方檔案中的所有設定，並加入這些 labels。使用 curl -I https://auth.example.com/if/user/ 檢查，應會回應 HTTP/2 200。如果 Traefik 回傳 404 page not found，表示 container 不在 proxy network 上；Traefik 無法將流量路由到無法連線的 container。

主機名稱可正常運作後，請在 override 中將發布的連接埠繫結至 127.0.0.1，讓流量只能經由 proxy 進入。

使用 forward auth 保護單一應用程式

Authentik 的 proxy provider 有 3 種模式，選錯模式可能浪費 1 小時。Proxy 表示由 outpost 本身將流量轉送到上游應用程式。Forward auth (single application) 表示仍由你自己的反向代理轉送流量，並只向 Authentik 確認請求是否已完成登入。Forward auth (domain level) 則會使用單一 provider 保護同一父網域下的所有應用程式，但代價是無法套用個別應用程式的授權規則。若前方使用 Traefik，應選擇 forward auth (single application)。如果需要實際應用程式來練習，可以先使用 自架的 AFFiNE 工作區。這類內部工具通常只需要讓自己的裝置存取，不應對其他來源開放。團隊工具更能凸顯這種做法的價值：將 自架的 Chatwoot 客服台 放在同一個 provider 後方，所有處理收件匣的人員每天只需登入一次，不必再共用另一組密碼。

在 Web 介面中，開啟 Applications，接著開啟 Providers，建立 Proxy Provider，選擇 forward auth single application 模式，並將外部主機設定為 https://app.example.com。建立一個指向該 provider 的 Application。接著開啟 Outposts，編輯 authentik Embedded Outpost，再將新的 application 移入其 selected applications。outpost 只會處理已指派給它的應用程式，因此若略過最後這個步驟，即使 provider 設定正確，也不會回應任何內容。

在 Authentik container 上定義一次 middleware，之後讓所有受保護的應用程式引用它：

      traefik.http.middlewares.authentik.forwardauth.address: http://server:9000/outpost.goauthentik.io/auth/traefik
      traefik.http.middlewares.authentik.forwardauth.trustForwardHeader: "true"
      traefik.http.middlewares.authentik.forwardauth.authResponseHeaders: X-authentik-username,X-authentik-groups,X-authentik-email,X-authentik-name,X-authentik-uid,X-authentik-jwt,X-authentik-meta-jwks,X-authentik-meta-outpost,X-authentik-meta-provider,X-authentik-meta-app,X-authentik-meta-version

authResponseHeaders 是 Traefik 從 Authentik 的回應中複製到上游請求的標頭清單。若省略這項設定，應用程式仍會受到保護，但無法得知使用者身分。因此，任何讀取 X-authentik-username 來自動登入的功能都會維持未登入狀態。

受保護的應用程式本身需要 2 個 router，而不是 1 個：

    labels:
      traefik.enable: "true"
      traefik.http.routers.myapp.rule: Host(`app.example.com`)
      traefik.http.routers.myapp.entrypoints: websecure
      traefik.http.routers.myapp.tls.certresolver: le
      traefik.http.routers.myapp.middlewares: authentik@docker
      traefik.http.routers.myapp-auth.rule: Host(`app.example.com`) && PathPrefix(`/outpost.goauthentik.io/`)
      traefik.http.routers.myapp-auth.entrypoints: websecure
      traefik.http.routers.myapp-auth.tls.certresolver: le
      traefik.http.routers.myapp-auth.priority: "15"
      traefik.http.routers.myapp-auth.service: authentik

第二個 router 是最常被遺漏的部分。登入後，Authentik 會將瀏覽器導回 應用程式主機名稱下 /outpost.goauthentik.io/ 的路徑，而不是 auth.example.com。若沒有 router 將這個路徑前綴轉送至 Authentik service，請求就會抵達你的應用程式並回傳 404，登入流程也無法完成。較高的 priority 會讓這個特定路徑規則優先於相同網域上的一般 Host() 規則。

使用私密瀏覽器視窗進行測試。你應會被導向 auth.example.com，登入後再返回應用程式。Authentik 端的 docker compose logs -f server 會為每次嘗試列出一筆授權事件，藉此確認請求是否確實抵達 Authentik。

實際會遇到的故障

應用程式與登入頁面之間不斷重新導向。 Provider 上的外部主機名稱與瀏覽器使用的主機名稱不一致，通常是 Provider 中的 http:// 與網址列中的 https:// 不同。接著，工作階段 cookie 會設定在不同的來源，因此每次返回時都會被視為新的匿名請求。修正外部主機名稱，並清除兩個網域的 cookie，再重新測試。

/outpost.goauthentik.io/start 回傳 404。 缺少 outpost router，或其優先順序低於該主機的 catch-all router。

應用程式載入，但完全沒有要求登入。 middlewares 標籤指向不存在的 middleware。Traefik 不會針對此情況發出警告，因此 authentik@docker 的拼字錯誤只會導致沒有 middleware 執行。開啟 Traefik dashboard，確認 router 清單中已列出該 middleware。

成功登入後 Authentik 回傳 403。 使用者已完成驗證，但未獲授權：應用程式設定了此使用者不符合的 policy binding 或群組要求。管理介面的 Events log 會指出拒絕存取的 policy。

Keycloak 更適合的情況

Keycloak 是較早期的專案，由 Red Hat 支援。對於傳統企業身分識別工作，它通常是更強的選擇，包括大量 SAML federation、同時代理來自多個外部身分識別提供者的登入，以及將 realm 匯出與匯入作為有文件記載的遷移途徑。對部分組織而言，背後具備商業支援也是紙面上的重要考量。代價是 Keycloak 沒有內建 proxy，因此若要保護不支援 OIDC (OpenID Connect) 的應用程式，就必須搭配執行類似 oauth2-proxy 的元件。Authentik 內建的 proxy provider 已整合這項功能，這也是多數同時維護多種應用程式的自架服務使用者最後選擇 Authentik 的原因。

備份與升級

還原需要 3 項內容：PostgreSQL 資料庫、./data 目錄，以及 .env。

cd /opt/authentik
docker compose exec -T postgresql pg_dump -U authentik authentik | gzip > authentik-$(date +%F).sql.gz

將該傾印檔與 .env 一起保存。只有傾印檔並不足夠，因為保護工作階段與 token 資料的密鑰位於 .env。

升級只需變更標籤。在 .env 中將 AUTHENTIK_TAG 設為所需的版本，然後執行 docker compose pull，再執行 docker compose up -d。請先閱讀版本說明，因為 Authentik 使用以日期為基礎的版本，而且部分版本包含要求從前一個版本升級的 migration。請在 pull 前建立資料庫傾印，不要在 pull 後才建立。

FAQ

Authentik 可免費自架嗎？

開放原始碼版本免費，涵蓋上述所有功能：proxy provider、forward auth、OIDC (OpenID Connect)、SAML 及 flows engine。付費企業版提供支援與部分企業功能，但本教學中的內容都不需要授權。

使用 Authentik 一定需要 Traefik 嗎？

不需要。透過 auth_request，forward auth 可與 nginx 搭配使用；透過 forward_auth，也可與 Caddy 搭配使用。每種情況的模式都相同：反向代理會針對每個請求詢問 Authentik，而受保護主機名稱上的路徑前綴 /outpost.goauthentik.io/ 必須路由至 Authentik，而不是應用程式。

為什麼受保護的應用程式會在登入與錯誤頁面之間無限跳轉？

proxy provider 中設定的外部主機名稱，與瀏覽器使用的 URL 不一致，最常見的是 http 與 https 不同。工作階段 cookie 是針對其中一個來源簽發，卻在另一個來源讀取，因此 Authentik 每次都會將請求視為匿名請求。修正外部主機名稱，然後清除這兩個主機名稱的 cookie，再重新測試。

Authentik 需要多少 RAM？

截至 July 2026，文件列出的最低需求是 2 個 CPU 核心與 2 GB RAM，涵蓋 PostgreSQL、server 與 worker。使用 2 GB RAM 的主機在記憶體壓力下，worker 會是核心最先終止的程序；症狀是背景工作與外寄電子郵件停止，但登入頁面仍可正常運作。如果同一台伺服器也執行受保護的應用程式，請配置 4 GB RAM。