服务注册与分布式协调 / 系统课时

启用双向 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 项。

properties
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 复制到所有进程。

mTLS 证书认证到 x509 ACL 授权链路

用 Java 客户端建立 x509 ACL

通过安全端口完成客户端证书认证后,ZooKeeper 会自动把客户端的 X500 Principal 作为 x509 身份加入当前连接。x509 ACL 的表达式就是客户端证书的精确 X500 Principal;使用 CREATOR_ALL_ACL 可以让服务器把当前已认证身份写入新节点 ACL。([Apache ZooKeeper][2])

可运行主程序如下。第一次用合法客户端证书执行时创建 /mtls-only;再次执行会读取 ACL 和数据。

java
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();
    }
}

用持有合法客户端证书的身份运行:

bash
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

预期输出

text
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 拒绝。

预期结果

text
org.apache.zookeeper.KeeperException$NoAuthException: KeeperErrorCode = NoAuth for /mtls-only

这个结果证明了两层控制没有混在一起:CA 决定证书能否成为可信连接身份,ACL 决定这个可信身份能否操作某个 znode。

避免把“证书可信”当成“业务有权”

mTLS 解决的是双方身份真实性和链路加密,不会自动给客户端访问所有 znode 的权限。只有节点 ACL 包含该连接的 x509 身份,或使用了其他匹配的认证方案,业务请求才会被授权。

因此排查时要先看握手是否成功,再看当前客户端证书对应的 X500 Principal 是否与 ACL 精确匹配。无证书和错误 CA 应停在 TLS 层;受信任但身份不匹配的证书应进入 ZooKeeper 后收到授权失败,这才是正确的安全边界。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

启用双向 TLS 与 x509 身份

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通