LDAP 身份验证

该功能由 yu-i-i/overleaf-cep 开发。这里我们提供一些文档，帮助你完成配置。

Overleaf 使用的是 passport-ldapauth 库，该库相对陈旧，无法完全保证 LDAP 兼容性。在某些 LDAP 身份提供商（例如 https://goauthentik.io/）上可能会出现登录失败的情况。因此，如果可能，建议优先使用 OAuth/SAML 方式。对于 goauthentik，请按照下文经过测试的分步指南：goauthentik进行配置。

​

什么是 LDAP

LDAP 是一种用于外部身份验证的认证协议。Overleaf Server Pro 在 Web 界面中提供了一个专用的 LDAP 登录表单，与标准认证方式相互独立。当用户提交其 LDAP 用户名和密码时，Overleaf 后端会针对所配置的 LDAP 服务器（例如 ldap://ldap:10389）验证凭据。

Server Pro 的 LDAP 示例

​

配置

在内部，Overleaf LDAP 使用 passport-ldapauth 库。大多数配置选项会被传递给用于配置 passport-ldapauth 的 server 配置对象。如果你在配置 LDAP 时遇到问题，建议阅读 passport-ldapauth 的 README，了解它所期望的配置。

启用 LDAP 身份验证模块需要设置环境变量 EXTERNAL_AUTH。该环境变量指定要激活哪些外部认证方式，其值是一个列表。如果列表中包含 ldap，则会激活 LDAP 身份验证。

例如：EXTERNAL_AUTH=ldap saml

与 Overleaf CEP 不同，在我们的 ayaka-notes 版本中，LDAP 身份验证被限定为一种纯粹的认证方式，可通过 http://your-overleaf.com/ldap/login 访问。

使用 LDAP 身份验证方式时，用户在登录表单中输入 username 和 password 后，系统会尝试：

1. 使用 OVERLEAF_LDAP_SEARCH_FILTER 定义的过滤器在 LDAP 目录中搜索 LDAP 用户并进行认证。
2. 如果认证成功，系统会在 Overleaf 用户数据库中查找主邮箱地址与已认证 LDAP 用户邮箱地址相匹配的用户：
   • 如果找到匹配的用户，则删除该用户的 hashedPassword 字段（如果存在）。这可确保该用户今后只能通过 LDAP 身份验证登录。
   • 如果未找到匹配的用户，则使用从 LDAP 服务器获取的邮箱、名字和姓氏创建一个新的 Overleaf 用户。

对于通过 LDAP 登录的用户，我们不会在 Overleaf 的 mongo 数据库中存储哈希密码（已存在的也会被删除）。

​

环境变量

• OVERLEAF_LDAP_URL （必填）
  • LDAP 服务器的 URL。
    • 示例：ldaps://ldap.example.com:636（基于 SSL 的 LDAP）
    • 示例：ldap://ldap.example.com:389（未加密，或在已配置时使用 STARTTLS）。
• OVERLEAF_LDAP_IDENTITY_SERVICE_NAME
  • LDAP 身份服务的显示名称，用于登录页面。
  • 默认为 Log in with LDAP Provider。
• OVERLEAF_LDAP_EMAIL_ATT
  • LDAP 服务器返回的邮箱属性，默认为 mail。每个 LDAP 用户必须至少有一个邮箱地址。如果提供了多个地址，则只使用第一个。
• OVERLEAF_LDAP_FIRST_NAME_ATT
  • 保存用户名字（first name）的属性名，供应用程序使用，通常为 givenName。
• OVERLEAF_LDAP_LAST_NAME_ATT
  • 保存用户姓氏（family name）的属性名，供应用程序使用，通常为 sn。
• OVERLEAF_LDAP_NAME_ATT
  • 保存用户全名的属性名，通常为 cn。如果前两个变量中任一未定义，则从该变量中提取用户的名字和/或姓氏；否则不使用该变量。
• OVERLEAF_LDAP_PLACEHOLDER
  • 登录表单的占位文本，默认为 Username。
• OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN
  • 如果设置为 true，则在登录时更新 LDAP 用户的 first_name 和 last_name 字段，并为 LDAP 用户关闭 /user/settings 页面上的用户详情表单。否则，仅在首次登录时获取用户详情。
• OVERLEAF_LDAP_BIND_DN
  • 用于 LDAP 连接的 LDAP 用户的可分辨名称（DN）（该用户应能够在 LDAP 服务器上搜索/列出账户），例如 cn=ldap_reader,dc=example,dc=com。如果未定义，则使用匿名绑定。
