Wekan LDAP AD Simple AuthActive Directory 简单认证配置完整指南【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan本文面向需要在自托管 Wekan基于 Meteor 的开源看板中对接微软 Active DirectoryAD的企业管理员讲解如何通过LDAP_AD_SIMPLE_AUTH开启 AD 简单认证让用户直接用用户名域名与自己的密码完成 LDAP 绑定登录并配合LDAP_USER_AUTHENTICATION、LDAP_DEFAULT_DOMAIN在 Docker Compose 与 Snap 两种部署形态下完成最小可用配置。读完本文你将掌握 AD Simple Auth 的核心原理、完整参数语义、两种平台的启用/禁用方法以及如何通过 LDAP Sync 与搜索过滤器加固登录体验。一、什么是 AD Simple Auth为什么需要它在标准的 LDAP 认证流程中Wekan 通常先使用一个管理员搜索账号绑定 LDAP 服务器再在LDAP_BASEDN指定的目录子树下搜索用户最后用搜索到的用户 DN 去验证密码。这种模式需要你明确配置 Base DN并维护一个专门的搜索账号。而 Active Directory 提供了一种更简洁的简单认证Simple Auth方式直接使用用户名域名作为绑定 DN用该用户自己的密码去完成 LDAP 绑定。Wekan 用环境变量LDAP_AD_SIMPLE_AUTH控制这一行为开启后LDAP_BASEDN不再是必需项——用户定位不依赖目录树位置域账号本身就能完成认证认证路径大幅缩短一次绑定即完成校验无需先搜索再二次绑定。在 packages/wekan-ldap/server/ldap.js 的bindUserIfNecessary()中可以看到核心实现逻辑/* if SimpleAuth is configured, the BaseDN is not needed */ if (!this.options.BaseDN !this.options.AD_Simple_Auth) throw new Error(BaseDN is not provided); // Escape the username to prevent LDAP injection in DN construction const escapedUsername escapedToHex(username); var userDn ; if (this.options.AD_Simple_Auth true || this.options.AD_Simple_Auth true) { userDn ${escapedUsername}${this.options.Default_Domain}; } else { userDn ${this.options.User_Authentication_Field}${escapedUsername},${this.options.BaseDN}; }从源码结构可以清晰看出两条绑定路径的分野开启 Simple Auth 后绑定 DN 被构造成用户名默认域名即 UPN 格式而普通 LDAP 认证则仍走认证字段用户名,BaseDN的传统 DN 拼接方式。同时注意escapedToHex()会对用户名做转义处理ldap.js防止在 DN 构造中注入恶意字符。与 LDAP 通用认证的关系LDAP_AD_SIMPLE_AUTH不是独立于 LDAP 的另一种登录体系它是LDAP 用户认证的一种特化形态。开启时通常要配合LDAP_USER_AUTHENTICATIONtrue表示放弃管理员搜索账号改用登录用户自己的凭据进行绑定。两者共同作用后LDAP_BASEDN、LDAP_AUTHENTIFICATION管理员绑定、LDAP_AUTHENTIFICATION_USERDN、LDAP_AUTHENTIFICATION_PASSWORD等搜索账号相关配置都不再需要配置面大幅收敛。二、核心环境变量与参数语义2.1LDAP_AD_SIMPLE_AUTH类型布尔值示例值true作用开启 AD 简单认证。启用后LDAP_BASEDN不再需要。底层影响该变量在 packages/wekan-ldap/server/ldap.js 被读取并存入this.options.AD_Simple_Auth随后直接决定bindUserIfNecessary()中用户 DN 的构造方式UPN 拼接 vs 字段BaseDN 拼接。2.2LDAP_USER_AUTHENTICATION类型布尔值默认false默认使用管理员搜索账号作用true时改用登录用户自己的用户名与密码进行 LDAP 绑定而不再使用管理员密钥绑定。与 AD Simple Auth 的组合使用 AD Simple Auth 时必须同时设为true此时绑定用户就是登录用户本人LDAP_BASEDN不再需要。底层影响该变量在 ldap.js 被读入User_Authentication并在bindUserIfNecessary()中作为是否进行用户绑定、以及是否抛出 BaseDN is not provided 异常的开关。2.3LDAP_USER_AUTHENTICATION_FIELD类型字符串默认uid作用仅在使用非 Simple Auth的用户认证LDAP_USER_AUTHENTICATIONtrue且LDAP_AD_SIMPLE_AUTH未开启时生效用于指定查找用户的字段。例如在 AD 场景可设为sAMAccountName。开启 AD Simple Auth 后该字段不参与 DN 构造因为它直接使用用户名域名。2.4LDAP_DEFAULT_DOMAIN类型字符串示例值mydomain.com双重作用见 docker-compose.yml 与 snap-src/bin/config构造绑定 UPNAD Simple Auth 开启时默认域名会被追加到登录名之后形成形如john.doemydomain.com的绑定账号兜底生成邮箱当 LDAP 条目中无法映射出邮箱例如LDAP_SYNC_USER_DATA_FIELDMAP未正确映射、且mail属性缺失时Wekan 会用用户名默认域名合成新用户的邮箱。第二个作用在 packages/wekan-ldap/server/sync.js 的addLdapUser()中有直接体现} else if (ldapTextValue(ldapUser.getLDAPValue(mail)).includes()) { // #6481: case-insensitive, matching the fieldmap path above. userObject.email ldapTextValues(ldapUser.getLDAPValue(mail))[0]; } else if (LDAP.settings_get(LDAP_DEFAULT_DOMAIN) ! ) { userObject.email ${ username || uniqueId.value }${ LDAP.settings_get(LDAP_DEFAULT_DOMAIN) }; } else { const error new Meteor.Error(LDAP-login-error, LDAP Authentication succeded, there is no email to create an account. Have you tried setting your Default Domain in LDAP Settings?); ... }也就是说在 AD 目录的mail属性缺失、且字段映射又没有兜底的情况下LDAP_DEFAULT_DOMAIN是保证新用户能够被创建的最后一道防线——否则登录会以 there is no email to create an account 报错失败。2.5 配套的搜索过滤器与邮箱字段Wekan 官方针对 AD Simple Auth 给出如下推荐配套设置- LDAP_USER_SEARCH_FILTER(objectClassuser) - LDAP_EMAIL_FIELDmailLDAP_USER_SEARCH_FILTER附加的 LDAP 搜索过滤器。官方推荐的(objectClassuser)会把搜索范围限定在 AD 的user对象类上避免把计算机账户、组对象等非用户条目误当作登录用户。该值在 ldap.js 中被escapedToHex()预处理后存入User_Search_Filter并在getUserFilter()ldap.js中与用户名条件组合成形如((objectClassuser)(sAMAccountName...))的复合过滤器最终与登录名条件取 AND 关系。LDAP_EMAIL_FIELD指定 LDAP 目录中承载邮箱地址的属性名AD 场景通常为mail。该字段在登录成功后由getLdapEmail()packages/wekan-ldap/server/sync.js读取用于用户邮箱的匹配与新用户创建。注以上两行来自 LDAP-AD-Simple-Auth.md 中引用的 issue #3908 评论区推荐设置其原始 PR#3909由 indika-dev 贡献后续 xet7 在 commit fe40f35 中为该功能补齐了除 Sandstorm 外的全部 Wekan Standalone 平台的设置项与本文档说明。仓库 docker-compose.yml 中也保留了LDAP_USER_SEARCH_FILTER、LDAP_USER_SEARCH_FIELDAD 场景推荐sAMAccountName、LDAP_EMAIL_FIELDmail的完整注释示例。2.6 若启用 LDAP Sync请同步调整文档明确提醒如果同时使用 LDAP Sync 功能相关同步设置也需要一并调整。例如LDAP_SYNC_USER_DATA_FIELDMAP默认示例{cn:name, mail:email}、LDAP_SYNC_ADMIN_STATUS/LDAP_SYNC_ADMIN_GROUPS管理员状态同步、LDAP_SYNC_GROUP_ROLES组到角色同步、LDAP_SYNC_ORGANIZATIONS/LDAP_SYNC_TEAMS组织/团队同步等。这些设置在 docker-compose.yml 中有完整注释登录时的同步逻辑见 packages/wekan-ldap/server/loginHandler.js。三、AD Simple Auth 的登录认证流程结合 packages/wekan-ldap/server/loginHandler.jsAD Simple Auth 开启后的登录链路可以归纳为入口判断Accounts.registerLoginHandler(ldap, ...)收到携带ldap/ldapOptions的登录请求若LDAP_ENABLE ! true直接回退到默认账号系统。建立连接ldap.connect()按LDAP_ENCRYPTIONtls/starttls/off构造ldaps://或ldap://URL 并建立连接。用户绑定与搜索当LDAP_USER_AUTHENTICATIONtrue时调用bindUserIfNecessary(username, password)AD Simple Auth 开启 → 绑定 DN 为用户名默认域名LDAP_BASEDN未配置也不报错未开启 → 绑定 DN 为LDAP_USER_AUTHENTICATION_FIELD用户名,LDAP_BASEDN此时若 BaseDN 缺失会抛出BaseDN is not provided。 绑定成功后用searchUsers(username)按过滤器检索该用户条目。密码校验非用户认证模式下管理员绑定后执行ldap.auth(users[0].dn, password)校验用户密码用户认证模式下绑定成功本身即视为密码校验通过。登录态处理找到或创建对应用户生成登录 token 返回若用户已存在但authenticationMethod不是ldap且未开启LDAP_MERGE_EXISTING_USERS则拒绝登录提示已有同名 Wekan 账号。同步钩子登录成功后可触发管理员状态、组角色、组织/团队、用户数据字段等同步loginHandler.js。四、Docker 部署docker-compose.yml 配置在 docker-compose.yml 中官方已经预置了完整的注释块。启用方法取消对应行注释注意不要为变量值加单引号参见 docker-compose.yml 的提示。最小启用配置如下#----------------------------------------------------------------- # LDAP AD Simple Auth # # Set to true, if you want to connect with Active Directory by Simple Authentication. # When using AD Simple Auth, LDAP_BASEDN is not needed. # # Example: - LDAP_AD_SIMPLE_AUTHtrue # # LDAP User Authentication # # a) Option to login to the LDAP server with the users own username and password, instead of # an administrator key. Default: false (use administrator key). # # b) When using AD Simple Auth, set to true, when login user is used for binding, # and LDAP_BASEDN is not needed. # # Example: - LDAP_USER_AUTHENTICATIONtrue # # Which field is used to find the user for the user authentication. Default: uid. #- LDAP_USER_AUTHENTICATION_FIELDuid # # LDAP Default Domain # # a) In case AD SimpleAuth is configured, the default domain is appended to the given # loginname for creating the correct username for the bind request to AD. # # b) The default domain of the ldap it is used to create email if the field is not map # correctly with the LDAP_SYNC_USER_DATA_FIELDMAP # # Example : - LDAP_DEFAULT_DOMAINmydomain.com # #-----------------------------------------------------------------同时建议一并启用 LDAP 基础连接与搜索相关变量对应 docker-compose.yml 与 docker-compose.yml- LDAP_ENABLEtrue - LDAP_PORT389 - LDAP_HOSTlocalhost # 改为你的 AD 服务器地址 #- LDAP_USER_SEARCH_FILTER(objectClassuser) - LDAP_USER_SEARCH_FIELDsAMAccountName - LDAP_EMAIL_FIELDmail配置要点将示例中的mydomain.com全部替换为你实际的 AD 域名如corp.example.com若使用 LDAPS将LDAP_ENCRYPTION设为tls对应加密模式ldaps://并配置LDAP_CA_CERT、LDAP_REJECT_UNAUTHORIZEDdocker-compose.ymlLDAP_BASEDN、LDAP_AUTHENTIFICATION*等搜索账号配置在 Simple Auth 模式下可以留空不配除 docker-compose.yml 外该功能在其它 Standalone 部署形态如 start-wekan.sh 环境变量脚本、Dockerfile、各 FerretDB 变体的 compose 文件中均有对应设置项同一套变量名直接复用。五、Snap 部署snap set 命令启用与禁用Wekan Snap 包使用sudo snap set以kebab-case键名管理配置键名定义见 snap-src/bin/config、snap-src/bin/config、snap-src/bin/config。Wekan标准版启用sudo snap set wekan ldap-ad-simple-authtrue sudo snap set wekan ldap-user-authenticationtrue sudo snap set wekan ldap-default-domainmydomain.com禁用sudo snap unset wekan ldap-ad-simple-auth sudo snap unset wekan ldap-user-authentication sudo snap unset wekan ldap-default-domainWekan Gantt GPL甘特图版本启用sudo snap set wekan-gantt-gpl ldap-ad-simple-authtrue sudo snap set wekan-gantt-gpl ldap-user-authenticationtrue sudo snap set wekan-gantt-gpl ldap-default-domainmydomain.com禁用sudo snap unset wekan-gantt-gpl ldap-ad-simple-auth sudo snap unset wekan-gantt-gpl ldap-user-authentication sudo snap unset wekan-gantt-gpl ldap-default-domain说明Snap 的ldap-default-domain与 Docker 的LDAP_DEFAULT_DOMAIN语义完全一致同样承担构造 UPN 绑定账号与兜底生成邮箱双重职责Snap 键的默认值定义可在 snap-src/bin/config 中查阅如ldap-user-authentication默认false、ldap-user-authentication-field默认uid、ldap-user-search-field默认空需要 LDAP 日志排查时Snap 同样支持ldap-log-enabled等键完整键清单见该配置文件。六、验证与排错建议确认配置生效Docker 下重启容器后检查 Wekan 日志中Init setup、Connecting ldap(s)://host:port等行ldap.jsSnap 下用sudo snap get wekan查看已设置键值。用户登录使用 AD 账号如john.doe配合密码登录注意此时不需要输入mydomain.com后缀——域名由LDAP_DEFAULT_DOMAIN自动拼接从 ldap.js 的 DN 构造逻辑可以确认这一点。首次登录建号如果目录中mail属性为空且字段映射未兜底登录会报 there is no email to create an account此时应优先检查LDAP_EMAIL_FIELDmail、LDAP_SYNC_USER_DATA_FIELDMAP与LDAP_DEFAULT_DOMAIN三者是否齐备对应 sync.js 的建号分支。组过滤排错若开启了LDAP_GROUP_FILTER_ENABLE导致所有登录被拒可检查组的存放子树是否需要单独设置LDAP_GROUP_BASEDN组的查找子树默认等于用户 BaseDN参见 ldap.js 的groupBaseDN()。回退策略若希望 LDAP 认证失败时回退到 Wekan 本地账号可设置LDAP_LOGIN_FALLBACKtruedocker-compose.yml对应实现见 loginHandler.js。七、相关文档与扩展阅读LDAP 完整功能总览包含组过滤、同步、加密等全部环境变量docs/Features/Login/LDAP.md本主题的原始英文文档docs/Features/Login/LDAP-AD-Simple-Auth.mdDocker 编排示例docker-compose.ymlSnap 支持键定义snap-src/bin/config环境变量启动脚本start-wekan.sh核心实现LDAP 客户端与绑定逻辑 packages/wekan-ldap/server/ldap.js、登录处理器 packages/wekan-ldap/server/loginHandler.js、用户同步与建号 packages/wekan-ldap/server/sync.js相关变更历史PR #3909功能引入、commit fe40f35补齐各平台设置项与文档可参见 old-CHANGELOG/2019.md。【免费下载链接】wekanThe Open Source kanban, built with Meteor. GitHub issues/PRs are only for FLOSS Developers, not for support, support is at https://wekan.fi/commercial-support/ . PR source translation to imports/i18n/data/en.i18n.json, other translations at https://app.transifex.com/wekan/wekan项目地址: https://gitcode.com/GitHub_Trending/we/wekan创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
