跳转到主要内容
此功能由 yu-i-i/overleaf-cep 开发。这里我们提供一些文档,供你进行配置时参考。

配置

Overleaf OIDC 模块在内部使用 passport-openidconnect 库。如果你在配置 OpenID Connect 时遇到问题,建议阅读 passport-openidconnect 的 README,以了解它所需的配置。 启用 OIDC 认证模块需要设置环境变量 EXTERNAL_AUTH。该环境变量指定启用哪些外部认证方式,其值是一个列表。如果列表中包含 oidc,则会启用 OIDC 认证。 例如:EXTERNAL_AUTH=ldap oidc 使用 OIDC 认证方式时,用户会被重定向到身份提供商(IdP)的认证站点。如果 IdP 成功认证了该用户,系统会在 Overleaf 用户数据库中查找包含如下结构的 thirdPartyIdentifiers 字段的记录:
externalUserId 必须与 IdP 服务器返回的用户资料中的用户 ID 相匹配(参见 OVERLEAF_OIDC_USER_ID_FIELD 环境变量),并且 providerId 必须与 OIDC 提供商的 ID 相匹配(参见 OVERLEAF_OIDC_PROVIDER_ID)。 如果未找到匹配的记录,系统会在数据库中查找主邮箱地址与 IdP 用户资料中的邮箱相匹配的用户:
  • 如果找到了这样的用户,则更新其 thirdPartyIdentifiers 字段。
  • 如果没有找到匹配的用户,且未禁用 JIT 账户创建,则会使用 IdP 资料中的邮箱地址和 thirdPartyIdentifiers 创建一个新用户。
在这两种情况下,该用户都被称为已与外部 OIDC 用户”关联”。用户可以在 /user/settings 页面上取消与 OIDC 提供商的关联。

使用发现文档查找这些值

每个 OpenID 提供商(OP)都会在 <issuer>/.well-known/openid-configuration 发布一个发现文档。请从中复制这些值,而不要手动输入;只要有一个字符错误,就足以导致登录失败。
1

找到发现 URL

你的 OP 会在你为 Overleaf 创建的客户端(提供商)页面上显示它。在 Authentik 中,打开 Applications > Providers,选择该提供商,然后查找 OpenID Configuration URL 和 OpenID Configuration Issuer:

Authentik:提供商的发现 URL 和 issuer(测试实例)

该 URL 通常如下所示:
  • Keycloak:https://keycloak.example.com/realms/<realm>/.well-known/openid-configuration
  • Authentik:https://authentik.example.com/application/o/<application-slug>/.well-known/openid-configuration
2

读取这些值

在浏览器中打开该 URL,或者在 Overleaf 服务器上运行:
Authentik 的响应如下所示:
Authentik 也会在提供商页面的下方列出这些 URL:

Authentik:提供商的端点(测试实例)

3

将它们复制到 variables.env

4

检查 Overleaf 能否访问 OP

Overleaf 会从其容器内部调用 token 和 userinfo 端点,因此 OP 必须能从容器内访问,而不仅仅是从你的浏览器访问:
它应当输出 200。
请精确复制 issuer,包括末尾的斜杠。Overleaf 会将它与 ID 令牌中的 issuer 逐字符进行比较;任何差异都会导致所有 OIDC 登录失败,并出现以下错误:{"message":{"message":"ID token not issued by expected OpenID provider."}}在 Authentik 中,issuer 属于应用(.../application/o/<application-slug>/)。它不是 Authentik 服务器的地址,尽管 authorize、token 和 userinfo URL 由所有应用共享。

环境变量

以下五个必需变量的值可以通过你的 OpenID 提供商(OP)的 .well-known/openid-configuration 端点获取,参见上文。
  • OVERLEAF_OIDC_ISSUER (必需)
  • OVERLEAF_OIDC_AUTHORIZATION_URL (必需)
  • OVERLEAF_OIDC_TOKEN_URL (必需)
  • OVERLEAF_OIDC_USER_INFO_URL (必需)
  • OVERLEAF_OIDC_LOGOUT_URL (必需)
