使用OkHttp通过HTTP代理发起HTTPS请求时KeyManager失效问题

问题分析 #

直接调用API时客户端证书能正常完成认证，但通过HTTP代理调用时目标服务器返回403 : Forbidden : Missing certificate，说明隧道建立后的TLS握手阶段没有正确发送客户端证书。Postman可正常通过代理调用，排除代理本身不支持CONNECT隧道的问题，核心问题出在OkHttp的SSL配置与代理的结合逻辑上。

解决方案 #

核心思路是：自定义包含客户端证书的SSL上下文，将其与代理配置绑定到同一个OkHttpClient实例，再替换OpenAPI生成客户端的默认HttpClient。

1. 构建包含客户端证书的SSLContext #

import javax.net.ssl.*;
import java.io.FileInputStream;
import java.security.KeyStore;
import java.security.SecureRandom;

public class SslContextFactory {
    public static SSLContext createSslContext(String keyStorePath, String keyStorePassword, String keyStoreType, String caCertPath) throws Exception {
        // 加载客户端证书到KeyStore
        KeyStore keyStore = KeyStore.getInstance(keyStoreType);
        try (FileInputStream fis = new FileInputStream(keyStorePath)) {
            keyStore.load(fis, keyStorePassword.toCharArray());
        }

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

        // 加载API证书链到TrustStore
        KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
        trustStore.load(null, null);
        try (FileInputStream fis = new FileInputStream(caCertPath)) {
            CertificateFactory cf = CertificateFactory.getInstance("X.509");
            java.security.cert.Certificate cert = cf.generateCertificate(fis);
            trustStore.setCertificateEntry("api-ca-chain", cert);
        }

        // 初始化TrustManagerFactory
        TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
        tmf.init(trustStore);

        // 构建并返回SSLContext
        SSLContext sslContext = SSLContext.getInstance("TLS");
        sslContext.init(kmf.getKeyManagers(), tmf.getTrustManagers(), new SecureRandom());
        return sslContext;
    }
}

2. 配置带代理和SSL上下文的OkHttpClient #

import okhttp3.OkHttpClient;
import java.net.InetSocketAddress;
import java.net.Proxy;

public class HttpClientFactory {
    public static OkHttpClient createHttpClient(String proxyHost, int proxyPort, SSLContext sslContext) {
        // 配置HTTP代理
        Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress(proxyHost, proxyPort));

        // 构建自定义OkHttpClient
        return new OkHttpClient.Builder()
                .proxy(proxy)
                .sslSocketFactory(sslContext.getSocketFactory(), (X509TrustManager) sslContext.getTrustManagers()[0])
                .hostnameVerifier((hostname, session) -> {
                    // 生产环境建议替换为真实的域名验证逻辑，避免安全风险
                    return hostname.equals("{URL_SERVICE的域名}");
                })
                .build();
    }
}

3. 替换生成的API客户端的默认HttpClient #

OpenAPI Generator生成的客户端会提供设置自定义HttpClient的方法，示例如下：

// 假设生成的基础客户端类为ApiClient
ApiClient apiClient = new ApiClient();

// 加载配置并创建SSLContext
SSLContext sslContext = SslContextFactory.createSslContext(
        "./src/main/resources/{CLIENT_CERTIFICATE}.pfx",
        "{CLIENT_CERTIFICATE_PASSWORD}",
        "PKCS12",
        "./src/main/resources/{API_CERTIFICATE_CHAIN}.crt"
);

// 创建带代理的自定义OkHttpClient
OkHttpClient okHttpClient = HttpClientFactory.createHttpClient(
        "{PROXY_IP}",
        8080,
        sslContext
);

// 替换生成客户端的默认HttpClient
apiClient.setHttpClient(okHttpClient);

// 后续用该apiClient创建具体的API服务实例调用接口
ExampleApi exampleApi = new ExampleApi(apiClient);
exampleApi.callTargetApi();

关键注意事项 #

• 必须替换默认HttpClient：自动生成的客户端默认HttpClient不会包含自定义的SSL和代理配置，必须显式替换。
• 路径适配：建议使用类路径加载证书文件（如getClass().getResourceAsStream("/{CLIENT_CERTIFICATE}.pfx")），避免环境差异导致的路径问题。
• 代理认证：如果代理需要用户名密码认证，需在OkHttpClient.Builder中添加proxyAuthenticator逻辑。
• 日志排查：可添加OkHttp日志拦截器查看SSL握手细节，辅助定位问题：

import okhttp3.logging.HttpLoggingInterceptor;

// 添加到OkHttpClient.Builder中
HttpLoggingInterceptor loggingInterceptor = new HttpLoggingInterceptor();
loggingInterceptor.setLevel(HttpLoggingInterceptor.Level.HEADERS);
new OkHttpClient.Builder().addInterceptor(loggingInterceptor).build();

内容的提问来源于stack exchange，提问作者Álvaro Peña Meléndez