企业官网建设流程全解析

1. 先说结论：这个报错到底在提示什么

如果你在 Ranger Admin 里配了 LDAP 认证，打开登录页输入 FreeIPA 账号，结果页面干脆利落地甩给你一句 “Bad credentials”，十有八九不是 Ranger 本身坏了，而是它拿“你给的这组用户名 + 密码”去做 LDAP 绑定或搜索时，被 FreeIPA 拒了。这句话是你排查链路里最有价值的线索，“Bad credentials” 在 LDAP 协议里对应的是错误码 49（invalidCredentials），意思是服务端确实收到了连接请求，但用户名或密码没能通过身份校验。

FreeIPA 环境下这个报错尤其容易冒出来，因为它不像 Active Directory 那样“随便拿个 userPrincipalName 就能 bind”，也不像裸装的 OpenLDAP 那样默认目录结构简单直白。FreeIPA 的默认目录基础是dc=example,dc=com这种形式，用户放在cn=users,cn=accounts下，组放在cn=groups,cn=accounts下，管理员账号是uid=admin,cn=users,cn=accounts,dc=example,dc=com。如果你在 Ranger 里填的 Bind DN、User Search Base 和实际目录结构对不上，或者证书信任链不对，那 FreeIPA 不会给你任何有歧义的提示，直接返回 49。这篇文章不绕弯子，直接按我实际排障的顺序，把这个报错从“看到报错”到“彻底解决”的完整链路拆给你看。

1.1 Bad credentials 在 Ranger 里的真实含义

Ranger Admin 的 LDAP 认证，本质上不是 Ranger 自己写了套 LDAP 客户端，而是走 Java JNDI / Spring LDAP 那套逻辑。你配置好ranger-admin-site.xml里的ranger.admin.auth.method=LDAP、ranger.admin.ldap.url、ranger.admin.ldap.bind.dn、ranger.admin.ldap.bind.password、ranger.admin.ldap.user.searchbase之后，用户登录时流程大致是这样：

1. Ranger 先用配置里的 Bind DN 和 Bind Password 去连 FreeIPA，建立一条“管理通道”；
2. 用这条管理通道去 User Search Base 里检索你输入的用户名，拿到这个用户的完整 DN；
3. 再用你输入的用户名、密码绑到这条 DN 上进行认证。

这三步任何一步失败，最终都可能表现为 “Bad credentials”。但其中有个容易被忽略的细节：如果是第一步管理通道绑定失败，Ranger 通常会在服务端日志里留下更明确的信息，比如javax.naming.AuthenticationException: [LDAP: error code 49]或者InvalidCredentialsException，而登录界面只给你一句笼统的 “Bad credentials”。所以我的习惯是先看 Ranger 的log/ranger-admin-<username>.log，再回来看界面报错。日志里的原始异常，基本能定位到是哪一步出了问题。

另外注意，“Bad credentials” 不等于“用户不存在”。FreeIPA 出于安全考虑，在 LDAP 绑定失败时不会告诉你到底是“用户不存在”还是“密码错误”，统一返回 invalidCredentials。这就意味着，哪怕你把 User Search Base 配错了，找不到用户，也可能报 Bad credentials；哪怕用户名对、密码对，但 Bind DN 没权限搜索，同样可能报 Bad credentials。搞清楚这一点，你就不会傻乎乎地只改密码了。

1.2 为什么 FreeIPA 特别容易触发这类报错

我在生产环境里同时维护过 OpenLDAP、AD 和 FreeIPA，说实话，FreeIPA 在 LDAP 集成这一步的“规矩”是最多的。它默认是 389 端口明文 LDAP 和 636 端口 LDAPS 同时开着，但为了安全，很多部署只允许 TLS 连接，甚至强制要求客户端校验服务端证书。Ranger 的 JVM 默认信任库只信任公开 CA，FreeIPA 的证书是自建的 IPA CA 签发，你要是没把这个 CA 证书导入 Ranger 所在 Tomcat 的cacerts，那么即使密码完全正确，TLS 握手也会失败，最终表现同样可能被封装成 “Bad credentials”。

再一个坑是目录结构。FreeIPA 默认的 users 容器是cn=users,cn=accounts，不是大多数 LDAP 文档里写的ou=people。有的人把其它系统的配置习惯直接抄过来，把 Search Base 写成ou=people,dc=example,dc=com，FreeIPA 上压根不存在这个节点，搜索返回 0 条记录，Ranger 找不到用户对应的 DN，自然无法完成后续绑定，于是又变成 Bad credentials。

