配置 AD 通讯录同步

本文面向身份集成管理员，介绍如何将平台中的用户和部门同步到 Microsoft Active Directory（AD）。完成配置后，你可以按计划或手动执行同步，并从平台同步日志与 AD 两端验证结果。

本文不包括 AD 域、组织单位（OU）、网络代理或证书的建设过程。

适用版本与验证边界

本文根据 6.7.1 系列前后端源码、testo 测试环境页面和 Microsoft 官方说明整理。真实 AD 端到端结果尚未完成验证；正式发布前还需核对实际构建版本，并在专用测试 OU 中复核连接、映射行和同步结果。

准备工作

开始前，请准备以下条件：

拥有通讯录同步连接器的查看、创建和更新权限。

准备专用 AD 服务账号，并仅授予目标 OU 所需的最小创建、读取、修改、禁用或删除权限。

获取 AD 服务器地址、端口、BaseDN、管理员账号和管理员密码。

确认平台服务或代理网关能够访问 AD 的 LDAP 或 LDAPS 端口。

如需写入密码，准备受信任的 TLS 证书，并确认服务账号具有重置密码权限。

建立专用测试 OU 和少量测试用户，首次同步前备份目标目录或准备可恢复基线。

AD 连接信息清单

参数	说明	示例
服务器地址	AD 域控制器的 FQDN 或 IP 地址	`ad.example.com`
服务器端口	LDAP 或 LDAPS 服务端口	`389` 或 `636`
BaseDN	同步操作使用的目录基准 DN	`DC=example,DC=com`
管理员账号	对目标 OU 具有所需权限的专用服务账号	`CN=svc_sync,OU=Service Accounts,DC=example,DC=com`
管理员密码	专用服务账号的密码	不要记录在文档、截图或工单中
代理网关	AD 无法被平台直接访问时使用的代理网关	按部署网络选择

先在测试 OU 验证

AD 同步会创建、覆盖、禁用或删除目录对象。首次配置不要直接选择生产 OU，也不要在尚未确认映射和删除保护时开启周期性全量同步。

操作步骤

步骤 1：创建 AD 同步连接器

登录平台管理控制台。

进入「用户中心 > 通讯录同步」。

打开同步连接器库，选择「AD」。

进入「基本信息」页签。

在同步连接器库中选择 Windows AD，进入连接器配置页面。

创建后，连接器配置依次包含「基本信息」「同步策略」「属性映射」「待处理任务」「同步日志」和「告警通知」页签。

步骤 2：配置 AD 连接信息

在「基本信息」页签填写以下内容：

字段	是否必填	配置说明
名称	是	使用能够区分目录和用途的名称，例如“总部 AD 测试 OU”。
BaseDN	是	填写本次连接和目录操作使用的基准 DN。先确认 DN 层级与目标 OU 规划一致。
TLS	否	新建连接器时默认关闭。涉及密码写入或凭据保护时应启用加密连接。
管理员账号	是	填写专用 AD 服务账号。账号格式以目标 AD 的绑定方式为准。
管理员密码	是	填写服务账号密码；不要在截图或交付材料中保留明文。
服务器地址	是	填写域控制器 FQDN 或 IP 地址。推荐使用与证书匹配的 FQDN。
服务器端口	是	新建连接器默认值为 `389`。启用 TLS 时，应按 AD 实际监听方式填写对应端口，不能只修改 TLS 开关。
代理网关	否	平台不能直连 AD 时选择已部署且连通的代理网关。

填写完成后，进入下一步。平台在新建连接器过程中会测试连接；只有连接配置可用，才应继续创建连接器和配置属性映射。

使用非敏感示例值确认名称、BaseDN、TLS、管理员账号、服务器地址、端口和代理网关字段；管理员密码不会明文显示。

密码写入要求

AD 的 unicodePwd 修改需要使用满足要求的加密连接，且服务账号必须拥有相应权限。是否映射密码应由实际账号初始化方案决定，不要把 unicodePwd 当作所有场景的默认必填字段。

步骤 3：配置同步策略

在「同步策略」页签按业务范围和风险等级配置以下内容：

同步对象与覆盖策略

