服务注册与分布式协调 / 系统课时
启用双向 TLS 与 x509 身份
启用双向 TLS 与 x509 身份
这一节把客户端 TLS 从“只验证服务器”提升为双向认证:服务器强制索取客户端证书,ZooKeeper 把证书的 X500 Principal 注入会话为 x509 身份,再用 ACL 证明可信 CA 与正确身份是两道独立门槛。
学习目标
- 配置
ssl.clientAuth=need,让无客户端证书的连接在握手阶段失败 - 让 Java 客户端同时加载 keyStore 与 trustStore 完成 mTLS
- 用
x509会话身份和 ACL 区分可信证书与授权身份
强制客户端提交证书
服务器端必须同时拥有自己的证书私钥,以及用于验证客户端证书签发链的 trustStore。显式配置 ssl.clientAuth=need 后,没有证书的客户端不能完成 TLS 握手;持有证书但证书链不被服务器信任时也会在握手阶段失败。([Apache ZooKeeper][1])
片段示例:以下只列出与客户端 mTLS 直接相关的 zoo.cfg 项。
secureClientPort=<PORT>
serverCnxnFactory=org.apache.zookeeper.server.NettyServerCnxnFactory
ssl.keyStore.location=<PATH>/server-keystore.p12
ssl.keyStore.password=<PASSWORD>
ssl.keyStore.type=PKCS12
ssl.trustStore.location=<PATH>/client-ca-truststore.p12
ssl.trustStore.password=<PASSWORD>
ssl.trustStore.type=PKCS12
ssl.clientAuth=need客户端除了信任服务端 CA,还要提供自己的私钥与证书链。生产环境应分别管理服务端和客户端私钥,不要为了省事把同一个 keystore 复制到所有进程。

用 Java 客户端建立 x509 ACL
通过安全端口完成客户端证书认证后,ZooKeeper 会自动把客户端的 X500 Principal 作为 x509 身份加入当前连接。x509 ACL 的表达式就是客户端证书的精确 X500 Principal;使用 CREATOR_ALL_ACL 可以让服务器把当前已认证身份写入新节点 ACL。([Apache ZooKeeper][2])
可运行主程序如下。第一次用合法客户端证书执行时创建 /mtls-only;再次执行会读取 ACL 和数据。
import java.nio.charset.StandardCharsets;
import java.util.List;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.TimeUnit;
import org.apache.zookeeper.CreateMode;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooDefs;
import org.apache.zookeeper.ZooKeeper;
import org.apache.zookeeper.data.ACL;
import org.apache.zookeeper.data.Stat;
public class MtlsAclClient {
public static void main(String[] args) throws Exception {
String connectString =
System.getenv().getOrDefault("ZK_CONNECT", "zk1.example.com:2281");
CountDownLatch connected = new CountDownLatch(1);
ZooKeeper zk = new ZooKeeper(connectString, 10_000, event -> {
if (event.getState() == Watcher.Event.KeeperState.SyncConnected) {
connected.countDown();
}
});
if (!connected.await(10, TimeUnit.SECONDS)) {
zk.close();
throw new IllegalStateException("ZooKeeper mTLS connection timed out");
}
String path = "/mtls-only";
Stat stat = zk.exists(path, false);
if (stat == null) {
zk.create(
path,
"secret".getBytes(StandardCharsets.UTF_8),
ZooDefs.Ids.CREATOR_ALL_ACL,
CreateMode.PERSISTENT);
System.out.println("created=" + path);
}
List<ACL> acls = zk.getACL(path, new Stat());
for (ACL acl : acls) {
System.out.println(
"acl=" + acl.getId().getScheme()
+ ":" + acl.getId().getId()
+ " perms=" + acl.getPerms());
}
byte[] data = zk.getData(path, false, null);
System.out.println("data=" + new String(data, StandardCharsets.UTF_8));
zk.close();
}
}用持有合法客户端证书的身份运行:
ZK_CONNECT=<HOST>:<PORT> java \
-Dzookeeper.clientCnxnSocket=org.apache.zookeeper.ClientCnxnSocketNetty \
-Dzookeeper.client.secure=true \
-Dzookeeper.ssl.keyStore.location=<PATH>/orders-client.p12 \
-Dzookeeper.ssl.keyStore.password=<PASSWORD> \
-Dzookeeper.ssl.keyStore.type=PKCS12 \
-Dzookeeper.ssl.trustStore.location=<PATH>/server-ca-truststore.p12 \
-Dzookeeper.ssl.trustStore.password=<PASSWORD> \
-Dzookeeper.ssl.trustStore.type=PKCS12 \
-cp "<PATH>/classes:<PATH>/lib/*" \
MtlsAclClient预期输出
created=/mtls-only
acl=x509:<X500_PRINCIPAL> perms=31
data=secret<X500_PRINCIPAL> 是客户端证书的实际 X500 Principal,例如 CN=orders-client,OU=Platform,O=Example;字段内容和顺序必须以实际证书及 ZooKeeper 记录的身份为准。
验证三类拒绝路径
无证书时,保留 trustStore 但去掉客户端 keyStore,再运行同一程序。因为服务器配置了 ssl.clientAuth=need,失败发生在 ZooKeeper 会话创建之前,通常表现为 TLS 握手异常,而不是 NoAuth。
错误 CA 也属于握手层失败:如果服务端不信任客户端证书的签发 CA,或客户端不信任服务端证书的签发 CA,双方都无法把证书链验证到受信任根。
“错误身份”则不同。准备另一张由服务器信任 CA 签发、但 X500 Principal 与 /mtls-only ACL 不同的客户端证书,替换 zookeeper.ssl.keyStore.location 后再次运行。mTLS 可以成功,但读取受保护节点会被 ACL 拒绝。
预期结果
org.apache.zookeeper.KeeperException$NoAuthException: KeeperErrorCode = NoAuth for /mtls-only这个结果证明了两层控制没有混在一起:CA 决定证书能否成为可信连接身份,ACL 决定这个可信身份能否操作某个 znode。
避免把“证书可信”当成“业务有权”
mTLS 解决的是双方身份真实性和链路加密,不会自动给客户端访问所有 znode 的权限。只有节点 ACL 包含该连接的 x509 身份,或使用了其他匹配的认证方案,业务请求才会被授权。
因此排查时要先看握手是否成功,再看当前客户端证书对应的 X500 Principal 是否与 ACL 精确匹配。无证书和错误 CA 应停在 TLS 层;受信任但身份不匹配的证书应进入 ZooKeeper 后收到授权失败,这才是正确的安全边界。