还有一个极其隐蔽的点：FreeIPA 的默认密码策略里，连续多次失败会锁定账号。我见过有人排错时一遍一遍在界面试密码，结果把uid=admin这个绑定账号本身给锁了。后面所有请求都失败，看起来还是 Bad credentials，但实际是账号锁定。所以“先看日志，再动配置，少做无意义重试”是排障铁律。

2. 环境准备与前置检查

2.1 FreeIPA 侧的账户与目录结构确认

动手改 Ranger 配置之前，先把 FreeIPA 侧该确认的信息确认完。你先用 ipa 管理员账号登到一台 FreeIPA 服务器上，用ldapsearch或ipa user-find看看当前真实结构。最常见的验证命令是：

ldapsearch -x -H ldap://ipa.example.com -D "uid=admin,cn=users,cn=accounts,dc=example,dc=com" -W -b "dc=example,dc=com" "(objectClass=posixAccount)" uid cn

这里要重点确认几个值：

• Base DN：例子里是dc=example,dc=com，真实环境请用ipa-server-install时设置的域名。如果你不确定，可以在 FreeIPA 服务器上执行ipa env或查看/etc/ipa/default.conf里的basedn。
• 用户搜索基址：FreeIPA 默认是cn=users,cn=accounts,<Base DN>。有些版本或自定义 schema 会变，所以最好用上面的命令实际确认一下返回条目的 DN 格式。
• 绑定账号：Ranger 里配置的 LDAP Bind DN 需要用有权读目录的账号。常规做法是直接用uid=admin,cn=users,cn=accounts,dc=example,dc=com，简单归简单，但权限过大。如果你希望更规范，可以在 FreeIPA 里建一个专用服务账号，比如uid=rangerbind,cn=users,cn=accounts,dc=example,dc=com，然后用ipa role-add-member给它只读权限。

检查完目录结构，顺手验证一下这个绑定账号能不能正常用密码绑定。不要跳过这步，很多人在 Ranger 里配完报错，最后发现其实是绑定账号密码在 FreeIPA 里早就过期了。验证命令：

ldapsearch -x -H ldap://ipa.example.com -D "uid=rangerbind,cn=users,cn=accounts,dc=example,dc=com" -W -b "cn=users,cn=accounts,dc=example,dc=com" "(uid=alice)" uid

如果这一步能正常返回用户条目，说明账号和密码没问题。如果返回ldap_bind: Invalid credentials (49)，那就是密码错误或者账号本身状态有问题，去 FreeIPA 侧先处理。

2.2 Ranger 侧几个最容易被忽略的配置项

Ranger 的 LDAP 配置集中在ranger-admin-site.xml和ranger-ams-*.properties之类文件里。我建议你直接去安装目录的conf下看ranger-admin-site.xml，重点关注这些参数：

这些问题里最容易忽略的是ranger.admin.ldap.referral。FreeIPA 在配置了复制拓扑时，某个 LDAP 请求可能返回 referral 到另一台副本，如果 Ranger 不跟随引用，查找用户可能失败，表现为找不到用户，最终也会演变成 Bad credentials。虽然多数单机部署没这问题，但集群部署建议显式配置。

另外，如果你修改了ranger-admin-site.xml，必须重启 Ranger Admin 服务，或者至少调用它的 reload 接口。别改完文件就以为立刻生效，我见过太多人在这个环节卡半小时。

2.3 证书与 JVM 信任库检查

如果ranger.admin.ldap.url配的是ldaps://，你就要在 Ranger 所在节点的 JVM 里把 FreeIPA 的 CA 证书导入cacerts，否则 JVM 在 TLS 握手阶段就会报PKIX path building failed。操作命令如下：

# 从 FreeIPA 服务器拉取 CA 证书 scp root@ipa.example.com:/etc/ipa/ca.crt /tmp/ipa-ca.crt # 找到 Ranger 使用的 JVM # 通常就是 JAVA_HOME/jre/lib/security/cacerts keytool -importcert -alias ipa-ca -file /tmp/ipa-ca.crt \ -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit -noprompt

导入后用以下命令验证：

keytool -list -keystore $JAVA_HOME/jre/lib/security/cacerts -storepass changeit | grep -i ipa

还有一个容易被忽略的版本问题：如果你使用的是ldap://明文协议，FreeIPA 默认允许明文绑定吗？看部署参数。大部分 FreeIPA 安装默认是允许 389 明文 LDAP 绑定的，但建议生产环境用 LDAPS。如果你初期只想快速验证账号密码是否正确，可以先用 389 明文调通，再切到 636。走 LDAPS 时一定确认防火墙放行 636。

3. 认证过程拆解：从点击登录到 Bad credentials

3.1 Ranger 拿到用户名后到底做了什么事

