> ## 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.
# LDAP 身份验证
该功能由 [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep) 开发。这里我们提供一些文档，帮助你完成配置。
Overleaf 使用的是 **passport-ldapauth** 库，该库相对陈旧，无法完全保证 LDAP 兼容性。在某些 LDAP 身份提供商（例如 [https://goauthentik.io/](https://goauthentik.io/)）上可能会出现登录失败的情况。因此，如果可能，建议优先使用 OAuth/SAML 方式。对于 goauthentik，请按照下文经过测试的[分步指南：goauthentik](/zh-CN/on-premises/configuration/overleaf-toolkit/authentication/ldap-authentication)进行配置。
### 什么是 LDAP
LDAP 是一种用于外部身份验证的认证协议。Overleaf Server Pro 在 Web 界面中提供了一个专用的 LDAP 登录表单，与标准认证方式相互独立。当用户提交其 LDAP 用户名和密码时，Overleaf 后端会针对所配置的 LDAP 服务器（例如 `ldap://ldap:10389`）验证凭据。
### 配置
在内部，Overleaf LDAP 使用 [passport-ldapauth](https://github.com/vesse/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` 的值。如果未定义该变量，生成的过滤器将不匹配任何内容。可以使用 `*` 作为通配符。
```text theme={null}
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 用户。
```text theme={null}
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=support@example.com
OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]
OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
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=admin@example.com
OVERLEAF_LDAP_CONTACTS_FILTER=(gidNumber={{userProperty}})
OVERLEAF_LDAP_CONTACTS_PROPERTY=gidNumber
OVERLEAF_LDAP_CONTACTS_NON_LDAP_VALUE='*'
```
## 分步指南：goauthentik
本节介绍一套已在 [goauthentik](https://goauthentik.io/) 上测试通过的配置。示例中使用的 Base DN 为 `dc=example,dc=com`，请替换为你自己的值。
Overleaf 会先使用自己的账户登录目录以查找用户。在 Authentik 中，打开 **Directory > Users**，点击 **New User**，选择 **Internal User** 并点击 **Next**。输入用户名，例如 `ldapservice`，然后点击 **Create**：
打开新建的用户并点击 **Set password**。该密码将填入 `OVERLEAF_LDAP_BIND_CREDENTIALS`：
记下地址栏中该用户的编号，例如 `…/#/identity/users/19` 中的 `19`。第 3 步中会用到它。
打开 **Applications > Applications** 并点击 **New Application**。该向导会同时创建应用及其提供商。
1\. 为应用设置名称和 slug，例如 `overleaf-ldap`，然后点击 **Next**：
2\. 选择 **LDAP Provider** 并点击 **Next**：
3\. 将 **Bind Mode** 设置为 **Direct binding**，将 **Search Mode** 设置为 **Direct querying**：
4\. 在下方将 **Bind Flow** 设置为 `default-authentication-flow`，将 **Base DN** 设置为你的 Base DN，例如 `dc=example,dc=com`：
5\. 一直点击 **Next** 直到最后一页，然后提交应用。
如果没有此权限，绑定账户只能看到它自己，搜索将找不到任何用户，所有 LDAP 登录都会失败。
打开提供商，进入 **Permissions** 并点击 **Assign Role Object Permission**。在 **Role** 中输入第 1 步记下的编号并选择 `ak-managed-role--user-`，然后开启 **Search full LDAP directory**：
之后该角色在 **Search full LDAP directory** 下会显示一个勾选标记：
Authentik 通过 outpost（一个独立的容器）响应 LDAP 请求。打开 **Applications > Outposts**，使用你的提供商创建一个类型为 **LDAP** 的 outpost，并按照 Authentik 的说明进行部署。它会监听所在主机的 389 端口。连接成功后，会显示一个绿色勾选标记：
```dotenv theme={null}
OVERLEAF_LDAP_URL=ldap://ldap.example.com:389
```
提供商页面会在 **How to connect** 下显示 Base DN 和一个示例：
不要原样复制示例中的值：
* **Bind DN** 显示的是你当前登录的账户。请改用第 1 步中的绑定账户：`cn=ldapservice,ou=users,`。
* **Search base** 显示的是 Base DN。请使用 `ou=users,`。
```dotenv theme={null}
OVERLEAF_LDAP_BIND_DN=cn=ldapservice,ou=users,dc=example,dc=com
OVERLEAF_LDAP_BIND_CREDENTIALS=
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,`。
在启动 Overleaf 之前，先运行它将执行的搜索。输出中必须恰好有一个 `dn:`：
```shell theme={null}
ldapsearch -x -H ldap://ldap.example.com:389 \
-D cn=ldapservice,ou=users,dc=example,dc=com -w '' \
-b ou=users,dc=example,dc=com '(cn=alice)' dn
```
如果完全没有 `dn:`，通常意味着缺少第 3 步中的权限。
用户所属的组位于 `memberOf` 中，形式为 `ou=groups` 下的 DN。要让 Authentik 组 `Admins` 的成员成为 Overleaf 的管理员：
```dotenv theme={null}
OVERLEAF_LDAP_IS_ADMIN_ATT=memberOf
OVERLEAF_LDAP_IS_ADMIN_ATT_VALUE=cn=Admins,ou=groups,dc=example,dc=com
```
管理员标志会在每次 LDAP 登录时更新。如果属性或值有误，所有通过 LDAP 登录的管理员都会失去管理员权限。请先使用另一个管理员账户测试该映射。
```dotenv title="variables.env" wrap theme={null}
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=
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
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.