字段	选项或含义	配置建议
同步范围	「用户和部门」或「仅同步用户」	需要在 AD 中维护 OU 层级时选择「用户和部门」；AD 已由其他系统维护 OU 时评估选择「仅同步用户」。
强制创建	控制未匹配对象是否允许在 AD 中创建	首次验证先限定到测试 OU 和测试用户，再决定是否开启。
组织架构同步模式	「全量」或「部分」	首次上线建议选择「部分」，用白名单限制到测试范围。
组织同步白名单	仅在「部分」模式下显示	填写允许同步的组织范围。
组织同步黑名单	仅在「部分」模式下显示	排除不应进入 AD 的组织范围。
用户筛选规则	按连接器页面提供的条件筛选用户	将服务账号、测试账号或其他特殊账号排除在自动同步范围之外。

AD 和 LDAP 连接器不显示下游根组织 ID 字段。同步起点应通过 BaseDN、组织范围以及属性映射共同控制。

Windows AD 同步策略页显示同步范围、强制创建、组织架构同步模式和筛选规则

先确认同步范围、强制创建、组织架构同步模式和筛选规则；Windows AD 页面不显示下游根组织 ID。

执行方式与删除保护

字段	选项或含义	配置建议
同步方式	自动增量同步、手动全量同步、自动全量同步	首次验证使用手动全量同步；验证稳定后再评估自动增量或自动全量。
同步周期	自动模式下的执行间隔	可选间隔包括 15、30、60、120、180、360、720 和 1440 分钟。按数据时效与 AD 承载能力选择。
开始时间	自动模式的计划开始时间	选择业务低峰时段，并避开 AD 备份、补丁或批处理窗口。
删除用户阈值	单次同步允许删除的用户数量上限	这是人数，不是百分比。超过阈值时，连接器不执行删除操作。

删除用户阈值的取值规则：

0：同步时不删除用户。

正整数：当数据源删除用户数大于该值时，本次不执行删除。

-1：不设置删除上限，风险最高，仅在有额外保护和明确审批时使用。

删除阈值不是百分比

不要填写“3%”或“5%”一类比例。首次上线建议设为 0，先通过日志和待处理任务确认删除对象，再根据组织的变更规模制定人数上限。

切换到手动全量同步后，页面显示删除用户阈值；该值是单次允许删除的人数上限。

步骤 4：配置属性映射

连接测试并创建连接器后，进入「属性映射」页签。AD 连接器包含「用户」和「部门」两类映射；页面展示的源字段、目标字段和已有默认值以当前租户运行时返回结果为准。

用户属性映射入口与表格结构；通过连接测试并创建连接器后，页面才会加载当前 AD 的运行时属性行。

用户属性映射

先确定稳定唯一标识，再配置展示和业务属性。常见 AD 目标属性包括：

AD 属性	用途	配置要点
`sAMAccountName`	兼容登录名	保证目标域内唯一，并符合 AD 长度和字符限制。
`userPrincipalName`	UPN 登录名	通常形如 `username@example.com`；确认后缀已在 AD 中配置。
`displayName`	用户显示名称	可映射平台姓名，但不要把它作为唯一匹配键。
`mail`	邮箱	确认源字段格式和空值策略。
`mobile`	手机号	仅在业务需要且数据合规时映射。
`title`	职位	明确离职、调岗或源值为空时是否允许覆盖。
`userAccountControl`	账号状态和控制标志	该属性由多个位标志累加组成，不要只根据单一数字覆盖其他已有标志。
`unicodePwd`	密码写入	仅在账号初始化方案需要时配置，并满足加密连接、权限和密码策略要求。

userAccountControl 不是单一状态枚举。例如，正常账号标志为 512，禁用账号通常是在现有值上增加 2，得到 514。若目标 AD 还使用“密码永不过期”等标志，应先读取并保留需要的位，避免用固定值覆盖其他策略。

部门属性映射

部门映射用于构建或更新 OU 层级。配置前确认：

平台部门的稳定标识、名称和父子关系如何映射到 AD。

目标 OU 是允许自动创建，还是必须预先存在。