为了讲清楚 Bad credentials 在哪一步产生，我画一条最简单链路：用户在 Ranger 登录页输入alice和密码，点击登录。Ranger 内部顺序不是“拿用户名密码直接绑”，而是先配置的管理员 DN 绑定，再执行搜索。为什么非得这样？因为 LDAP 协议里普通用户绑定需要完整 DN，而用户通常只输入短用户名，比如alice，你要先查出来uid=alice,cn=users,cn=accounts,dc=example,dc=com，再拿这个 DN 去绑定。这里“查找”的动作就需要一个有权搜索目录的服务账号。

所以，整个逻辑顺序是：

1. 使用ranger.admin.ldap.bind.dn和ranger.admin.ldap.bind.password建立 JNDI 连接；
2. 在这个连接上执行ranger.admin.ldap.user.searchfilter搜索ranger.admin.ldap.user.searchbase，参数为用户名；
3. 如果结果恰好返回一个条目，取出它的 DN；
4. 关闭原来的连接，拿这个 DN 和用户输入的密码再绑一次；
5. 绑定成功则认证通过，失败则抛出 invalidCredentials，界面上就是 “Bad credentials”。

理解了这条链路，你就能明白：Bad credentials 不一定是“你的账户密码不对”，也可能是“第一步管理员绑定就失败了”，或是“第二步没搜到用户”。所以排查时不能只盯用户密码。

3.2 用命令行工具逐步验证每个环节

我排 LDAP 认证问题的时候，基本不依赖 Ranger 界面，直接用命令行把三步验证一遍。建议你也这样，效率最高。

第一步，验证管理员绑定是否成功：

ldapsearch -x -H ldap://ipa.example.com:389 \ -D "uid=rangerbind,cn=users,cn=accounts,dc=example,dc=com" \ -w 'your-password' \ -b "cn=users,cn=accounts,dc=example,dc=com" \ "(uid=alice)" dn

如果这里返回ldap_bind: Invalid credentials (49)，说明绑定账号密码就不对，直接去 FreeIPA 改密码或换账号。

第二步，验证用户搜索是否能拿到唯一 DN。如果上一步绑定成功但搜索结果为空，可能是 searchbase 不对，或者 searchfilter 太严格。可以先用宽松一点的过滤器实验：

ldapsearch -x -H ldap://ipa.example.com:389 \ -D "uid=rangerbind,cn=users,cn=accounts,dc=example,dc=com" \ -w 'your-password' \ -b "dc=example,dc=com" \ "(uid=alice)" dn

把 base 一栏直接放到域根，看能不能扫到。能扫到，说明 base 写窄了；扫不到，说明过滤器或者数据真有问题。

第三步，模拟用户绑定。拿到uid=alice,cn=users,cn=accounts,dc=example,dc=com后，直接拿这个 DN 和用户的密码绑定：

ldapsearch -x -H ldap://ipa.example.com:389 \ -D "uid=alice,cn=users,cn=accounts,dc=example,dc=com" \ -w 'alice-password' \ -b "uid=alice,cn=users,cn=accounts,dc=example,dc=com" \ -s base "objectClass=*"

能绑定就说明用户账号没问题。这三条命令分别对应 Ranger 的三步内部逻辑，哪一步挂在命令行里原样暴露。这比看一堆 Java 堆栈直观得多。

3.3 证书与 TLS 在链路里的隐藏作用

很多人忽略一个细节：Ranger 绑定 FreeIPA 时，即使你配置的是ldaps://，JVM 也默认不会直接信任“私有 CA 签发的证书”。如果没导入证书，你看到的可能是另一类异常，比如javax.net.ssl.SSLHandshakeException，但在某些封装版本里，前端仍然显示 Bad credentials。排查方法是在 Ranger 日志里搜SSLHandshakeException或PKIX，一旦出现，优先怀疑信任库。

FreeIPA 的目录服务同时监听 389 和 636，但 636 上的证书默认是 IPA CA 签发的，并且通常包含服务器主机名。你在配置 LDAPS URL 时，最好使用 FreeIPA 服务器的真实主机名或 IP 与证书对应的地址，别用ipa.example.com结果解析到别的 IP。如果主机名对不上，证书校验也会失败。

另一个经验是，先用openssl s_client验证服务端证书链，确保 Ranger 所在节点能正常建立 TLS 连接：

openssl s_client -connect ipa.example.com:636 -showcerts </dev/null | head -20

看输出里的subject和issuer，确认它确实是由 IPA CA 签发的，并且证书没过期。这一步能为你省下不少回头看日志的时间。

4. 解决方案与配置示范

