本文详解如何将基于 Apache HttpClient 3.x/4.x 的 NTLM 认证代码（使用 NTCredentials 和 AuthSchemes）平滑迁移到 HttpClient 5.x，涵盖认证提供器、授权范围、认证方案枚举及密码类型等关键变更点。
本文详解如何将基于 apache httpclient 3.x/4.x 的 ntlm 认证代码（使用 `ntcredentials` 和 `authschemes`）平滑迁移到 httpclient 5.x，涵盖认证提供器、授权范围、认证方案枚举及密码类型等关键变更点。
在 Apache HttpClient 5.x 中，NTLM 认证的配置方式发生了若干重要演进：API 包结构重构、常量类重命名、凭证构造要求更严格，且底层安全契约更加明确。以下为完整迁移步骤与最佳实践。
Apache Superset Dashboard and SQL Exploration Skill
下载
Apache Superset 是一个广泛采用的开源 BI 平台，用于 SQL 探索、图表构建和仪表板交付。当代理需要查询仓库数据、组装仪表板或使用成熟的分析界面解释指标而不是临时笔记本代码时，此技能非常有用。
✅ 核心变更点说明
-
AuthScope.ANY已废弃：需替换为new AuthScope(null, -1)，表示匹配任意主机和端口； -
NTCredentials密码参数类型变更：从String改为char[]，提升敏感信息安全性（避免字符串常量池残留）； -
认证方案枚举迁移：
AuthSchemes.NTLM→StandardAuthScheme.NTLM（位于org.apache.hc.client5.http.impl.auth）； -
超时配置统一化：若涉及连接/请求超时，须显式使用
Timeout.ofSeconds()或Timeout.of(10, TimeUnit.SECONDS)，不再接受裸 long 值； -
包路径更新：所有类均归属
org.apache.hc.client5.*，需更新 import（如BasicCredentialsProvider,NTCredentials,StandardAuthScheme,RequestConfig,HttpClients）。
✅ 迁移后完整示例代码
import org.apache.hc.client5.http.auth.AuthScope;
import org.apache.hc.client5.http.auth.CredentialsProvider;
import org.apache.hc.client5.http.auth.StandardAuthScheme;
import org.apache.hc.client5.http.auth.UsernamePasswordCredentials;
import org.apache.hc.client5.http.impl.auth.BasicCredentialsProvider;
import org.apache.hc.client5.http.impl.auth.NTCredentials;
import org.apache.hc.client5.http.impl.classic.CloseableHttpClient;
import org.apache.hc.client5.http.impl.classic.HttpClients;
import org.apache.hc.client5.http.config.RequestConfig;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.web.client.RestTemplate;
// ... 在方法内
String url = "https://intranet.example.com/api/data";
String user = "DOMAIN\username"; // 或仅 username，取决于服务端要求
String pass = "P@ssw0rd";
String host = "intranet.example.com"; // 发起请求的目标主机名（非代理）
String domain = "DOMAIN";
CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(
new AuthScope(null, -1),
new NTCredentials(user, pass.toCharArray(), host, domain)
);
RequestConfig requestConfig = RequestConfig.custom()
.setTargetPreferredAuthSchemes(List.of(StandardAuthScheme.NTLM))
.build();
CloseableHttpClient httpClient = HttpClients.custom()
.setDefaultCredentialsProvider(credsProvider)
.setDefaultRequestConfig(requestConfig)
.build();
HttpComponentsClientHttpRequestFactory requestFactory = new HttpComponentsClientHttpRequestFactory();
requestFactory.setHttpClient(httpClient);
RestTemplate restTemplate = new RestTemplate(requestFactory);
return restTemplate.getForObject(url, String.class);⚠️ 注意事项与调试建议
- 主机名（host）必须准确：NTLM 质询中会用到该值生成加密哈希，若与实际请求目标不一致（如负载均衡后的真实后端），可能导致 401 错误；
- 域（domain）区分大小写：某些 Windows AD 环境对域名称大小写敏感，请确保与 Active Directory 配置完全一致；
-
禁用预认证（可选）：若遇到
401 Unauthorized后未自动重试 NTLM 流程，可尝试启用setAuthenticationStrategy(new ClassicAuthenticationStrategy())（HttpClient 5.2+）或检查服务端是否强制要求Connection: keep-alive； -
替代方案考量：如需脱离第三方 HTTP 客户端，Java 11+ 可结合
java.net.http.HttpClient+ 自定义Authenticator实现基础 NTLM（需集成第三方库如 Waffle 或 JCIFS NG），但复杂度显著上升，推荐优先使用 HttpClient 5.x 官方支持。
✅ 总结
HttpClient 5.x 对 NTLM 的支持更加标准化和安全可控，虽需适配少量 API 差异，但逻辑清晰、文档完备。只要注意 AuthScope 初始化方式、密码字符数组化、枚举类路径更新三大要点，即可顺利完成迁移，并获得更稳定的 Windows 集成认证能力。
