Realms Wiki接入LDAP目录服务：direct bind、bind by search与TLS加密完整配置教程

Realms Wiki 是一款基于 Git 的开源 wiki，除了本地数据库账号外，还支持通过 LDAP 目录服务完成用户认证。本文将带你完成 Realms Wiki 接入 LDAP 的完整配置，覆盖 direct bind（直接绑定）、bind by search（搜索绑定）两种登录方式，以及 LDAP/TLS 与 START_TLS 加密连接的全部配置项，帮助你在生产环境中安全地接入企业目录。

一、Realms Wiki 的 LDAP 认证能做什么

Realms Wiki 内置 LDAP 认证模块 realms/modules/auth/ldap/，用户只需在登录页输入 User ID 和密码，系统就会连接你的 LDAP 服务器完成身份验证，共支持三种组合：

• direct bind（直接绑定）：用用户提交的账号密码直接构造 DN 执行 BIND，适合 DN 结构固定的目录；
• bind by search（搜索绑定）：先用一个服务账号绑定目录、按模板搜索出用户，再用用户密码做一次 rebind 校验；
• TLS 加密：支持 ldaps:// 显式 TLS 与 START_TLS 两种加密方式。

配置好 LDAP 配置块后，auth.ldap 模块会自动加入模块列表（判断逻辑见 realms/config/init.py），登录页随即出现 "Login with LDAP" 入口；如果关闭本地认证（"AUTH_LOCAL_ENABLE": false），LDAP 表单将直接作为唯一登录方式，页面模板见 realms/modules/auth/templates/auth/ldap/login.html。

二、LDAP 配置文件放在哪里

所有配置写在 JSON 格式的 realms-wiki.json 中。Realms Wiki 按以下顺序查找该文件：当前工作目录 → 用户主目录 → /etc/realms-wiki（查找逻辑同样在 realms/config/init.py 的 get_path 方法中）。

README 的 "LDAP (beta)" 章节提供了全部官方示例，可对照查阅：README.md。

三、direct bind 直接绑定：最简单的一步配置

direct bind 的思路是：用户 DN 由 BIND_DN 模板给出，其中 %(username)s 会被替换为登录表单输入的 User ID。

"LDAP": {
    "URI": "ldap://127.0.0.1:389",
    "BIND_DN": "uid=%(username)s,ou=People,dc=realms,dc=io",
    "KEY_MAP": {
        "username": "cn",
        "email": "mail"
    }
}

配置要点：

• URI 是必填项，必须以 ldap:// 或 ldaps:// 开头，缺失时启动报错 LDAP is required, but the LDAP URI has not been defined；
• KEY_MAP 可选，把 LDAP 属性（如 cn、mail）映射到 Realms 用户对象，多值属性只取第一个值；
• LDAP_PROTO_VERSION 可选，默认协议版本 3，同时兼容旧式 OPTIONS 中的 OPT_PROTOCOL_VERSION。

绑定逻辑在 realms/modules/auth/ldap/models.py 的 direct_bind 方法：BIND 成功后还会对用户 DN 做一次 BASE 范围查询，取出 KEY_MAP 中声明的属性。

四、bind by search 搜索绑定：适合 DN 不固定的目录

当用户 DN 不固定、只知道用户所在的 base DN 时，使用 bind by search——配置中出现 USER_SEARCH 键即自动切换到该模式：

"LDAP": {
    "URI": "ldap://127.0.0.1:389",
    "BIND_DN": "cn=realms,ou=apps,dc=realms,dc=io",
    "BIND_AUTH": "服务账号密码",
    "USER_SEARCH": {
        "base": "ou=users, dc=realms,dc=io",
        "filter": "(uid=%(username)s)"
    },
    "KEY_MAP": {
        "username": "cn",
        "email": "mail"
    }
}

流程分三步（源码见同文件的 bind_search 方法）：