4.1 在 ranger-admin-site.xml 中的正确配置方式

当你已经把前置检查都做完，确认 FreeIPA 侧的账号密码和目录结构都没问题，接下来就改 Ranger 配置。下面是我在一套 CentOS 上部署的 Ranger 与 FreeIPA 集成时用的最小可用配置，直接贴在ranger-admin-site.xml里：

<property> <name>ranger.admin.auth.method</name> <value>LDAP</value> </property> <property> <name>ranger.admin.ldap.url</name> <value>ldaps://ipa.example.com:636</value> </property> <property> <name>ranger.admin.ldap.bind.dn</name> <value>uid=rangerbind,cn=users,cn=accounts,dc=example,dc=com</value> </property> <property> <name>ranger.admin.ldap.bind.password</name> <value>your-bind-password</value> </property> <property> <name>ranger.admin.ldap.user.searchbase</name> <value>cn=users,cn=accounts,dc=example,dc=com</value> </property> <property> <name>ranger.admin.ldap.user.searchfilter</name> <value>(objectClass=posixAccount)</value> </property> <property> <name>ranger.admin.ldap.group.searchbase</name> <value>cn=groups,cn=accounts,dc=example,dc=com</value> </property> <property> <name>ranger.admin.ldap.group.searchfilter</name> <value>(objectClass=posixGroup)</value> </property> <property> <name>ranger.admin.ldap.referral</name> <value>ignore</value> </property>

需要注意一点：bind.password是明文存在 XML 里的。如果密码里有&、<、>这类特殊字符，记得做 XML 转义，否则 Tomcat 会直接解析失败。我更推荐的做法是先用一段纯文本的配置调通，再考虑用 Ranger 的加密工具或者交给配置管理系统管理。

改完配置文件，重启 Ranger Admin 服务。不同发行版命令不一样，常见的是：

sudo systemctl restart ranger-admin

如果用的是旧版安装方式，可能是/usr/bin/ranger-admin start。重启后，在日志目录里能看到新的启动记录，确认没有 LDAP 相关报错。

4.2 FreeIPA 的“管理员 DN”到底该怎么填

这是 Bad credentials 排障中最高频的坑。很多人把 FreeIPA 的管理员填成admin，或者填成cn=Directory Manager，然后被拒。FreeIPA 有两个容易混淆的管理身份：

• IPA 管理用户：默认是admin，但它不是一个 LDAP 根节点，它的完整 DN 是uid=admin,cn=users,cn=accounts,dc=example,dc=com；
• Directory Manager：FreeIPA 基于 389 Directory Server，底层确实存在一个cn=Directory Manager，但它在 FreeIPA 里默认是禁用的，只有通过特定配置才能启用或重置密码，常规部署下别指望用它连。

所以在 Ranger 里，Bind DN 要么填uid=admin,cn=users,cn=accounts,dc=example,dc=com，要么像我前面说的，单独建一个rangerbind专用账号。单独建账号的好处很多：权限可控、日志清晰、不会因为管理员密码轮换而影响 Ranger。创建方式是：

ipa user-add rangerbind --first=Ranger --last=Bind --password

然后给它只读权限。最简单粗暴的方式是把rangerbind加进User Administrators或IPA Read User Administrators这种角色，但更稳妥的做法是只授予它读取用户和组的权限。FreeIPA 里没有特别精细的“LDAP 只读”一说，但你可以通过ipa permission-add和ipa privilege-add来定制。

我的个人建议是：如果测试阶段只是内网环境，直接用uid=admin也没什么大问题；但投产环境务必建专用账号，避免哪天有人把 admin 密码改了或锁了，连带 Ranger 也瘫痪。这个坑我踩过，当时整个 Ranger Admin 都登不进去，最后还是 SSH 到宿主机上临时把认证方式改成本地用户才缓过来。

4.3 配置完成后如何完整自检

配置改完、服务重启后，别急着在浏览器里输密码，先做一轮命令行自检。

第一步，用ldapsearch以rangerbind身份验证连通性。这一步其实你前置检查时就应该做过，这里再重复一次，确保当前状态一切正常。

第二步，确认 JVM 能成功连接 LDAPS。可以写一个极简的 Java 示例或直接用jshell跑 JNDI 调用，但说实话有点重。更轻量的是直接看 Ranger 日志。启动 Ranger 后，如果 LDAP 配置正确，日志里一般不会出现Caused by: javax.naming.AuthenticationException。如果配置错误，日志会非常清晰。常用的日志路径：

tail -f /opt/ranger/log/ranger-admin-<user>.log

