OIDC 身分驗證

在 Kubernetes 部署中，讓使用者透過 OpenID Connect 提供者登入。

OIDC 登入由每個 Ayakaleaf Pro pod 內的 web 服務（authentication 模組）處理。它沒有背景工作，也沒有獨立的 pod。提供者端（用戶端、重新導向 URI、管理員 claim）與 Toolkit 上相同，因此請先依照 OIDC 身分驗證設定您的 OpenID 提供者（OP），再依下列方式將設定值放入 Kubernetes。

​

各元件的執行位置

服務	web，位於每個 Ayakaleaf Pro pod 中；設定會在 web 啟動時讀取
Pod → OP	OVERLEAF_OIDC_TOKEN_URL 與 OVERLEAF_OIDC_USER_INFO_URL，每次登入時
瀏覽器 → OP	OVERLEAF_OIDC_AUTHORIZATION_URL，以及登出時的 OVERLEAF_OIDC_LOGOUT_URL
OP → Overleaf	無：OP 只會將瀏覽器重新導向回來
登入狀態	Redis 中的工作階段，由所有副本共用
定期工作	無

​

設定

1. 在 OP 註冊 Overleaf

   在您的 OP 中允許下列以 OVERLEAF_SITE_URL 組成的位址：

   用途	URI
   重新導向 URI（登入）	${OVERLEAF_SITE_URL}/oidc/login/callback
   登出後重新導向 URI	${OVERLEAF_SITE_URL}
   連結既有帳號後的登出後重新導向 URI	${OVERLEAF_SITE_URL}/user/settings

   請依照使用探索文件找出設定值中的說明，在 OP 的探索文件中找出這五個 URL。

2. 將設定加入 ConfigMap

   加入 overleaf-env（30-config.yaml，若為多個副本則為 60-config.yaml）：

   30-config.yaml (additions)

     EXTERNAL_AUTH: oidc
     OVERLEAF_OIDC_PROVIDER_ID: authentik
     OVERLEAF_OIDC_PROVIDER_NAME: Authentik
     OVERLEAF_OIDC_IDENTITY_SERVICE_NAME: Log in with Authentik
     OVERLEAF_OIDC_ISSUER: https://authentik.example.com/application/o/overleaf/
     OVERLEAF_OIDC_AUTHORIZATION_URL: https://authentik.example.com/application/o/authorize/
     OVERLEAF_OIDC_TOKEN_URL: https://authentik.example.com/application/o/token/
     OVERLEAF_OIDC_USER_INFO_URL: https://authentik.example.com/application/o/userinfo/
     OVERLEAF_OIDC_LOGOUT_URL: https://authentik.example.com/application/o/overleaf/end-session/
     OVERLEAF_OIDC_CLIENT_ID: <Client ID>
     OVERLEAF_OIDC_USER_ID_FIELD: username
     OVERLEAF_OIDC_IS_ADMIN_FIELD: groups
     OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE: Admins
     OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN: "true"
   

   EXTERNAL_AUTH 接受以空格分隔的清單，例如 ldap oidc。所有 OVERLEAF_OIDC_* 設定請參閱環境變數；除了用戶端密鑰以外，全部都放入 ConfigMap。

   請為 "true" 與 "false" 加上引號：ConfigMap 只能存放字串。設為 "" 的鍵與不存在的鍵並不相同：OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS: "" 會關閉首次登入時的帳號建立，而省略該鍵則允許所有網域。

3. 將用戶端密鑰放入 Secret

   kubectl -n overleaf patch secret overleaf-secrets --type merge \
     -p '{"stringData":{"OVERLEAF_OIDC_CLIENT_SECRET":"<Client Secret>"}}'
   
4. 信任私有 CA（選用）

   若 OP 的憑證由您自己的 CA 簽發，請將該 CA 加入掛載於 /var/lib/overleaf/certs 的 Secret overleaf-certs（請參閱憑證與其他檔案），並讓 Node.js 指向它：

     NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem
   
5. 套用並重新啟動

   kubectl apply -f 30-config.yaml
   kubectl -n overleaf rollout restart deployment/overleaf     # or statefulset/overleaf
   kubectl -n overleaf rollout status deployment/overleaf
   

   接著檢查每個 pod 是否都能連線至 token 端點。呼叫該端點的是 pod 而非瀏覽器，因此防火牆或 DNS 問題只會在這裡顯現：

   for p in $(kubectl -n overleaf get pod -l app=overleaf -o name); do   # app=overleaf-ha for several replicas
     kubectl -n overleaf exec "$p" -- curl -sS -o /dev/null -w "$p %{http_code}\n" \
       https://authentik.example.com/application/o/token/
   done
   

   任何 HTTP 狀態碼（GET 會得到 405）都表示端點可以連線；000 則表示無法連線。

​

多個副本

不需要額外處理。登入的 state 值以及登出時使用的 ID token 都保存在 Redis 中的工作階段裡，因此無論哪個副本收到回呼，都能正常運作。

​

在 Kubernetes 上的測試

以 goauthentik 作為 OP，在 Kubernetes 1.37 上以三個副本置於 HAProxy 之後，我們針對 OIDC 的端對端測試全數通過（35 個案例）：登入，以及透過 OP 登出；依群組、依電子郵件與依單一值對應管理員，以及不使用對應；每次登入時更新名稱與管理員旗標；連結與取消連結帳號；OIDC 帳號的密碼重設與密碼變更；已停權的帳號；OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS；OVERLEAF_DISABLE_LOCAL_LOGIN；以及 OIDC 搭配公開存取。

​

問與答

登入失敗並顯示「Unable to verify authorization request state」

回答：瀏覽器在回呼時沒有將工作階段 Cookie 送回。在 Kubernetes 上，常見原因如下：

• 已設定 OVERLEAF_SECURE_COOKIE，但使用者以一般 HTTP 開啟網站，因此瀏覽器從未儲存該 Cookie。OVERLEAF_SECURE_COOKIE 無論設為何值（即使是 "false"）都會啟用安全 Cookie；請改為移除該鍵。
• 網站是以 OVERLEAF_SITE_URL 以外的位址開啟。
• 在 HTTPS 後方，您的 ingress 或負載平衡器沒有傳送 X-Forwarded-Proto: https，或其位址未列在 OVERLEAF_TRUSTED_PROXY_IPS 中。

在哪裡可以看到登入失敗的原因？

回答：在處理該請求之 pod 的 web 日誌中，而不是在 kubectl logs 中：

kubectl -n overleaf exec deploy/overleaf -- grep -i oidc /var/log/overleaf/web.log | tail

若有多個副本，請逐一檢查每個 overleaf-N。