以下两个必需变量的值将由你的 OP 管理员提供
  • OVERLEAF_OIDC_CLIENT_ID (必需)
  • OVERLEAF_OIDC_CLIENT_SECRET (必需)
  • OVERLEAF_OIDC_SCOPE
    • 默认值:openid profile email
  • OVERLEAF_OIDC_PROVIDER_ID
    • OP 的任意 ID,默认为 oidc。
  • OVERLEAF_OIDC_PROVIDER_NAME
    • OP 的名称,用于 /user/settings 页面的 Linked Accounts 部分,默认为 OIDC Provider。
  • OVERLEAF_OIDC_IDENTITY_SERVICE_NAME
    • 身份服务的显示名称,用于登录页面(默认值:Log in with $OVERLEAF_OIDC_PROVIDER_NAME)。
  • OVERLEAF_OIDC_PROVIDER_DESCRIPTION
    • OP 的描述,用于 Linked Accounts 部分(默认值:Log in with $OVERLEAF_OIDC_PROVIDER_NAME)。
  • OVERLEAF_OIDC_PROVIDER_INFO_LINK
    • OP 描述中的 Learn more URL,默认:描述中不显示 Learn more 链接。
  • OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED
    • 如果用户账户未与 OP 关联,则不在 /user/settings 页面上显示该 OP,默认为 false。
  • OVERLEAF_OIDC_USER_ID_FIELD
    • Overleaf 会将该属性的值用作外部用户 ID,默认为 id。其他合理的取值还有 email 和 username(对应 OIDC 的 preferred_username 声明)。
  • OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS
    • 限制通过 OIDC 认证的用户的即时(JIT)账户创建。如果设置为以逗号分隔的域名列表,则只有当用户邮箱地址的域名与列表中的某个域名匹配时,才会创建新账户。如果域名不匹配,管理员必须使用该 OIDC 用户的邮箱地址手动创建用户账户,并设置一个强随机密码,或者最好完全不设置 hashedPassword 字段。域名可以以 *. 通配符开头,以匹配子域名。
      • 示例:允许邮箱地址形如 name@example.com 和 name@math.example.com 的用户进行 JIT 账户创建:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com
      • 示例:完全禁用 JIT 账户创建:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=
  • OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN
    • 如果设置为 true,则在登录时更新用户的 first_name 和 last_name 字段,并禁用 /user/settings 页面上的用户详细信息表单。
  • OVERLEAF_OIDC_IS_ADMIN_FIELD 和 OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE
    • 当这两个环境变量都已设置时,如果 OP 返回的用户资料包含 OVERLEAF_OIDC_IS_ADMIN_FIELD 指定的属性,且其值与 OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE 匹配,或者是包含 OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE 的数组(例如 groups 声明),登录过程会将 user.isAdmin 更新为 true,否则将 user.isAdmin 设置为 false。如果 OVERLEAF_OIDC_IS_ADMIN_FIELD 为 email,则使用属性 emails[0].value 的值进行匹配检查。
你的 OpenID 提供商的重定向 URL 为 https://my-overleaf-instance.com/oidc/login/callback。
variables.env

分步指南:goauthentik

本节介绍一套已在 goauthentik 上测试通过的配置。请将 https://overleaf.example.com 替换为你的 OVERLEAF_SITE_URL,并将 https://authentik.example.com 替换为你的 Authentik 地址。
1

创建提供商

在 Authentik 中,打开 Applications > Providers,点击 New Provider,选择 OAuth2/OpenID Provider 并点击 Next。
  • Client Type:Confidential。
  • Redirect URIs(位于 Protocol settings 下):添加 https://overleaf.example.com/oidc/login/callback,匹配模式为 Strict。
  • 现在就复制 Client ID 和 Client Secret,分别填入 OVERLEAF_OIDC_CLIENT_ID 和 OVERLEAF_OIDC_CLIENT_SECRET。