• OVERLEAF_LDAP_BIND_CREDENTIALS
  • OVERLEAF_LDAP_BIND_DN 的密码。
• OVERLEAF_LDAP_BIND_PROPERTY
  • 用于与客户端绑定的用户属性，默认为 dn。
• OVERLEAF_LDAP_SEARCH_BASE （必填）
  • 搜索用户的基础 DN。例如 ou=people,dc=example,dc=com。
• OVERLEAF_LDAP_SEARCH_FILTER
  • 用于查找用户的 LDAP 搜索过滤器。使用字面量 ‘{{username}}’ 可将给定的用户名插入到 LDAP 搜索中。
    • 示例：(|(uid={{username}})(mail={{username}}))（用户可使用邮箱或登录名登录）。
    • 示例：(sAMAccountName={{username}})（Active Directory）。
• OVERLEAF_LDAP_SEARCH_SCOPE
  • 搜索范围，可以是 base、one 或 sub（默认）。
• OVERLEAF_LDAP_SEARCH_ATTRIBUTES
  • 要从 LDAP 服务器获取的属性的 JSON 数组，例如 ["uid", "mail", "givenName", "sn"]。默认获取所有属性。
• OVERLEAF_LDAP_STARTTLS
  • 如果为 true，则使用基于 TLS 的 LDAP。
• OVERLEAF_LDAP_TLS_OPTS_CA_PATH
  • 包含用于验证 LDAP 服务器 SSL/TLS 证书的 CA 证书的文件路径。如果有多个证书，可以使用证书路径的 JSON 数组。这些文件必须能被 Docker 容器访问。
    • 示例（单个证书）：/var/lib/overleaf/certs/ldap_ca_cert.pem
    • 示例（多个证书）：["/var/lib/overleaf/certs/ldap_ca_cert1.pem", "/var/lib/overleaf/certs/ldap_ca_cert2.pem"]
• OVERLEAF_LDAP_TLS_OPTS_REJECT_UNAUTH
  • 如果为 true，则根据所提供的 CA 列表验证服务器证书。
• OVERLEAF_LDAP_CACHE
  • 如果为 true，则最多同时缓存 100 个凭据，缓存时间为 5 分钟。
• OVERLEAF_LDAP_TIMEOUT
  • 客户端操作在超时前允许持续的时间，单位为毫秒（默认：Infinity）。
• OVERLEAF_LDAP_CONNECT_TIMEOUT
  • 客户端在 TCP 连接超时前等待的时间，单位为毫秒（默认：操作系统默认值）。
• OVERLEAF_LDAP_IS_ADMIN_ATT 和 OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE
  • 当这两个环境变量都已设置时，如果 LDAP 配置文件包含 OVERLEAF_LDAP_IS_ADMIN_ATT 指定的属性，且其值与 OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE 匹配或是包含 OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE 的数组，登录过程会将 user.isAdmin 更新为 true，否则将 user.isAdmin 设置为 false。如果其中任一变量未设置，则管理员状态仅在 Launchpad 中创建管理员用户时被设置为 true。

以下五个变量用于配置如何从 LDAP 服务器获取用户联系人。

• OVERLEAF_LDAP_CONTACTS_FILTER
  • 用于在 LDAP 服务器中搜索要加载到联系人中的用户的过滤器。过滤器中的占位符 ‘{{userProperty}}’ 会被替换为发起搜索的 LDAP 用户的 OVERLEAF_LDAP_CONTACTS_PROPERTY 所指定属性的值。如果未定义，则不会从 LDAP 服务器获取任何用户到联系人中。
• OVERLEAF_LDAP_CONTACTS_SEARCH_BASE
  • 指定开始搜索联系人的基础 DN。默认为 OVERLEAF_LDAP_SEARCH_BASE。
• OVERLEAF_LDAP_CONTACTS_SEARCH_SCOPE
  • 搜索范围，可以是 base、one 或 sub（默认）。
• OVERLEAF_LDAP_CONTACTS_PROPERTY
  • 指定用户对象的哪个属性将替换 OVERLEAF_LDAP_CONTACTS_FILTER 中的 ‘{{userProperty}}’ 占位符。
• OVERLEAF_LDAP_CONTACTS_NON_LDAP_VALUE
  • 指定当搜索由非 LDAP 用户发起时 OVERLEAF_LDAP_CONTACTS_PROPERTY 的值。如果未定义该变量，生成的过滤器将不匹配任何内容。可以使用 * 作为通配符。

