> ## 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、管理员声明）与 Toolkit 中相同，因此请先按照 [OIDC 身份验证](https://ayakaleaf-pro.mintlify.site/zh-CN/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-CN/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-CN/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-CN/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-CN/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 令牌都保存在位于 Redis 中的会话里，因此无论哪个副本收到回调，回调都能正常工作。

### 在 Kubernetes 上的测试

以 goauthentik 作为 OP，在 Kubernetes 1.37 上使用位于 HAProxy 之后的三个副本，我们针对 OIDC 的端到端测试全部通过（35 个用例）：登录以及通过 OP 退出登录；按组、按邮箱和按单个值映射管理员，以及不进行映射；每次登录时更新姓名和管理员标志；关联和取消关联账户；OIDC 账户的密码重置和密码更改；已停用的账户；`OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`；`OVERLEAF_DISABLE_LOCAL_LOGIN`；以及 OIDC 与公开访问同时使用。

### Q\&A

> [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.