通讯录同步-AD

概述

本文档介绍如何将专属集成平台中的组织架构和用户数据推送到 Active Directory（AD）域。通过该功能，您可以将平台作为用户身份数据的主数据源，将用户数据自动同步至 AD 系统，实现 AD 中用户账号的自动创建、更新和生命周期管理。

适用场景

集中管理分发：以平台作为统一的用户管理中心，将用户数据分发到 AD

AD 账号自动化：新员工入职后平台自动在 AD 中创建账号和邮箱

密码统一管理：在平台中统一设置和更新 AD 用户密码

账号生命周期：离职员工自动在 AD 中禁用或删除账号

前提条件

AD 域管理信息：拥有 AD 服务器的域名/FQDN、端口号、BaseDN 和具有写入权限的管理员账号

平台管理员权限：拥有专属集成平台的管理员权限

网络要求：确保平台服务器可以访问 AD 服务器的 LDAP/LDAPS 端口

服务账户：准备一个 AD 专用服务账户，具有创建、修改和删除用户及组织单元的权限

TLS 证书（推荐）：若需进行密码操作，必须启用 TLS 加密连接

AD 配置信息准备清单

参数	说明	示例
服务器地址	AD 服务器的域名或 IP 地址	ad.company.com
服务器端口	LDAP 端口（389）或 LDAPS 端口（636）	636
BaseDN	AD 域根节点的基准 DN	DC=company,DC=com
管理员账号	具有管理权限的 AD 账号（含域名）	CN=svc_sync,CN=Users,DC=company,DC=com
管理员密码	管理员账号的密码	—

操作步骤

步骤 1：创建同步任务

登录专属集成平台管理控制台

在左侧导航栏选择「用户中心 → 通讯录同步」

点击页面右上角的「添加连接器」按钮

在弹出的平台选择面板中，选择「AD」图标

填写连接器名称，如"总部 AD 同步"

步骤 2：配置 AD 连接信息

在连接器配置页面，填写以下 AD 连接参数：

参数	说明	是否必填
名称	连接器名称	是
服务器地址	AD 服务器的 FQDN 或 IP 地址	是
服务器端口	LDAP 端口（389）或 LDAPS 端口（636）	是
BaseDN	AD 域根节点的基准 DN，如 DC=company,DC=com	是
TLS	是否启用 TLS 加密传输	否（密码操作必须开启）
管理员账号	具有写入权限的 AD 服务账户 DN	是
管理员密码	AD 服务账户密码	是
本地代理网关	是否使用代理网关	否

重要：如需同步用户密码（配置 unicodePwd 属性），必须启用 TLS 并使用 LDAPS 端口 636，否则密码设置操作将失败。

步骤 3：配置字段映射

用户属性映射

平台属性	AD 属性	数据类型	必填	说明
sub（用户ID）	sAMAccountName	String	是	用户登录名
name（姓名）	displayName	String	是	显示名称
name（姓名）	cn	String	是	通用名称
email（邮箱）	mail	String	是	电子邮件地址
mobile（手机号）	mobile	String	否	手机号码
position（职位）	title	String	否	职位头衔
department（部门）	department	String	否	部门名称
userPrincipalName	userPrincipalName	String	是	格式：`${username}@域名.com`
userAccountControl	userAccountControl	Number	是	账号控制标志，默认值 544
unicodePwd	unicodePwd	String	是*	用户密码（当配置 userAccountControl 时必须）

警告：* 配置 userAccountControl 时必须同时映射 unicodePwd，且必须启用 TLS 加密连接。服务账户需具有修改密码的权限。

userAccountControl 常用值

值	含义
512	正常启用账号
514	禁用账号
544	启用账号且密码永不过期
546	禁用账号且密码永不过期

部门属性映射

平台属性	AD 属性	数据类型	必填	说明
id（部门ID）	ou	String	是	组织单元名称
name（部门名称）	name	String	是	组织单元显示名
parent_id（父部门ID）	—	String	是	通过 distinguishedName 构建层级

步骤 4：配置同步规则

参数	说明	建议配置
同步范围	全部 / 部分	根据业务需要选择
根组织 ID	组织架构同步起始节点	全量填"1"，部分填具体部门 ID
同步方式	自动增量 / 自动全量 / 手动全量	初始化用手动全量，运行期用自动增量
同步周期	执行频率	建议初始"手动"，稳定后"每6小时"
删除用户阈值	触发删除保护的阈值	小型企业 8~~10%，中大型企业 3~~5%