示例

OVERLEAF_LDAP_CONTACTS_FILTER=(gidNumber={{userProperty}})
OVERLEAF_LDAP_CONTACTS_PROPERTY=gidNumber
OVERLEAF_LDAP_CONTACTS_NON_LDAP_VALUE=1000

上述示例会将所有与当前 LDAP 用户具有相同 UNIX gid 的 LDAP 用户加载到其联系人中。非 LDAP 用户的联系人中将包含所有 UNIX gid=1000 的 LDAP 用户。

variables.env 示例文件

OVERLEAF_APP_NAME="Our Overleaf Instance"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Enables Thumbnail generation using ImageMagick
ENABLE_CONVERSIONS=true

# Disables email confirmation requirement
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Set for TLS via nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Our Overleaf Instance
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=[e-mail]

OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:[e-mail]"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]

OVERLEAF_EMAIL_FROM_ADDRESS=[e-mail]
OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
OVERLEAF_EMAIL_SMTP_PORT=587
OVERLEAF_EMAIL_SMTP_SECURE=false
# OVERLEAF_EMAIL_SMTP_USER=
# OVERLEAF_EMAIL_SMTP_PASS=
# OVERLEAF_EMAIL_SMTP_NAME=
OVERLEAF_EMAIL_SMTP_LOGGER=false
OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
OVERLEAF_CUSTOM_EMAIL_FOOTER=This system is run by department x

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## LDAP for CE ##
#################

EXTERNAL_AUTH=ldap
OVERLEAF_LDAP_URL=ldap://ldap.example.com:389
OVERLEAF_LDAP_STARTTLS=true
OVERLEAF_LDAP_TLS_OPTS_CA_PATH=/var/lib/overleaf/certs/ldap_ca_cert.pem
OVERLEAF_LDAP_SEARCH_BASE=ou=people,dc=example,dc=com
OVERLEAF_LDAP_SEARCH_FILTER=(|(uid={{username}})(mail={{username}}))
OVERLEAF_LDAP_BIND_DN=cn=ldap_reader,dc=example,dc=com
OVERLEAF_LDAP_BIND_CREDENTIALS=GoodNewsEveryone
OVERLEAF_LDAP_EMAIL_ATT=mail
OVERLEAF_LDAP_FIRST_NAME_ATT=givenName
OVERLEAF_LDAP_LAST_NAME_ATT=sn
# OVERLEAF_LDAP_NAME_ATT=cn
OVERLEAF_LDAP_SEARCH_ATTRIBUTES=["uid", "sn", "givenName", "mail"]

OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN=true

OVERLEAF_LDAP_PLACEHOLDER='Username or email address'

OVERLEAF_LDAP_IS_ADMIN_ATT=mail
OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE=[e-mail]

OVERLEAF_LDAP_CONTACTS_FILTER=(gidNumber={{userProperty}})
OVERLEAF_LDAP_CONTACTS_PROPERTY=gidNumber
OVERLEAF_LDAP_CONTACTS_NON_LDAP_VALUE='*'

​

分步指南：goauthentik

本节介绍一套已在 goauthentik 上测试通过的配置。示例中使用的 Base DN 为 dc=example,dc=com，请替换为你自己的值。

1. 创建绑定账户

   Overleaf 会先使用自己的账户登录目录以查找用户。在 Authentik 中，打开 Directory > Users，点击 New User，选择 Internal User 并点击 Next。输入用户名，例如 ldapservice，然后点击 Create：

   

   Authentik：创建绑定账户

   打开新建的用户并点击 Set password。该密码将填入 OVERLEAF_LDAP_BIND_CREDENTIALS：

   

   Authentik：设置绑定账户的密码（测试实例）

   记下地址栏中该用户的编号，例如 …/#/identity/users/19 中的 19。第 3 步中会用到它。

2. 创建提供商和应用

   打开 Applications > Applications 并点击 New Application。该向导会同时创建应用及其提供商。

   1. 为应用设置名称和 slug，例如 overleaf-ldap，然后点击 Next：

   

   Authentik：应用的名称和 slug

   2. 选择 LDAP Provider 并点击 Next：

   

   Authentik：选择 LDAP 提供商

   3. 将 Bind Mode 设置为 Direct binding，将 Search Mode 设置为 Direct querying：

   

   Authentik：LDAP 提供商的绑定模式和搜索模式

   4. 在下方将 Bind Flow 设置为 default-authentication-flow，将 Base DN 设置为你的 Base DN，例如 dc=example,dc=com：

   

   Authentik：LDAP 提供商的绑定流程和 Base DN

   5. 一直点击 Next 直到最后一页，然后提交应用。

