Caddy 选择性 mTLS：内网 API 强制双向认证，公网访问零影响

Caddy 选择性 mTLS内网 API 强制双向认证公网访问零影响【免费下载链接】caddyFast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS项目地址: https://gitcode.com/GitHub_Trending/ca/caddy安全团队要求 API 域名启用强制双向认证但同一个 Caddy 上跑着的公开文档站不能受影响——普通用户不应该被要求提交客户端证书。Caddy 选择性 mTLS 正是为这类一部分流量必须验证书、另一部分照常放行的需求设计的它按 TLS 连接策略connection_policy匹配流量对每个连接应用不同的客户端证书验证规则。用connection_policymatch把强制认证限定在指定 IP 段或域名上先跑通基线双向认证再叠加 remote_ip / sni 等匹配条件拿到一张 mTLS 握手排障表覆盖 CA 路径、证书链、匹配顺序等高频坑为什么不是一刀切方案安全性可用性配置复杂度不启用 mTLS仅验证服务端无客户端身份所有客户端零摩擦低全量 mTLS每个连接都验证客户端证书没有证书的连接全部被拒低但牺牲可用选择性 mTLS敏感流量强制验证其余照常普通访问不受影响中需写匹配条件Caddy 的机制核心在 TLS 连接策略模块ConnectionPolicy每个 TLS 握手开始时Caddy 拿 ClientHello 依次匹配已配置的连接策略第一条命中的策略决定该连接的客户端认证行为。client_auth块模式 信任池就挂在策略上而不是写死在服务器上。支持的匹配维度均作用于握手阶段早于任何 HTTP 路由SNI按请求域名匹配MatchServerName远端 IP按客户端 IP/网段匹配MatchRemoteIP本地 IP按服务器本机 IP 匹配适合多网卡多入口MatchLocalIP正则SNI 通配MatchServerNameRE先想清楚你的匹配条件是什么上配置前先把什么流量需要强制证书说清楚匹配条件选错了后面全白调。典型场景适用条件推荐 matcher内网服务网段客户端固定来自办公网/机房 IP 段如 192.168.1.0/24match remote_ip特定子域名内部 API 独占一个子域名如 api.internal.example.commatch sni正则通配一批子域名都算内部服务如*.corp.example.commatch sni_regexp证书文件只需准备好客户端 CA 的根证书放到 Caddy 可读取的路径cp client-ca.crt /etc/caddy/caddy.ca.cer版本要求trust_pool子块语法需要较新的 Caddyv2.7升级或安装参见 官方安装文档。⚠️ 老版本只认已废弃的trusted_ca_cert_file字段混用会在caddy adapt时报错。配置落地从最小可用到按需加条件基线双向认证配置tls 块 client_auth trust_pool{ srv0 { listen :443 routes { internal { header Authorization Bearer sk-internal-... } handle /api/* { reverse_proxy 10.0.0.20:8080 } } } }上面是示意路由结构核心在下面的 TLS 块取自仓库测试用例 tls_client_auth_cert_file.caddyfiletest:443 { respond OK tls { client_auth { mode require_and_verify # 关键行强制提交并完整验证 trust_pool file { pem_file /etc/caddy/caddy.ca.cer # CA 根证书路径 } } } }这一段的意思是该 server 上的所有连接都必须提交由这个 CA 签发的有效客户端证书否则握手直接失败。跑通这个基线再谈选择性——如果基线都不通加条件只会把排查范围放大。换成你的场景时只改pem_file路径和 CA 来源即可。加条件用 connection_policy match remote_ip 限定强制范围:443 { respond OK tls { # 默认策略只请求、不强制普通客户端零摩擦 client_auth { mode request trust_pool file { pem_file /etc/caddy/caddy.ca.cer } } # 内网网段命中后强制验证 connection_policy { match remote_ip 192.168.1.0/24 client_auth { mode require_and_verify trust_pool file { pem_file /etc/caddy/caddy.ca.cer } } } } }匹配规则要记死策略按在 Caddyfile 中出现的顺序评估先命中先生效后面的策略不参与。⚠️ 如果你把remote_ip策略写在前面、默认策略写在后面顺序反了就会让 192.168.1.0/24 之外的流量落到不该落的位置——按越具体越靠前排。改网段就改match remote_ip后面的 CIDR要按域名强制把它换成match sni api.internal.example.com即可。验收与排障curl 双场景 mTLS 握手排障表快速验收无证书被拒、带证书通过# 预期结果握手失败tls: certificate required curl -v https://api.internal.example.com --cacert /etc/caddy/caddy.ca.cer # 预期结果HTTP 200返回 OK curl https://api.internal.example.com --cacert /etc/caddy/caddy.ca.cer \ --cert client.crt --key client.key两条命令一拒一通过说明选择性策略按预期生效。注意--cert/--key指向由该 CA 签发的客户端证书测试阶段可以让 Caddy PKI 模块 的内部 CA 顺手签发一张。配置不生效按这张 mTLS 握手排障表查现象最可能原因排查命令或操作相关源码或文档handshake failure且所有客户端全拒pem_file路径错误或文件不可读ls -l /etc/caddy/caddy.ca.cer确认 Caddy 进程用户可读ClientAuthentication 解析证书正确但仍被拒客户端证书链断裂提交的是中间证书未带全链openssl verify -CAfile /etc/caddy/caddy.ca.cer client.crttrust_pool 模块解析昨天正常今天全拒服务器时间漂移证书被判定过期chronyc tracking校时openssl x509 -enddate -noout -in client.crt同上内网流量没走强制策略匹配器顺序问题更宽的策略写在了前面检查 Caddyfile 中connection_policy顺序具体策略靠前策略评估顺序改完配置起不来或行为怪异Caddyfile 语法/字段错误caddy adapt --config Caddyfile --pretty查看展开后的 JSONCaddyfile 适配测试用例生产环境 mTLS 上线 checklist服务端证书接入 Caddy 自动签发与轮换客户端 CA 到期纳入日历提醒Caddy PKI 模块客户端证书吊销走 CRL/OCSP 或缩短证书有效期别等泄露后才发现内网高频服务启用 TLS 会话复用减少重复完整握手打开握手日志认证失败率异常时能按时间点回溯日志模块把 mTLS 失败率纳入指标监控并设告警阈值HTTP 指标条件逻辑超过两三个维度时改用 CEL 表达式匹配避免 matcher 叠罗汉CEL 匹配器变更走caddy adapt预校验 灰度发布不直接热加载生产配置选择性 mTLS 的价值就一句话敏感服务被双向认证保护普通访问零摩擦——完整能力参见 Caddy TLS 模块。【免费下载链接】caddyFast and extensible multi-platform HTTP/1-2-3 web server with automatic HTTPS项目地址: https://gitcode.com/GitHub_Trending/ca/caddy创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考