OIDC 身份验证

在 Kubernetes 部署中，让用户通过 OpenID Connect 提供商登录。

OIDC 登录由每个 Ayakaleaf Pro Pod 中的 web 服务（authentication 模块）处理。它没有后台任务，也没有单独的 Pod。提供商端（客户端、重定向 URI、管理员声明）与 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 令牌都保存在位于 Redis 中的会话里，因此无论哪个副本收到回调，回调都能正常工作。

​

在 Kubernetes 上的测试

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

​

Q&A

登录失败并提示“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。