3. 允许绑定账户搜索目录

   如果没有此权限，绑定账户只能看到它自己，搜索将找不到任何用户，所有 LDAP 登录都会失败。

   打开提供商，进入 Permissions 并点击 Assign Role Object Permission。在 Role 中输入第 1 步记下的编号并选择 ak-managed-role--user-<number>，然后开启 Search full LDAP directory：

   

   Authentik：为绑定账户授予搜索权限（测试实例）

   之后该角色在 Search full LDAP directory 下会显示一个勾选标记：

   

   Authentik：LDAP 提供商的权限（测试实例）

4. 运行 LDAP outpost

   Authentik 通过 outpost（一个独立的容器）响应 LDAP 请求。打开 Applications > Outposts，使用你的提供商创建一个类型为 LDAP 的 outpost，并按照 Authentik 的说明进行部署。它会监听所在主机的 389 端口。连接成功后，会显示一个绿色勾选标记：

   

   Authentik：正在运行的 LDAP outpost（测试实例）

   OVERLEAF_LDAP_URL=ldap://ldap.example.com:389
   
5. 填写 DN

   提供商页面会在 How to connect 下显示 Base DN 和一个示例：

   

   Authentik：LDAP 提供商概览（测试实例）

   不要原样复制示例中的值：

   • Bind DN 显示的是你当前登录的账户。请改用第 1 步中的绑定账户：cn=ldapservice,ou=users,<Base DN>。
   • Search base 显示的是 Base DN。请使用 ou=users,<Base DN>。

   OVERLEAF_LDAP_BIND_DN=cn=ldapservice,ou=users,dc=example,dc=com
   OVERLEAF_LDAP_BIND_CREDENTIALS=<password of ldapservice>
   OVERLEAF_LDAP_SEARCH_BASE=ou=users,dc=example,dc=com
   OVERLEAF_LDAP_SEARCH_FILTER=(cn={{username}})
   

   Authentik 会在 ou=virtual-groups 下为每个用户保留一个同名的组。在整个 Base DN 中搜索 (cn=alice) 会同时找到 cn=alice,ou=users,… 和 cn=alice,ou=virtual-groups,…，而 Overleaf 会拒绝匹配到多个条目的登录。请将搜索基础保持为 ou=users,<Base DN>。

6. 检查搜索

   在启动 Overleaf 之前，先运行它将执行的搜索。输出中必须恰好有一个 dn:：

   ldapsearch -x -H ldap://ldap.example.com:389 \
     -D cn=ldapservice,ou=users,dc=example,dc=com -w '<password of ldapservice>' \
     -b ou=users,dc=example,dc=com '(cn=alice)' dn
   

   如果完全没有 dn:，通常意味着缺少第 3 步中的权限。

7. 映射管理员（可选）

   用户所属的组位于 memberOf 中，形式为 ou=groups 下的 DN。要让 Authentik 组 Admins 的成员成为 Overleaf 的管理员：

   OVERLEAF_LDAP_IS_ADMIN_ATT=memberOf
   OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE=cn=Admins,ou=groups,dc=example,dc=com
   

   管理员标志会在每次 LDAP 登录时更新。如果属性或值有误，所有通过 LDAP 登录的管理员都会失去管理员权限。请先使用另一个管理员账户测试该映射。

经过测试的 goauthentik variables.env

variables.env

EXTERNAL_AUTH=ldap
OVERLEAF_LDAP_IDENTITY_SERVICE_NAME=Log in with Authentik
OVERLEAF_LDAP_URL=ldap://ldap.example.com:389
OVERLEAF_LDAP_BIND_DN=cn=ldapservice,ou=users,dc=example,dc=com
OVERLEAF_LDAP_BIND_CREDENTIALS=<password of ldapservice>
OVERLEAF_LDAP_SEARCH_BASE=ou=users,dc=example,dc=com
OVERLEAF_LDAP_SEARCH_FILTER=(cn={{username}})
OVERLEAF_LDAP_EMAIL_ATT=mail
OVERLEAF_LDAP_NAME_ATT=name
OVERLEAF_LDAP_IS_ADMIN_ATT=memberOf
OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE=cn=Admins,ou=groups,dc=example,dc=com
OVERLEAF_LDAP_UPDATE_USER_DETAILS_ON_LOGIN=true