第三步，在 Ranger UI 上先用一个已知正常的 FreeIPA 用户登录，同时观察日志。如果日志里出现authentication failed for alice，但是命令行验证 alice 密码没问题，那问题大概率出在搜索过滤器或者证书。如果日志里出现no results found for user alice，那搜索基址写错了的可能性更大。

我一直强调自检要全链路，是因为 Bad credentials 是真“敷衍”的报错，它把每一步失败都折叠成同一个提示。只有你自己一步步把链路摊开，才能确认问题到底在哪。

5. 常见问题与实操避坑

5.1 现实中踩过的几个典型错误配置

下面这几类问题，我几乎每隔一段时间就会碰到一次，列成表方便你对照检查。

第五种情况值得多说两句。FreeIPA 默认密码策略会在错误尝试次数达到阈值后锁定账号，常见的阈值在/etc/ipa/default.conf或通过ipa pwpolicy-show查看。如果你用uid=admin做绑定账号，一旦它被锁，整个 Ranger 的 LDAP 通道就断了。这个状态下你从 UI 看什么都像 Bad credentials，但本质是绑定账号失效。临时办法是通过 IPA 控制台或命令行解除锁定，根本办法就是别把高权限账号直接暴露给中间件。

5.2 日志与排查工具速查

排障时建议优先翻这几类日志：

• Ranger Admin 日志：/opt/ranger/log/ranger-admin-<user>.log，重点关注Caused by字段；
• FreeIPA 目录服务器日志：journalctl -u dirsrv@<HOSTNAME>或/var/log/dirsrv/slapd-<HOSTNAME>/errors，能看到客户端传来的绑定请求和错误码；
• Tomcat 日志：如果 Ranger 跑在 Tomcat 里，catalina.out里可能有连接池或 JNDI 相关异常。

工具方面，我强烈建议你掌握ldapsearch和openssl s_client这两条命令。前者能验证 LDAP 协议层的所有认证细节，后者能验证 TLS 层证书状态。Ranger 界面上的报错信息量太少了，全靠命令行补。

如果你希望看得更细一点，还可以在 Ranger 日志级别上调到 DEBUG。不同版本入口不一样，常见做法是在logback.xml或log4j2.xml里将org.apache.ranger.admin的级别调成 DEBUG，然后重现一次登录失败。输出里会包含 JNDI 调用栈和具体 LDAP 错误码，能省掉不少猜谜时间。

5.3 一次真实案例的排错记录

最后分享一个我印象比较深的案例。客户环境是 FreeIPA 加 Ranger，现象是任何 FreeIPA 用户都登不上，界面稳定报 Bad credentials。我登录 FreeIPA 服务器，用rangerbind手动绑定，成功；用普通用户绑定，成功；目录搜索也没问题。当时我就想，问题多半不在 FreeIPA 侧，而在 Ranger 侧。

登录 Ranger 服务器看日志，发现报错里有SSLHandshakeException，但日志头部却显示它连的是ldap://而不是ldaps://。这就怪了。后来发现ranger-admin-site.xml里的 URL 确实写的是ldap://ipa.example.com:389，但 Ranger 某些内部服务配置文件里残留了旧的ldaps://ipa.example.com:636地址，导致实际验证走的是 LDAPS，而证书又没导入。这个环境里有两处配置文件不一致，属于“历史遗留”问题。

处理方式很简单：统一改成ldaps://ipa.example.com:636，并确认 TLS 证书导入成功。改完后重新登录，一次通过。这个案例说明了一件事：排障时别只盯一个文件，Ranger 里和 LDAP 相关的配置可能分布在多个配置文件和服务实例里，ranger-admin-site.xml、ranger-usersync-site.xml甚至一些环境变量都可能覆盖默认值。遇到 Bad credentials，先全局搜一遍 LDAP 相关配置，再去判断谁生效。

最后说点个人体会

排了这么多年 LDAP 认证问题，我最大的感触是：遇到 “Bad credentials” 先别急着猜密码，花十分钟把命令行链路跑一遍，往往比在界面上反复试快得多。尤其 FreeIPA 这种自带 Kerberos、自带 CA、密码策略又严格的环境，它的设计逻辑和普通 OpenLDAP 差别很大，很多坑不是它“有问题”，而是我们对它的目录约定不熟。

我个人现在每集成一套 FreeIPA，都会顺手建一个专用的低权限绑定账号，并把这个账号、DN、搜索基址、证书导入步骤都写进交付文档。后续出了任何认证问题，团队成员按文档里的验证命令 5 分钟就能定位。你不用“一把梭”去追求最复杂的安全方案，但一定别把排障步骤省掉。Bad credentials 只是一个结果，真正的解法永远在“查到哪一步失败”这个过程里。