Authentik:新提供商的 Client ID 和 Client Secret

Authentik 仅在你创建提供商时显示客户端密钥。之后编辑表单中只提供 Modify,它会用一个新密钥替换原有密钥。
2

创建应用

打开 Applications > Applications,创建一个新应用,为其设置名称和 slug(例如 overleaf),并选择该提供商。slug 会成为 issuer 的一部分:https://authentik.example.com/application/o/overleaf/。
3

复制 URL

按照上文使用发现文档查找这些值填写这五个 URL。
4

映射管理员(可选)

Authentik 会以 groups 声明(一个数组)发送用户所属的组。要让 Authentik 组 Admins 的成员成为 Overleaf 的管理员:
管理员标志会在每次 OIDC 登录时更新。如果字段或值有误,所有通过 OIDC 登录的管理员都会失去管理员权限,包括在 launchpad 中创建的管理员。请先使用另一个管理员账户测试该映射。
variables.env

问答

回答:请检查以下几点:
  • 版本。在 v6.3.0 之前,Overleaf 不读取 groups 等自定义声明,因此只有 OVERLEAF_OIDC_IS_ADMIN_FIELD=email 有效。请升级到 v6.3.0 或更高版本。
  • 该声明必须出现在 UserInfo 响应中。Overleaf 从 OVERLEAF_OIDC_USER_INFO_URL 读取声明,而不是从 ID 令牌中读取。如果你的 OP 只将该声明添加到 ID 令牌中,请同时将其添加到 UserInfo,例如在 Keycloak 映射器上启用 Add to userinfo。
  • 值必须完全匹配,包括大小写,例如 Admins。
每次登录时都会重新检查管理员状态:如果声明不匹配,在管理面板中被设为管理员的用户会在下次登录时失去管理员身份。
回答:不可以。GitHub 支持 OAuth 2.0,但不支持用于用户登录的 OpenID Connect:它不会返回 Overleaf 所需的 ID 令牌,因此登录会失败并提示 ID token not present in token response。若要让用户使用 GitHub 账户登录,请使用 goauthentik 或 Keycloak 等身份提供方,将 GitHub 作为其登录来源,再通过 OIDC 将 Overleaf 连接到该提供方。
回答:可以。GitLab(包括自托管的 GitLab)是一个 OpenID Connect 提供方。在 GitLab 中,于 Applications(位于你的用户、群组或 Admin 区域设置中)下创建一个应用,并设置:
  • Redirect URI:https://my-overleaf-instance.com/oidc/login/callback
  • Scopes:openid、profile 和 email
然后按照使用发现文档查找这些值中的说明,从 https://gitlab.com/.well-known/openid-configuration(或你的 GitLab 上的相同路径)读取各个端点。对于 gitlab.com,issuer 为 https://gitlab.com,末尾不带斜杠。
回答:在重定向到 OP 之前,Overleaf 会在用户会话中存储一个随机的 state 值,并在 OP 重定向回来时进行检查。这些错误表示回调时的会话并不是发起登录的那个会话。Unable to verify authorization request state 表示浏览器在回调时没有发回会话 Cookie。请检查:
  • 用户是否通过 OVERLEAF_SITE_URL 的地址打开 Overleaf。回调始终指向 OVERLEAF_SITE_URL,因此从其他地址发起的登录会丢失会话,例如在 OVERLEAF_SITE_URL 为 https://overleaf.example.com 时从 http://192.168.1.20 发起登录。
  • 当 Overleaf 通过普通 HTTP 提供服务时,没有设置 OVERLEAF_SECURE_COOKIE。浏览器会在 HTTP 上丢弃安全 Cookie。任何值都会启用该选项(包括 false),因此请直接删除该行。
Invalid authorization request state 表示较新的登录替换了已存储的值,例如同时在两个标签页中登录,或在登录过程中使用浏览器的后退功能。请关闭其他标签页,然后从 Overleaf 登录页面重新开始登录。
最后修改于 2026年11月2日