部门更名、移动或删除时，AD 中对应对象的处理策略。

相同名称的部门是否可能出现在不同层级；不要只用可变名称作为唯一匹配依据。

部门属性映射入口与表格结构；通过连接测试并创建连接器后，页面才会加载当前 AD 的运行时属性行。

完成映射后保存。首次配置不要一次性加入大量可选字段；先验证唯一标识、层级和账号状态，再逐步增加业务属性。

步骤 5：执行首次同步

确认同步范围只包含专用测试 OU 和少量测试用户。

确认删除用户阈值为 0，且尚未启用高风险自动任务。

保存属性映射，并触发首次手动全量同步。

打开「同步日志」，核对创建、更新、跳过和失败数量。

若出现待处理删除任务，先核对对象清单，不要直接批准批量删除。

在 AD 端读回对象和属性，完成双端验证后再扩大同步范围。

验证结果

平台显示“同步成功”不能单独证明 AD 已正确更新。请同时完成平台侧和 AD 侧读回：

验证项	平台侧检查	AD 侧检查	预期结果
连接与任务	连接器状态、任务开始和结束时间	域控制器可访问，服务账号没有异常锁定	任务按预期执行，无连接或认证错误
用户创建	日志中的新增数量和对象标识	在测试 OU 使用 AD 用户和计算机或 `Get-ADUser` 查询	用户只出现在预期 OU，唯一标识正确
用户更新	日志中的更新字段和结果	读回 `displayName`、`mail`、`mobile`、`title` 等已映射属性	仅预期字段发生变化，空值策略符合设计
账号状态	日志中的状态变更	读回 `userAccountControl` 并按位判断	启用、禁用及其他标志均符合策略
部门层级	日志中的部门新增或更新	查看 OU 的 DN 与父子层级	OU 位于预期 BaseDN 下，层级无错位
删除保护	日志或待处理任务中的删除数量	确认生产对象未被删除	超过阈值时删除被阻止，阈值为 `0` 时不删除
失败恢复	记录失败对象与错误原因	修正后只对测试对象重试并再次读回	重试幂等，不产生重复账号或错误 OU

如果配置了密码写入，只能用隔离测试账号验证登录或重置结果；不得尝试读回或记录明文密码。

常见问题

连接测试失败

依次检查服务器地址和端口、DNS 解析、平台或代理网关到 AD 的网络连通性、TLS 证书信任、BaseDN、服务账号格式和密码。若 LDAP 返回认证或权限错误，再到 AD 审计日志核对失败原因。

用户未创建到 AD

检查强制创建是否开启、组织同步模式和白名单是否包含该用户、黑名单或筛选规则是否排除了该用户，以及服务账号是否有目标 OU 的创建权限。随后根据同步日志中的对象标识定位失败记录。

UPN 或登录名不正确

检查 userPrincipalName 的拼接规则、UPN 后缀是否已在 AD 配置，以及 sAMAccountName 是否唯一。不要用姓名或邮箱显示值代替稳定匹配键。

删除操作没有执行

检查同步方式和删除用户阈值。当数据源删除人数大于正整数阈值，或阈值设置为 0 时，连接器会阻止删除。先在待处理任务和同步日志中核对对象，再调整策略。

密码写入失败

确认连接满足 AD 对密码修改的加密要求，服务账号具有重置密码权限，密码符合域复杂度策略，并检查目标账号是否受保护或继承了特殊权限。

停用或回滚

先停用连接器或自动调度，阻止新的同步任务。

导出或记录当前配置、同步日志、失败对象和待处理任务，保留排查证据。

在专用测试对象上恢复上一版映射或策略，并重新读回 AD 结果。

连接器删除前必须先停用；删除连接器不会自动撤销已经写入 AD 的对象和属性。

准备工作#

AD 连接信息清单#

操作步骤#

步骤 1：创建 AD 同步连接器#

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

步骤 3：配置同步策略#

步骤 4：配置属性映射#

步骤 5：执行首次同步#

验证结果#

常见问题#

连接测试失败#

用户未创建到 AD#

UPN 或登录名不正确#

删除操作没有执行#

密码写入失败#

停用或回滚#