如果在配置并嵌入客户端 SSL 证书后查询仍返回错误,请检查以下设置。
在终端中,使用以下命令检查客户端与 API 端点之间是否可以成功建立 SSL/TLS 连接。
curl --verbose --cert /path/to/certificate.pem --key /path/to/key.pem https://your-api-endpoint.com如果无法完成 SSL/TLS 握手,请检查证书和私钥是否正确。 如果握手完成但请求仍被阻止,请确认 Cloudflare 正在验证客户端证书。
检查是否已为正确的主机启用 mTLS。主机应与您要保护的 API 端点匹配。
要检查 mTLS 规则,请考虑以下步骤。更多指导请参阅自定义规则。
-
在 Cloudflare 仪表板中,前往 Security rules(安全规则) 页面。
前往 Security rules(安全规则) ↗ -
在特定规则上,选择 Edit(编辑)。
-
在该规则上,检查:
-
Expression Preview 是否正确。
-
如果定义了主机名,是否与您的 API 端点匹配。例如,对于 API 端点
api.trackers.ninja/time,规则应类似于:(http.host in {"api.trackers.ninja"} and not cf.tls_client_auth.cert_verified)
-
-
要编辑规则,请使用用户界面或选择 Edit expression(编辑表达式)。
您可以使用 Cloudflare Workers 调试客户端证书验证失败。
-
创建一个 Worker,用于记录传入请求的
cf属性,并将每个请求转发到源站:src/index.jsjs export default { async fetch(request) { console.info({ message: JSON.stringify(request.cf, null, 2) }); return fetch(request); }, };src/index.tsts export default { async fetch(request): Promise<Response> { console.info({ message: JSON.stringify(request.cf, null, 2) }); return fetch(request); }, } satisfies ExportedHandler; -
使用 Worker route 将 Worker 与已启用 mTLS 的主机名关联。
-
向已配置的主机名和/或路径发起请求,分别在发送和不发送 mTLS 客户端证书的情况下进行。
-
在 Observability 仪表板中,将记录的
前往 Observability(可观测性) ↗tlsClientAuth值与预期值进行比较。
-
有效证书
"tlsClientAuth": { "certPresented": "1", "certVerified": "SUCCESS", }, -
无效证书(例如自签名证书)
"tlsClientAuth": { "certPresented": "1", "certVerified": "FAILED:self signed certificate", }, -
无证书
"tlsClientAuth": { "certPresented": "0", "certVerified": "NONE", },
Cloudflare 托管的客户端证书计入按 zone 的配额。要释放名额,请吊销不再需要的证书。吊销证书会立即释放该名额。
要列出并吊销证书,请参阅 client certificates API。
每个 Enterprise 账户最多可为 BYOCA 上传五个 CA 证书。此配额由 API Shield、Workers mTLS 和 Cloudflare Gateway 共享。
如果超出此限制,API 将返回:
{
"code": 1489,
"message": "Hit maximum CA cert allocation."
}要释放名额,必须先移除该 CA 的所有主机名关联,然后再删除它。要提高配额,请联系您的账户团队。
上传用于 自带 CA (BYOCA) 的 CA 证书时,证书必须满足以下要求:
-
CA 证书可以来自公开受信任的 CA 或自签名。
-
在证书
Basic Constraints中,CA属性必须设置为TRUE。 -
证书必须使用以下列出的签名算法之一:
允许的签名算法
x509.SHA1WithRSAx509.SHA256WithRSAx509.SHA384WithRSAx509.SHA512WithRSAx509.ECDSAWithSHA1x509.ECDSAWithSHA256x509.ECDSAWithSHA384x509.ECDSAWithSHA512
您上传的必须是 CA 证书——也就是说,其扩展中必须包含 Basic Constraints: CA=TRUE。请上传客户端证书链中的 CA 证书,而不是客户端证书本身。
上传失败的常见原因是上传了叶(客户端)证书而不是 CA 证书。如果您的证书链是 Root CA → Intermediate CA → Client certificate,请在单个 PEM 文件中上传完整 CA 链,先放中间 CA,再放根 CA。
如果只上传中间 CA,即使主机名已与该 CA 关联,每次请求的 mTLS 验证也会失败。在 HTTP 请求日志中,ClientMTLSAuthCertFingerprint 与预期的客户端证书匹配,但 ClientMTLSAuthStatus 为 unknown。
要确认证书是 CA 证书,请对链中的每张证书运行以下命令:
openssl x509 -in certificate.pem -noout -text | grep -A1 "Basic Constraints"输出应包含 CA:TRUE。如果显示 CA:FALSE 或该字段缺失,则该证书不是 CA 证书,无法上传。
CA 证书必须使用以下签名算法之一:
SHA1WithRSA,SHA256WithRSA,SHA384WithRSA,SHA512WithRSAECDSAWithSHA1,ECDSAWithSHA256,ECDSAWithSHA384,ECDSAWithSHA512
如果 CA 证书使用了其他算法,请使用受支持的算法重新签发。
上传请求中的 certificates 字段必须包含有效且正确分隔的 PEM 内容。确保证书以 -----BEGIN CERTIFICATE----- 开头,并以 -----END CERTIFICATE----- 结尾。请勿在此字段中包含私钥或证书签名请求。