1. 用 BIND_DN + BIND_AUTH（专用服务账号）绑定目录；两者省略时执行匿名绑定；
2. 在 USER_SEARCH.base 下按 filter 搜索用户，%(username)s 替换为登录名；filter 忘记写括号也没关系，系统会自动补上外层 ()；
3. 找到用户后，用用户刚输入的密码执行 rebind 验证，通过才允许登录。

USER_SEARCH 还支持可选的 scope 参数：base、level、subtree（默认子树搜索）。

五、启用 TLS 加密：ldaps 与 START_TLS 两种方案

方案 1：ldaps:// 显式 TLS

"LDAP": {
    "URI": "ldaps://127.0.0.1:686",
    "BIND_DN": "uid=%(username)s,ou=People,dc=realms,dc=io",
    "TLS_OPTIONS": {
        "CA_CERTS_FILE": "CA证书PEM文件路径"
    }
}

• CA_CERTS_FILE 指向签发 LDAP 服务器证书的 CA 的 PEM 文件；若该 CA 已被系统信任且 Python 版本较新，可以省略；
• 调试期可临时关闭证书校验（生产环境请勿使用）：

"TLS_OPTIONS": {
    "VALIDATE": "NONE"
}

VALIDATE 只接受 NONE、OPTIONAL、REQUIRED 三个值（默认 REQUIRED），取值非法会报 The 'VALIDATE' TLS option must be one of: NONE, REQUIRED, OPTIONAL。

方案 2：START_TLS 升级加密

普通 ldap:// 连接可以先明文建立连接，再原地升级为 TLS，只需追加 "START_TLS": true：

"LDAP": {
    "URI": "ldap://127.0.0.1:389",
    "BIND_DN": "uid=%(username)s,ou=People,dc=realms,dc=io",
    "START_TLS": true,
    "TLS_OPTIONS": {
        "CA_CERTS_FILE": "CA证书PEM文件路径"
    }
}

TLS_OPTIONS 全部选项一览

选项	说明
CA_CERTS_FILE	CA 证书 PEM 路径，文件不存在时直接启动报错
VALIDATE	证书校验级别：NONE / OPTIONAL / REQUIRED
VERSION	TLS 协议版本：TLS、SSLV23、TLSV1、TLSV1_1、TLSV1_2
CLIENT_CERT_FILE / CLIENT_PRIVKEY_FILE	客户端证书与私钥路径（双向认证时）
CLIENT_PRIVKEY_PASSWORD	私钥密码，旧版 Python 不支持时会直接报错

所有 TLS 选项的合法性校验集中在 realms/modules/auth/ldap/init.py。注意：旧版 flask-ldap-login 风格的 OPT_X_TLS_REQUIRE_CERT 等写法在新版中已不再支持，需迁移到上述 TLS_OPTIONS。

六、常见启动报错速查

错误信息	原因与解决
Provide a LDAP configuration to enable LDAP authentication	启用了 LDAP 但没提供 LDAP 配置块
LDAP is required, but the LDAP URI has not been defined	缺少必填的 URI 项
For LDAP authentication, you need to provide BIND_DN and/or USER_SEARCH option	必须提供 BIND_DN 或 USER_SEARCH 至少一项
The 'VALIDATE' TLS option must be one of: ...	VALIDATE 取值不在 NONE / OPTIONAL / REQUIRED 中
CA_CERTS_FILE '...' does not exist	CA 证书文件路径写错或文件不存在

运行时登录失败（凭证错误、网络不通等）不会抛异常，而是写入 realms.auth.ldap 日志，可结合日志定位问题。

七、关键源码导读

• 配置校验与模块注册：realms/modules/auth/ldap/init.py
• 两种绑定方式与 TLS 连接：realms/modules/auth/ldap/models.py
• 登录表单定义：realms/modules/auth/ldap/forms.py
• 认证模块加载机制：realms/modules/auth/models.py
• 官方文档示例：README.md

完成以上配置后重启 Realms Wiki，打开登录页即可用 LDAP 账号登录，轻松实现与企业主目录的安全对接。