Nextcloud 自带 LDAP 应用，可将 LDAP 用户（包括 Active Directory）显示在用户列表中。他们使用 LDAP 凭据登录，无需创建单独的 Nextcloud 账户。管理员可以像管理其他用户一样管理他们的组、配额和共享权限。
**注意**
需要 PHP LDAP 模块，多数发行版由 php-ldap 提供。
LDAP 应用支持：
– LDAP 组。
– 与 Nextcloud 用户和组共享文件。
– WebDAV 和桌面客户端访问。
– 版本管理、外部存储及其他所有 Nextcloud 功能。
– 无需额外配置的 Active Directory 连接。
– Active Directory 主组。
– 自动检测基础 DN、邮箱、端口等 LDAP 属性。
– 默认只读访问 LDAP，不支持在 LDAP 中编辑或删除用户。
– 可选：允许用户通过 Nextcloud 修改 LDAP 密码。
**注意**
LDAP 后端需要不阻止访问或正确配置的 SELinux 环境，参阅官方 SELinux 配置文档。
配置
在“应用”页启用 LDAP user and group backend，然后到管理页配置。
配置面板有四个标签页。必须先正确填写 Server 页，才能访问其余页面。正确配置会亮起绿色指示器；鼠标悬停字段可查看提示。
Server（服务器）
从此页开始；可以配置多个服务器。
**注意**
不要在这里配置故障转移主机，应按“高级设置”说明操作。
至少填写主机名。如果服务器需要认证，在此输入凭据。Nextcloud 尝试自动检测端口与基础 DN；两者必填，检测失败时手工输入。
**服务器配置：**
可配置一个或多个 LDAP 服务器。Delete Configuration 删除当前配置。
**主机：**
LDAP 服务器的主机名或 IP，也可使用 ldaps:// URI。输入端口号可以加快检测。
示例：
* directory.my-company.com
* ldaps://directory.my-company.com
* directory.my-company.com:9876
**端口：**
用于连接 LDAP 的端口。新配置最初禁用此字段；标准端口会自动检测，非标准端口也会尝试检测，失败时必须手工填写。
示例：
* 389
**用户 DN：**
有权搜索 LDAP 目录的用户 DN。匿名访问则留空。建议使用专用 LDAP 系统用户。
示例：
* uid=nextcloudsystemuser,cn=sysusers,dc=my-company,dc=com
**密码：**
上述用户的密码；匿名访问留空。
**基础 DN：**
可访问全部用户和组的 LDAP 基础 DN，可以多行填写多个。用户和组各自的基础 DN 可在 Advanced 页配置。本项必填，Nextcloud 根据用户 DN 或主机尝试检测，失败时须手工填写。
示例：
* dc=my-company,dc=com
Users（用户）
此页决定哪些 LDAP 用户显示在 Nextcloud 用户列表。能否登录则由 Login Attributes 决定。可访问但未列出的用户成为隐藏用户。也可绕过表单，直接输入原始 LDAP 过滤器。
**仅这些对象类：**
Nextcloud 检测常用于用户对象的对象类，自动选中返回用户最多的类，也可多选。
**仅来自这些组：**
LDAP 过滤器支持 member-of-overlay 时，可以限制只有指定一个或多个组的用户出现在 Nextcloud 列表。默认不选组，可多选。
不支持 member-of-overlay 时，该字段禁用，请联系 LDAP 管理员。
**编辑 LDAP 查询：**
点击 Edit LDAP Query 切换过滤模式，可直接输入 LDAP 过滤器，例如：
(&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
dc=example,dc=com))
**找到 x 位用户：**
此处显示将列出的用户数量估计，修改后自动更新。
Login Attributes（登录属性）
此页决定哪些 LDAP 用户可登录，以及输入的登录名与哪些属性匹配，例如 LDAP/AD 用户名或邮箱。可多选，也可直接填写 LDAP 过滤器。
原始 LDAP 过滤器可以覆盖 Users 页的用户过滤设置。
**LDAP 用户名：**
勾选 LDAP Username 后，将登录值与目录用户名比较，对应属性通常为 uid 或 samaccountname，由 Nextcloud 自动检测。
**LDAP 邮箱：**
勾选 LDAP Email Address 后，与 mailPrimaryAddress、mail 中的邮箱比较。
**其他属性：**
Other Attributes 多选框可指定其他比较属性，列表由 LDAP 用户对象属性自动生成。
**编辑 LDAP 查询：**
点击 Edit LDAP Query 切换模式，直接输入过滤器。
%uid 占位符替换为用户输入的登录名。
示例：
– 仅用户名：
(&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
dc=example,dc=com)(uid=%uid)
– 用户名或邮箱：
((&(objectClass=inetOrgPerson)(memberOf=cn=nextcloudusers,ou=groups,
dc=example,dc=com)(|(uid=%uid)(mail=%uid)))Groups（组）
默认没有 LDAP 组可用于 Nextcloud。此页决定可用组，也可直接输入原始过滤器。
**仅这些对象类：**
Nextcloud 检测 LDAP 常用组对象类，只列出至少返回一个组对象的类，可多选。典型类为 group 或 posixGroup。
**仅来自这些组：**
Nextcloud 列出 LDAP 可用组，从中选择允许访问的组。
**编辑 LDAP 查询：**
点击 Edit LDAP Query 切换过滤模式，直接输入 LDAP 过滤器。
示例：
* objectClass=group
* objectClass=posixGroup
**找到 y 个组：**
显示可用组数量估计，修改后自动更新。
高级设置
这里的选项并非建立连接所必需，可禁用当前配置、设置副本主机，或调整性能。
分为四部分：
– 连接设置。
– 目录设置。
– 特殊属性。
– 用户资料属性。
连接设置
**启用配置：**
Configuration Active 启用或禁用当前配置，默认关闭。成功测试连接后自动打开。
**备用（副本）主机：**
有备用 LDAP 服务器时，在此配置。主服务器不可达时自动连接备用。备用必须是主服务器副本，确保对象 UUID 相同。
示例：
* directory2.my-company.com
**备用端口：**
备用服务器端口。只指定主机未指定端口时，使用前面配置的主端口。
示例：
* 389
**禁用主服务器：**
Disable Main Server 可手工覆盖主服务器，让 Nextcloud 只连接备用，适合计划停机。
**关闭 SSL 证书验证：**
Turn off SSL certificate validation 关闭证书检查，仅供测试！实际效果取决于 PHP 系统配置，例如官方 Nextcloud 容器镜像中不生效。原文给出针对特定用途的配置方式：在 /etc/ldap/ldap.conf 加入下行。
` TLS_REQCERT ALLOW `
**缓存 TTL：**
缓存用于减少 LDAP 流量，例如缓存用户名，避免每个页面都查询，并加快用户页。保存配置会清空缓存，TTL 单位为秒。
几乎每个 PHP 请求都需新建 LDAP 连接。即使需要较新数据，也建议设约十五秒的最小生命周期，而非完全禁用缓存。
示例：
– 十分钟：600。
– 一小时：3600。
缓存工作方式见下文。
目录设置
**用户显示名字段：**
用作 Nextcloud 显示名的 LDAP 属性。
* 示例： displayName
**第二显示名字段：**
可选第二显示属性，在显示名后括号中展示。例如 mail 显示为 Molly Foo (molly@example.com)。
**用户基础树：**
能够访问全部用户的完整基础 DN，无论基本设置填了什么，这里都必须完整。可一行一个填写多个树。
* 示例：
cn=programmers,dc=my-company,dc=com
cn=designers,dc=my-company,dc=com
**用户搜索属性：**
用户搜索属性用于共享对话框等搜索。默认为用户显示名属性，可一行一个填写多个。
用户对象缺少该属性时，不会显示，也不能登录，显示名属性同样受影响。覆盖默认值时，必须在此明确包含显示名属性。
* 示例：
displayName
**禁用已从 LDAP 消失的用户**
启用 Disable users missing from LDAP 后，已从 LDAP 消失的残留用户会被视为禁用，例如其公共共享不再工作。参阅 LDAP 用户清理文档。
**组显示名字段：**
用作 Nextcloud 组名的属性，允许字符为 a-zA-Z0-9.-_@。一旦分配组名便不能更改。
* 示例： cn
**组基础树：**
能够访问全部组的完整基础 DN，不受基本设置内容影响。可一行一个填写多个。
* 示例：
cn=barcelona,dc=my-company,dc=com
cn=madrid,dc=my-company,dc=com
**组搜索属性：**
搜索组时使用的属性，例如共享对话框中。默认使用组显示名属性，可多行填写。
覆盖默认值后，除非明确列出，否则不再考虑组显示名属性。
* 示例：
cn
description
**组成员关联：**
指示组成员关系的属性，即 LDAP 组引用用户的属性。
Nextcloud 自动检测此值，只有理由充分且明确了解后果时才修改。
* 示例： uniquemember
**嵌套组：**
启用从子组获取成员。
要根据嵌套组列出用户并允许登录，还需参考后文“基于嵌套组列出用户和登录”。
**启用 LDAP 用户改密：**
允许 LDAP 用户自行改密，并允许超级管理员、组管理员为其 LDAP 用户改密。
启用需要满足：
**一般要求：**
– LDAP 访问控制必须允许改密；Server 设置中的 User DN 需要更新 userPassword 的写权限。
– 密码以明文内容发送给 LDAP，因此连接必须使用传输加密，例如 LDAPS。
– 强烈建议 LDAP 服务端进行密码哈希。AD 默认单向存储；OpenLDAP 可配置 ppolicy overlay 的 ppolicy_hash_cleartext。
**Active Directory 的额外要求：**
– Nextcloud 与 LDAP 之间至少使用 128 位传输加密。
– 将 dSHeuristics 的 fUserPwdSupport 字符设为让 userPassword 作为 unicodePwd 别名。AD LDS 默认如此，AD DS 则不是。
**默认密码策略 DN：**
Default password policy DN 需要 OpenLDAP 与 ppolicy。用户没有专属密码策略时，使用该默认策略 DN 处理过期：
– 密码将过期时，通过 Nextcloud 通知应用显示剩余天数。
– 密码已过期但仍有足够宽限登录次数时，登录过程中提示重置。
留空则不启用密码过期处理。
使用该功能必须启用 LDAP 用户改密，并正确配置 OpenLDAP ppolicy 模块。
* 示例：
cn=default,ou=policies,dc=my-company,dc=com
特殊属性
**配额字段：**
可读取 LDAP 属性并据此设置用户配额。在此指定属性，其值应为可读形式，例如 2 GB。
* 示例： NextcloudQuota
**警告**
LDAP 配额设置会覆盖 Nextcloud 用户管理页的配额。
**默认配额：**
为没有 Quota Field 值的 LDAP 用户指定默认配额。
* 示例： 15 GB
**警告**
LDAP 配额会覆盖用户管理页的设置。
**邮箱字段：**
从 LDAP 属性设置用户邮箱，留空使用默认行为。
* 示例： mail
**主目录命名规则：**
默认在数据目录下按 Nextcloud 用户名创建主目录，例如 /var/www/nextcloud/data/alice。可指定 LDAP 属性覆盖名称，该属性也可返回绝对路径，例如 /mnt/storage43/alice。留空使用默认。
* 示例： cn
新安装会强制执行主目录规则。一旦设置从 LDAP 获取主目录，所有用户必须具备该属性，否则不能登录，也不会初始化文件系统，其共享也无法供其他用户使用。
迁移安装保留旧行为：属性未设置时使用 Nextcloud 用户名作为目录。可用 occ 改为强制执行，例如 Ubuntu：
sudo -E -u www-data php occ config:app:set user_ldap enforce_home_folder_naming_rule --value=1用户资料属性
配置后，对应 LDAP 数据覆盖用户资料。LDAP 数据校验和存于用户设置 user_ldap、lastProfileChecksum，未变化则跳过资料更新。若 config.php 启用 memcache.distributed，还会缓存校验和；缓存存在期间跳过检查，过期时间为 ldapCacheTTL 秒。
注意：
– 用户可修改资料，但 LDAP 数据变化后会覆盖。
– 用户可修改资料可见范围。
– 默认可见范围由 config.php 的 account_manager.default_property_scope 数组控制。
– 属性有多个值时，仅使用第一个分发值。
– 所有用户资料属性最多 2048 个字符。
– LDAP 数据格式错误，很可能导致资料字段为空。
– config.php 全局设置 profile.enabled => false 会跳过这段代码。
运行 sudo -E -u www-data php occ ldap:check-user --update <uid> 可显示 LDAP 数据并更新资料。用 php occ user:list 获取正确 uid。
**注意**
取消这里的属性名称不会删除现有资料；设置不存在的属性则会清空对应资料字段。
**电话字段：**
电话号码属性复制到资料电话字段。号码必须为无分隔符的国际 E.164 格式，例如 +4966612345678。
* 示例： telephoneNumber
* 示例： mobile
**注意**
应在 config.php 设置 default_phone_region。
**网站字段：**
网站 URI 属性必须以 https:// 或 http:// 开头，其他方案暂不允许。labeledURI 的标签，即首个空格之后的内容，会被删除。
* 示例： wWWHomePage
* 示例： labeledURI
**地址字段：**
用户地址属性，在资料页称为 Location。需要单行值，如 city, country 或 somewhere under the loving sun。多行 postalAddress 会重新格式化，美元分隔符换为逗号与空格。
* 示例： postalAddress
* 示例： localityName
**Twitter 字段：**
Twitter 账户名属性。
**Fediverse 字段：**
用户 Fediverse 地址属性。
**组织字段：**
组织名称属性。
* 示例： company
* 示例： o or organizationName
**角色字段：**
组织内角色或职位名称属性。
* 示例： title
**标题简介字段：**
用户标题简介属性。
**个人简介字段：**
用户简介属性。允许 Unix LF 多行文本；Windows CRLF 和 Macintosh CR 会转换为 LF。
**出生日期字段：**
出生日期属性，允许格式：
* LDAP GeneralizedTime
* YYYY-MM-DD
* YYYYMMDD
专家设置
可调整基础行为以满足需求，投入生产前必须充分测试。
**内部用户名：**
内部用户名是 LDAP 用户在 Nextcloud 中的标识。默认取 UUID 属性，确保唯一且无需字符转换。只允许 [a-zA-Z0-9_.@-]，其他字符转为 ASCII 等价字符或省略。
LDAP 后端检查所有已启用后端，包括本地用户，避免重复。发生冲突时追加 1000–9999 随机数，例如 alice 已存在时可能生成 alice_1337。
内部用户名默认用于主目录，也构成所有 DAV 等服务的远程 URL 的一部分。
Internal Username 可覆盖这些默认行为，留空保持默认，修改只影响新映射用户。
Nextcloud 用户名不可变，创建后不能修改。因此使用可能变化的属性（如姓名变化时更新的邮箱）可能导致问题。
* 示例： uid
**覆盖 UUID 检测**
Nextcloud 默认自动检测 UUID 属性，用于唯一识别 LDAP 用户与组；没有其他设置时，也据此创建内部用户名。
可指定自选属性，但必须确保用户和组都能取得它且值唯一。留空为默认。修改影响新映射的用户与组；当用户或组 DN 变化而缓存仍含旧 UUID 时，也可能产生新用户。
因此应在投入生产及清除绑定前配置，参阅下文“用户和组映射”。
* 示例： cn
**用户名与 LDAP 用户映射**
Nextcloud 用用户名作为存储和分配数据的键。每个 LDAP 用户对应一个内部用户名，映射到其 UUID。DN 也会缓存以减少交互，但不用于身份识别；DN 变化通过检查 UUID 发现。
组同样如此。
内部名称在 Nextcloud 各处使用，清空映射会留下大量残留。切勿在生产中清空，只能用于测试或实验服务器。
**警告**
清空映射并不局限于当前配置，会影响全部 LDAP 配置！
测试配置
**警告**
测试前确认 Configuration Active 已启用。它默认关闭，即使其他设置正确也会返回“密码错误”。Nextcloud 只在成功测试连接后自动启用。
Test Configuration 按当前字段值检查，测试前无需保存。点击后尝试绑定，失败时显示黄色提示：The configuration is invalid. Please have a look at the logs for further details.
测试成功后保存，再到用户页检查用户与组是否正确获取。
通过 occ 设置其他选项
少量配置只能通过 occ 命令行设置。
后台同步间隔
LDAP 后端在每次登录、首次发现新用户及定期后台作业中更新邮箱、配额、头像等属性。
后台作业每轮重新计算间隔，目标是每天处理每位已知 LDAP 用户约一次。间隔取决于映射用户总数与最小分页大小，限制为至少三十分钟、最多十二小时。
管理员组映射
每个连接可提升一个 LDAP 组为管理员组，其成员获得 Nextcloud 管理权限。
可通过专用 occ 命令提升。组参数可以是 Nextcloud 组 ID，或用于搜索的组名称；搜索必须完全匹配。
用法示例：
$ sudo -E -u www-data php occ ldap:promote-group --help
Description:
declares the specified group as admin group (only one is possible per LDAP configuration)
Usage:
ldap:promote-group [options] [--] <group>
Arguments:
group the group ID in Nextcloud or a group name
Options:
-y, --yes do not ask for confirmation
…
# Example
$ sudo -E -u www-data php occ ldap:promote-group "Nextcloud Admins"
Promote Nextcloud Admins to the admin group (y|N)? y
Group Nextcloud Admins was promoted
$ sudo -E -u www-data php occ ldap:promote-group "Paramount Court"
Promote Nextcloud Admins to the admin group and demote Nextcloud Admins (Group ID: nextcloud_admins) (y|N)? y
Group Paramount Court was promoted
$ sudo -E -u www-data php occ ldap:promote-group "Paramount Court"
The specified group is already promoted**注意**
只有组 ID 与显示名不同时才会显示 ID。
也可用 occ ldap:set-config $configId ldapAdminGroup $groupId 设置，但组 ID 可能尚未知，推荐特别是在自动化设置中使用 promote-group，它会拉取组并确定 ID。
撤销提升或重置时，为目标配置的 ldapAdminGroup 设置空字符串：
# Reset an admin group mapping via set-config
occ ldap:set-config $configId ldapAdminGroup ""
# Example
occ ldap:set-config s01 ldapAdminGroup ""
**提示**
同一连接需要多个管理员组时，在 LDAP 中创建包含这些嵌套组的容器组，并提升该容器组。
头像集成
用户在 LDAP 的 jpegPhoto 或 thumbnailPhoto 属性存有照片时，会作为 Nextcloud 头像。此时用户无法在个人页更改，必须在 LDAP 修改；优先使用 jpegPhoto。
这些属性不存在或为空时，用户可在 Nextcloud 个人页上传、管理头像；这些头像不会存到 LDAP。
每天获取一次 LDAP 照片属性，确保使用当前图片。LDAP 头像优先；删除后，恢复最近的 Nextcloud 头像。
LDAP 图片会自动裁剪、缩放，仅影响显示，不改变原图。
指定属性或关闭图片加载
可禁用头像集成，或指定单个其他属性，内容应与 jpegPhoto、thumbnailPhoto 一样为图像数据。
只能通过 occ 修改，选项如下：
– 使用前述默认行为：
occ ldap:set-config "s01" "ldapUserAvatarRule" "default"
– 不从 LDAP 获取用户图片：
occ ldap:set-config "s01" "ldapUserAvatarRule" "none"
– 从 selfiePhoto 属性读取图片：
occ ldap:set-config "s01" "ldapUserAvatarRule" "data:selfiePhoto"
s01 是配置 ID，可通过 occ ldap:show-config 查询。
排错、提示和技巧
日志
LDAP 实现可记录大量活动细节。排错时可暂时将 loglevel 设为 INFO（1）或 DEBUG（0）。
SSL 证书验证（LDAPS、TLS）
常见问题是 PHP 不认识证书。出现验证问题时检查：
– 已在 Nextcloud 服务器安装 LDAP 服务器证书。
– 系统 LDAP 配置文件（通常 /etc/ldap/ldap.conf）已声明证书。
– 使用 LDAPS 时端口正确，默认为 636。
Microsoft Active Directory
相比旧版，无需额外调整，Nextcloud 在设置过程中会自动发现正确配置。
memberOf 与读取 memberof 的权限
过滤器使用 memberOf 时，查询用户可能需要相应权限。原文提供了 Microsoft Active Directory 的相关说明链接。
基于嵌套组列出用户并登录
仅勾选目录设置中的 Nested groups 不够。还须在用户及登录过滤器中指定 LDAP_MATCHING_RULE_IN_CHAIN，将 memberof 条件按下例修改：
> * (memberof=cn=Nextcloud Users Group,ou=Groups,…)
改为：
> * (memberof:1.2.840.113556.1.4.1941:=cn=Nextcloud Users Group,ou=Groups,…)
复制服务器配置
已有可用配置，想创建类似配置或修改前保留快照时：
1. 进入 Server 页。
2. 在 Server Configuration 选择 Add Server Configuration。
3. 对 Take over settings from recent server configuration? 回答 yes。
4. 可选：到 Advanced 的 Connection Settings 取消 Configuration Active，防止保存后立即使用新配置。
5. 点击 Save。
随后可修改并启用配置。
LDAP 内部机制
以下介绍部分后端实现。
用户和组映射
Nextcloud 使用用户或组名称分配数据库信息。为保证可靠性，创建永久内部名称并映射到 LDAP DN、UUID。DN 在 LDAP 中变化时可被检测，不会冲突。
映射存于 ldap_user_mapping 与 ldap_group_mapping 表。用户名也用于包含文件和元数据的用户目录，除非另设主目录规则。
内部用户名与可见显示名分开；组名尚非如此，因此不能更改。
投入生产前必须完成 LDAP 配置。映射表很早就会填充，测试期间可随时清空，生产中绝对不要这样做。
用户属性在共享自动补全、用户管理等需要时获取，并存入数据库提升性能。通常每天分批重查两次，也会在用户登录时刷新，或用 occ ldap:check-user --update USERID 手工获取，USERID 为 Nextcloud 用户 ID。
组成员缓存存入数据库，以便增删成员时触发事件。后台作业更新缓存，也可用 occ ldap:check-group --update GROUPID 强制更新。
缓存
LDAP 信息缓存在 Nextcloud 内存缓存中，须先安装配置内存缓存。它加快交互与共享，按需填充，直到每个请求的 TTL 到期。登录不缓存；要缩短登录时间，可配置从 LDAP 服务器分担负载。
TTL 可在性能与数据新鲜度间权衡，默认缓存十分钟。原请求 TTL 期间，相同请求由缓存响应，不访问 LDAP。
TTL 针对单个请求。缓存到期不会自动重新填充，只有打开用户管理页、共享对话框搜索等新请求才会填充。
一个例外是特定后台任务会自动维护 user-group-mappings，始终保持其缓存更新。
正常情况下不会一次加载全部用户。通常生成页面结果时，每批三十个，直到达到限制或没有更多结果，因此 Nextcloud 与 LDAP 服务器都必须支持分页结果。
Nextcloud 记住用户所属的 LDAP 配置，请求直接发送到相应服务器。用户失效，例如迁移或服务器不可达时，其他服务器也会收到请求。
备用服务器处理
联系不上主 LDAP 时，Nextcloud 假定其离线，在 TTL 期间不再尝试。配置备用时改连备用。计划停机应勾选 Disable Main Server，避免无谓尝试。
注意
LDAP 对象的姓名或显示名属性（默认 displayname）为空时，Nextcloud 将其视为空对象，不展示该用户或 AD 对象的结果，以免收集技术账户。
—
原文：User authentication with LDAP，Nextcloud 35 管理手册，Nextcloud 文档贡献者。本文为中文翻译，截图使用官方原图地址。许可：CC BY 3.0，仓库许可。
暂无评论内容