微信接口 HTTPS 双向认证（mTLS）在 Java 客户端的配置与调试

微信 mTLS 场景说明

部分高安全要求的微信企业接口（如金融行业定制通道、支付回调验证增强等）会启用 HTTPS 双向认证（mTLS），即客户端必须提供由微信 CA 签发的客户端证书，服务端才会接受连接。Java 应用需正确加载 KeyStore（私钥+证书） 与 TrustStore（信任的 CA 证书） 才能建立连接。

准备证书文件

假设微信提供了以下文件：

• client.p12：PKCS#12 格式的客户端证书+私钥（密码为 changeit）
• wechat_ca.crt：微信 CA 的根证书

将它们放置于 src/main/resources/certs/ 目录下。

构建支持 mTLS 的 HttpClient（OkHttp 示例）

package wlkankan.cn.http;

import okhttp3.OkHttpClient;
import javax.net.ssl.*;
import java.io.InputStream;
import java.security.KeyStore;
import java.security.cert.CertificateFactory;
import java.security.cert.X509Certificate;

public class MtlsHttpClient {

    private static final String CLIENT_CERT_PATH = "/certs/client.p12";
    private static final String CA_CERT_PATH = "/certs/wechat_ca.crt";
    private static final String KEYSTORE_PASSWORD = "changeit";

    public static OkHttpClient createMtlsClient() {
        try {
            // 1. 加载客户端证书（KeyStore）
            KeyStore keyStore = KeyStore.getInstance("PKCS12");
            try (InputStream ksStream = MtlsHttpClient.class.getResourceAsStream(CLIENT_CERT_PATH)) {
                keyStore.load(ksStream, KEYSTORE_PASSWORD.toCharArray());
            }

            // 2. 初始化 KeyManagerFactory
            KeyManagerFactory kmf = KeyManagerFactory.getInstance(KeyManagerFactory.getDefaultAlgorithm());
            kmf.init(keyStore, KEYSTORE_PASSWORD.toCharArray());

            // 3. 加载微信 CA 证书（TrustStore）
            CertificateFactory cf = CertificateFactory.getInstance("X.509");
            try (InputStream caStream = MtlsHttpClient.class.getResourceAsStream(CA_CERT_PATH)) {
                X509Certificate caCert = (X509Certificate) cf.generateCertificate(caStream);

                KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
                trustStore.load(null, null);
                trustStore.setCertificateEntry("wechat-ca", caCert);

                TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
                tmf.init(trustStore);

                // 4. 构建 SSLContext
                SSLContext sslContext = SSLContext.getInstance("TLS");
                sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);

                return new OkHttpClient.Builder()
                    .sslSocketFactory(sslContext.getSocketFactory(), (X509TrustManager) tmf.getTrustManagers()[0])
                    .hostnameVerifier((hostname, session) -> hostname.equals("api.mch.weixin.qq.com")) // 严格校验
                    .build();
            }
        } catch (Exception e) {
            throw new RuntimeException("Failed to initialize mTLS HTTP client", e);
        }
    }
}

使用 Apache HttpClient 实现（备选方案）

package wlkankan.cn.http;

import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import javax.net.ssl.SSLContext;
import java.io.InputStream;
import java.security.KeyStore;

public class ApacheMtlsClient {

    public static CloseableHttpClient createClient() throws Exception {
        KeyStore keyStore = KeyStore.getInstance("PKCS12");
        try (InputStream ksIn = ApacheMtlsClient.class.getResourceAsStream("/certs/client.p12")) {
            keyStore.load(ksIn, "changeit".toCharArray());
        }

        SSLContext sslContext = org.apache.http.ssl.SSLContexts.custom()
            .loadKeyMaterial(keyStore, "changeit".toCharArray())
            .loadTrustMaterial(ApacheMtlsClient.class.getResource("/certs/wechat_ca.crt"), null)
            .build();

        SSLConnectionSocketFactory sslsf = new SSLConnectionSocketFactory(
            sslContext,
            new String[]{"TLSv1.2"},
            null,
            (hostname, session) -> hostname.equals("api.mch.weixin.qq.com")
        );

        return HttpClients.custom()
            .setSSLSocketFactory(sslsf)
            .build();
    }
}

调试技巧：启用 SSL 调试日志

在启动 JVM 时添加参数，输出详细 TLS 握手过程：

-Djavax.net.debug=ssl:handshake:verbose:keymanager:trustmanager

关键日志片段应包含：

• adding as trusted cert：确认 CA 证书被加载
• found key for : ...：确认客户端证书被选用
• *** CertificateRequest → *** Certificate：证明客户端已发送证书

若出现 Received fatal alert: bad_certificate，通常表示：

• 客户端证书未被微信 CA 签发
• 证书已过期或域名不匹配
• 私钥密码错误导致无法读取

封装调用示例

public class WeComMtlsService {

    private final OkHttpClient client = MtlsHttpClient.createMtlsClient();

    public String callSecureApi(String requestBody) {
        Request request = new Request.Builder()
            .url("https://api.mch.weixin.qq.com/secapi/some/endpoint")
            .post(RequestBody.create(requestBody, MediaType.get("application/json")))
            .build();

        try (Response response = client.newCall(request).execute()) {
            if (!response.isSuccessful()) {
                throw new RuntimeException("API call failed: " + response.code());
            }
            return response.body().string();
        } catch (Exception e) {
            wlkankan.cn.log.Logger.error("mTLS API call error", e);
            throw new RuntimeException(e);
        }
    }
}

生产环境注意事项

1. 证书权限：.p12 文件应设置为仅应用用户可读（chmod 600）
2. 密码管理：避免硬编码，使用配置中心（如 Apollo、Nacos）加密存储
3. 协议版本：强制使用 TLSv1.2+，禁用 SSLv3/TLSv1.0
4. 主机名校验：不可使用 (hostname, session) -> true，必须严格匹配微信官方域名

通过上述配置，Java 客户端可安全完成微信 mTLS 接口的双向认证，满足金融级通信安全要求。