> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# OIDC 身分驗證

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

OIDC 登入由每個 Ayakaleaf Pro pod 內的 **web** 服務（`authentication` 模組）處理。它沒有背景工作，也沒有獨立的 pod。提供者端（用戶端、重新導向 URI、管理員 claim）與 Toolkit 上相同，因此請先依照 [OIDC 身分驗證](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md)設定您的 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` |

請依照[使用探索文件找出設定值](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md#finding-the-values-with-the-discovery-document)中的說明，在 OP 的探索文件中找出這五個 URL。

**2. 將設定加入 ConfigMap**

加入 `overleaf-env`（`30-config.yaml`，若為[多個副本](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/kubernetes/horizontal-scaling.md)則為 `60-config.yaml`）：

```yaml title="30-config.yaml (additions)" wrap theme={null}
  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_*` 設定請參閱[環境變數](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/overleaf-toolkit/authentication/oidc-authentication.md#environment-variables)；除了用戶端密鑰以外，全部都放入 ConfigMap。

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

**3. 將用戶端密鑰放入 Secret**

```bash theme={null}
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`（請參閱[憑證與其他檔案](https://ayakaleaf-pro.mintlify.site/zh-TW/on-premises/configuration/kubernetes#憑證與其他檔案)），並讓 Node.js 指向它：

```yaml theme={null}
  NODE_EXTRA_CA_CERTS: /var/lib/overleaf/certs/ca.pem
```

**5. 套用並重新啟動**

```bash theme={null}
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 問題只會在這裡顯現：

```bash theme={null}
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 搭配公開存取。

### 問與答

> [accordion] 登入失敗並顯示「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` 中。

> [accordion] 在哪裡可以看到登入失敗的原因？
>
> \*\*回答：\*\*在處理該請求之 pod 的 web 日誌中，而不是在 `kubectl logs` 中：
>
> ```bash theme={null}
> kubectl -n overleaf exec deploy/overleaf -- grep -i oidc /var/log/overleaf/web.log | tail
> ```
>
> 若有多個副本，請逐一檢查每個 `overleaf-N`。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.