提示：由于 AD 同步涉及系统层面的账号操作，建议首次同步时选择手动全量模式，在业务低峰期执行，并提前做好 AD 备份。

步骤 5：执行同步并验证

点击「保存并同步」触发首次同步

在同步日志中确认创建/更新/删除操作的结果

使用 AD 管理工具（如 Active Directory 用户和计算机）验证：

新建用户是否在正确的 OU 下

用户属性（displayName、mail、title 等）是否正确

账号状态（启用/禁用）是否符合预期

验证与测试

连接测试

在连接器配置页面，点击「测试连接」

系统尝试使用配置的服务器地址、端口和管理员账号绑定 AD

测试成功后显示"连接成功"

同步结果验证清单

验证项	验证方法	预期结果
用户创建	在 AD 用户和计算机中查看对应 OU	用户存在于正确 OU 下，属性正确
用户更新	修改平台用户手机号后触发同步	AD 中 mobile 属性已更新
账号状态	禁用平台用户后同步	AD 中 userAccountControl 值变为 514
部门同步	在平台创建新部门后同步	AD 中对应 OU 已创建
密码设置	需要 TLS 连接	unicodePwd 正确设置

同步日志常见错误码

错误信息	可能原因	解决方法
连接失败	服务器地址或端口错误	检查 AD 服务器连通性
认证失败（LDAP 49）	管理员账号或密码错误	核对账号 DN 和密码
权限不足（LDAP 50）	服务账户权限不够	检查账户对目标 OU 的写入权限
无法设置密码	未启用 TLS 或权限不足	启用 TLS 并使用 636 端口
userPrincipalName 格式无效	UPN 格式不正确	检查 UPN 映射表达式

常见问题

Q1：同步时提示"无法设置密码"（unicodePwd 相关）

可能原因：

未启用 TLS 加密连接

服务账户没有修改密码的权限

密码不符合 AD 复杂度要求

解决方法：

开启 TLS 选项，确保服务器端口使用 636（LDAPS）

在 AD 中为服务账户授予"重置密码"权限

确保生成的密码满足 AD 密码策略（长度、复杂度要求）

Q2：同步后用户在 AD 中找不到

可能原因：

BaseDN 配置错误，用户被创建到了错误的位置

目标 OU 不存在，创建操作失败

根组织 ID 配置不当

解决方法：

检查 BaseDN 配置是否正确

确认目标 OU 已存在或在同步前先创建组织架构

使用 AD 管理工具搜索用户 sAMAccountName 确认是否已在其他位置创建

Q3：同步后 userPrincipalName 格式不正确

可能原因：UPN 映射表达式配置错误，域名部分不正确。

解决方法：
检查 userPrincipalName 的映射配置，格式应为 ${user.username}@域名.com。确保域名部分是有效的 DNS 域名且与 AD 域保持一致。

Q4：组织架构层级与平台不一致

可能原因：AD 中 OU 层级与平台部门层级的映射关系未正确建立。

解决方法：

确认根组织 ID 配置正确

检查部门 parent_id 映射是否正确

执行一次全量同步以重建完整的 OU 层级结构

概述#

适用场景#

前提条件#

AD 配置信息准备清单#

操作步骤#

步骤 1：创建同步任务#

步骤 2：配置 AD 连接信息#

步骤 3：配置字段映射#

用户属性映射#

userAccountControl 常用值#

部门属性映射#

步骤 4：配置同步规则#

步骤 5：执行同步并验证#

验证与测试#

连接测试#

同步结果验证清单#

同步日志常见错误码#

常见问题#

Q1：同步时提示"无法设置密码"（unicodePwd 相关）#

Q2：同步后用户在 AD 中找不到#

Q3：同步后 userPrincipalName 格式不正确#

Q4：组织架构层级与平台不一致#

概述

适用场景

前提条件

AD 配置信息准备清单

操作步骤

步骤 1：创建同步任务

步骤 2：配置 AD 连接信息

步骤 3：配置字段映射

用户属性映射

userAccountControl 常用值

部门属性映射

步骤 4：配置同步规则

步骤 5：执行同步并验证

验证与测试

连接测试

同步结果验证清单

同步日志常见错误码

常见问题

Q1：同步时提示"无法设置密码"（unicodePwd 相关）

Q2：同步后用户在 AD 中找不到

Q3：同步后 userPrincipalName 格式不正确

Q4：组织架构层级与平台不一致