如何实现 Vault 与 Active Directory 的集成认证与权限同步？

在企业基础设施里，HashiCorp Vault 负责保管密钥与证书，而 Active Directory（AD）往往是统一的身份源。让 Vault 直接信任 AD 中的账号，可以避免在 Vault 里再建一套本地用户，也能利用已有的组结构做细粒度授权。Vault 通过内置的 LDAP 认证方法对接 AD，底层走标准 LDAP 协议，因此只要网络通、账号有读取目录权限，集成并不复杂。

启用 LDAP 认证后端并配置连接参数

Vault 默认没有开启 LDAP 认证，需要先通过命令行或 API 启用。启用后，要写入一组连接配置，告诉 Vault 去哪台域控、用什么账号搜人、用哪个字段当用户名。这里最容易错的是 userdn 与 groupdn 的基准路径，以及 upndomain 是否设置。如果 AD forest 是 corp.local，用户容器在 OU=Users,DC=corp,DC=local，那就应照实填写。

下面是一段在 Linux 上用 vault 命令行配置 LDAP 后端的示例，其中 binddn 使用的是有目录读取权的服务账号。注意端口用 636 代表 LDAPS 加密，若内网有证书信任问题可先临时用 389 调试。配置成功后，Vault 并不会立即导入用户，只在有人登录时才去 AD 校验。

# 启用 ldap 认证方法，挂载到 default 路径 ldap
vault auth enable ldap

# 写入连接配置
vault write auth/ldap/config 
    url="ldaps://dc01.corp.local:636" 
    binddn="CN=svc_vault,OU=Service,DC=corp,DC=local" 
    bindpass="StrongPassw0rd" 
    userdn="OU=Users,DC=corp,DC=local" 
    groupdn="OU=Groups,DC=corp,DC=local" 
    upndomain="corp.local" 
    userattr="sAMAccountName" 
    groupfilter="(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))" 
    token_policies="default"

上面的 groupfilter 使用了 AD 的递归成员查询语法，能解决用户嵌套在子组里的情况。如果只写普通 member 匹配，深层组中的人可能登录后拿不到策略。另外 token_policies 给的是默认策略，具体权限应交给组映射覆盖，不要在这里写死过宽策略。

将 AD 组映射为 Vault 策略实现权限同步

LDAP 登录成功后，Vault 会拿到该用户所属的 AD 组名。下一步是在 auth/ldap/groups/ 下为每个组建立映射，绑定对应的 Vault policy。这样当 HR 组的人登录，就自动获得 hr-policy，运维组获得 ops-policy，无需手动给个人授权，离职只需在 AD 禁用账号即可生效。

假设 AD 里有 VaultReaders 与 VaultAdmins 两个组，分别要只读与全量权限。先写好两条策略文件，再用命令行把组与策略关联。下面示例展示策略内容与组映射命令，策略用 path 控制能读哪些密钥引擎。

# 只读策略 readonly.hcl
path "secret/data/*" {
  capabilities = ["read", "list"]
}

# 管理员策略 admin.hcl
path "secret/*" {
  capabilities = ["create", "read", "update", "delete", "list"]
}

# 写策略到 Vault
vault policy write readonly readonly.hcl
vault policy write admin admin.hcl

# 映射 AD 组到策略
vault write auth/ldap/groups/VaultReaders policies=readonly
vault write auth/ldap/groups/VaultAdmins policies=admin

这种映射方式的好处是权限随 AD 组变动而自动调整。若有人在 AD 被移出 VaultAdmins，下次登录 Vault 便不再拥有 admin 策略，不必到 Vault 逐个回收。需要注意组名在 Vault 里默认区分大小写，且与 AD 中 cn 完全一致，含空格的组名也要原样写。

当企业组特别多时，可以借助 Terraform 的 vault_ldap_auth_backend_group 资源做代码化管理，避免手工命令遗漏。同时建议在 AD 侧建专门 Vault 用的组前缀，如 Vault_，减少和普通业务组混淆，也方便 groupdn 下用 OU 隔离。

常见连接故障与排错思路

实际对接时，最多的问题是登录报 invalid username or password，但账号密码明明对。这类错八成是 userdn 范围写错，导致 Vault 拼出的搜索基不对，AD 里根本没搜到人。打开 Vault 服务端日志看 LDAP search base 即可确认。另一个隐性坑是 upndomain 没设，用户用 sAMAccountName 登录时 Vault 不会拼 UPN，某些域控拒绝匿名绑定搜人。

证书类错误也频繁：用 LDAPS 却没在 Vault 机器信任企业根证书，会报 x509 相关错误。此时要么把根证放入系统信任库，要么在 config 里加 certificate=-----BEGIN CERTIFICATE-----... 字段。不建议为图省事关掉 TLS 校验，内网嗅探可轻松拿到 binddn 密码。

# 用 ldapsearch 在 Vault 主机验证连通与搜人
ldapsearch -H ldaps://dc01.corp.local:636 
    -D "CN=svc_vault,OU=Service,DC=corp,DC=local" 
    -w "StrongPassw0rd" 
    -b "OU=Users,DC=corp,DC=local" 
    "(sAMAccountName=alice)"

# 若上面能出结果，Vault 配置中的 dn 与 url 基本就正确

还有一类权限错位是登录成功但啥也干不了，这通常是组映射没写或 policy 路径写错。可用 vault token lookup 看当前 token 的 policies 列表，确认是否包含期望策略。若只有 default，说明组名不匹配或映射命令漏执行。排错时建议先给 token_policies 设一个窄权限策略，登录后逐步放宽，能缩小故障面。

最后提醒，Vault 的 LDAP 后端不支持 AD 密码过期自动提醒，用户密码改了不影响已发 token，但下次登录必须用新密码。若企业有定期改密策略，配合 Vault 的 token 短时效与续期接口，能兼顾安全与可用。整体看，Vault 与 AD 集成核心就是配通 LDAP、映射组、勤排错三步，落地后账号治理会轻松许多。

VaultActive_DirectoryLDAP_auth修改时间：2026-08-14 07:03:34