Part2-HttpClient官方教程-Chapter4-HTTP 认证

　　原文链接地址
　　HttpClient 提供对由 HTTP 标准规范定义的认证模式的完全支持。HttpClient 的认证框架可以扩展支持非标准的认证模式，比如 NTLM 和 SPNEGO。

4.1 用户凭证

　　任何用户身份验证的过程都需要一组可以用于建立用户身份的凭据。用户凭证的最简单的形式可以仅仅是用户名/密码对。UsernamePasswordCredentials 代表了一组包含安全规则和明文密码的凭据。这个实现对由 HTTP 标准规范中定义的标准认证模式是足够的。

UsernamePasswordCredentials creds = new UsernamePasswordCredentials("user", "pwd");
System.out.println(creds.getUserPrincipal().getName());
System.out.println(creds.getPassword());

输出内容为：

user
pwd

　　NTCredentials是微软Windows指定的实现，它包含了除了用户名/密码对外，一组额外的Windows指定的属性，比如用户域名的名字，比如在微软的Windows网络中，相同的用户使用不同设置的认证可以属于不同的域。

NTCredentials creds = new NTCredentials("user", "pwd", "workstation", "domain");
System.out.println(creds.getUserPrincipal().getName());
System.out.println(creds.getPassword());

输出内容为：

DOMAIN/user
pwd

4.2. 认证模式

　　AuthScheme 接口代表了抽象的，面向请求-响应（challenge-response）的认证模式。一个认证模式期望支持如下的功能：

• 解析和处理目标服务器发送的请求，以响应受保护资源的请求。
• 提供处理后的请求的属性：认证方案类型及其参数，如认证方案适用的领域（如果可用）
• 为给定的一组凭证和HTTP请求生成授权字符串以响应实际的授权质询。

请注意，认证方案可能是有状态的，涉及一系列请求-响应交换。HttpClient 附带了一些 AuthScheme 实现：

• Basic（基本）：Basic 认证模式定义在 RFC 2617中。这个认证模式是不安全的，因为凭据以明文形式传 送。尽管它不安全，如果用在和 TLS/SSL加密的组合中，Basic认证模式是完全够用的。
• Digest（摘要）：摘要式认证方案在RFC 2617中定义。摘要式认证方案比Basic更安全，对于那些不希望通过TLS / SSL加密实现完全传输安全开销的应用程序来说，它可能是一个不错的选择。
• NTLM：NTLM是Microsoft开发的专用身份验证方案，针对Windows平台进行了优化。 NTLM被认为比Digest更安全。
• SPNEGO：SPNEGO（简单和受保护的GSSAPI协商机制）是一种GSSAPI“伪机制”，用于协商许多可能的实际机制之一。 SPNEGO最明显的用途是在Microsoft的HTTP协商认证扩展中。 可协商的子机制包括由Active Directory支持的NTLM和Kerberos。 目前HttpClient只支持Kerberos子机制。
• Kerberos:Kerberos身份验证实现。

4.3 凭据提供器

　　凭证提供程序旨在维护一组用户凭证，并能够为特定的认证范围生成用户凭证。 身份验证范围由主机名，端口号，领域名称和身份验证方案名称组成。 当向凭证提供者注册凭证时，可以提供通配符（任何主机，任何端口，任何领域，任何方案）而不是具体的属性值。 如果无法找到直接匹配，凭证提供程序将希望能够找到特定范围的最接近的匹配项。
HttpClient可以处理实现CredentialsProvider接口的凭证提供者的任何物理表示。 名为BasicCredentialsProvider的默认CredentialsProvider实现由java.util.HashMap支持。

CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(
    new AuthScope("somehost", AuthScope.ANY_PORT), 
    new UsernamePasswordCredentials("u1", "p1"));
credsProvider.setCredentials(
    new AuthScope("somehost", 8080), 
    new UsernamePasswordCredentials("u2", "p2"));
credsProvider.setCredentials(
    new AuthScope("otherhost", 8080, AuthScope.ANY_REALM, "ntlm"), 
    new UsernamePasswordCredentials("u3", "p3"));

System.out.println(credsProvider.getCredentials(
    new AuthScope("somehost", 80, "realm", "basic")));
System.out.println(credsProvider.getCredentials(
    new AuthScope("somehost", 8080, "realm", "basic")));
System.out.println(credsProvider.getCredentials(
    new AuthScope("otherhost", 8080, "realm", "basic")));
System.out.println(credsProvider.getCredentials(
    new AuthScope("otherhost", 8080, null, "ntlm")));

输出内容为：

[principal: u1]
[principal: u2]
null
[principal: u3]

4.4 HTTP 认证和执行上下文

　　HttpClient依靠AuthState类来跟踪有关身份验证过程的详细信息。 HttpClient在HTTP请求执行过程中创建两个AuthState实例：一个用于目标主机身份验证，另一个用于代理身份验证。 如果目标服务器或代理需要用户身份验证，则相应的AuthScope实例将使用在身份验证过程中使用的AuthScope，AuthScheme和Crednetials来填充。AuthState 可以被检查来找出请求的认证是什么类型的，是否匹配 AuthScheme 的实现，是否凭据提供器对给定的认证范围去找用户凭据。
在HTTP 请求执行的过程中，HttpClient 添加了下列和认证相关的对象到执行上下文中：

• Lookup实例代表实际的认证方案注册表。 在本地上下文中设置的这个属性的值优先于默认值。
• CredentialsProvider实例 代表实际的证书提供者。 在本地上下文中设置的这个属性的值优先于默认值。
• AuthState实例代表实际的目标认证状态。 在本地上下文中设置的这个属性的值优先于默认值。
• AuthCache实例 代表实际的认证数据缓存。 在本地上下文中设置的这个属性的值优先于默认值。
  可以使用本地HttpContext对象在请求执行之前自定义HTTP认证上下文，或者在请求执行后检查其状态：

CloseableHttpClient httpclient = <...>

CredentialsProvider credsProvider = <...>
Lookup<AuthSchemeProvider> authRegistry = <...>
AuthCache authCache = <...>

HttpClientContext context = HttpClientContext.create();
context.setCredentialsProvider(credsProvider);
context.setAuthSchemeRegistry(authRegistry);
context.setAuthCache(authCache);
HttpGet httpget = new HttpGet("http://somehost/");
CloseableHttpResponse response1 = httpclient.execute(httpget, context);
<...>

AuthState proxyAuthState = context.getProxyAuthState();
System.out.println("Proxy auth state: " + proxyAuthState.getState());
System.out.println("Proxy auth scheme: " + proxyAuthState.getAuthScheme());
System.out.println("Proxy auth credentials: " + proxyAuthState.getCredentials());
AuthState targetAuthState = context.getTargetAuthState();
System.out.println("Target auth state: " + targetAuthState.getState());
System.out.println("Target auth scheme: " + targetAuthState.getAuthScheme());
System.out.println("Target auth credentials: " + targetAuthState.getCredentials());

4.5 认证数据缓冲

从版本4.1开始，HttpClient会自动缓存已成功验证的主机信息。 请注意，必须使用相同的执行上下文来执行逻辑相关的请求，以使缓存的认证数据从一个请求传播到另一个请求。 执行上下文超出范围后，身份验证数据将立即丢失。

4.6. 抢先认证

HttpClient不支持抢先认证，因为如果错误使用或使用不当，抢先认证可能会导致重大的安全问题，例如以明文形式向未授权的第三方发送用户凭证。 因此，用户最好权衡好抢先认证与安全风险在他们的特定应用环境中。但是可以通过预先填充认证数据缓存来配置HttpClient进行抢先认证。

CloseableHttpClient httpclient = <...>

HttpHost targetHost = new HttpHost("localhost", 80, "http");
CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(
        new AuthScope(targetHost.getHostName(), targetHost.getPort()),
        new UsernamePasswordCredentials("username", "password"));

//创建 AuthCache实例
AuthCache authCache = new BasicAuthCache();
//生成BASIC方案对象并将其添加到本地身份验证缓存
BasicScheme basicAuth = new BasicScheme();
authCache.put(targetHost, basicAuth);

//将AuthCache添加到执行上下文
HttpClientContext context = HttpClientContext.create();
context.setCredentialsProvider(credsProvider);
context.setAuthCache(authCache);

HttpGet httpget = new HttpGet("/");
for (int i = 0; i < 3; i++) {
    CloseableHttpResponse response = httpclient.execute(
            targetHost, httpget, context);
    try {
        HttpEntity entity = response.getEntity();

    } finally {
        response.close();
    }
}

4.7 NTLM身份验证

从版本4.1开始，HttpClient提供对NTLMv1，NTLMv2和NTLM2会话认证的全面支持。 人们仍然可以继续使用由Samba项目开发的外部NTLM引擎（如JCIFS库）作为其Windows互操作性套件程序的一部分。

4.7.1. NTLM连接持久性

与标准的基本和摘要方案相比，NTLM认证方案在计算开销和性能影响方面明显更昂贵。这可能是微软选择使NTLM身份验证方案处于有状态的主要原因之一。也就是说，一旦通过身份验证，用户身份就与该连接的整个使用期限相关联。 NTLM连接的有状态性使得连接持久性更加复杂，因为持久性NTLM连接的明显原因可能不会被具有不同用户身份的用户重新使用。 HttpClient附带的标准连接管理器完全能够管理有状态的连接。然而，在同一个会话中，逻辑上相关的请求使用相同的执行上下文以使他们知道当前的用户身份是非常重要的。否则，HttpClient将最终为每个针对NTLM保护资源的HTTP请求创建一个新的HTTP连接。有关有状态HTTP连接的详细讨论，请参阅本节。
由于NTLM连接是有状态的，因此通常建议使用相对开销小的方法（如GET或HEAD）来触发NTLM身份验证，并重新使用相同的连接来执行更昂贵的方法，特别是那些包含请求实体（如POST或PUT）。

CloseableHttpClient httpclient = <...>

CredentialsProvider credsProvider = new BasicCredentialsProvider();
credsProvider.setCredentials(AuthScope.ANY,
        new NTCredentials("user", "pwd", "myworkstation", "microsoft.com"));

HttpHost target = new HttpHost("www.microsoft.com", 80, "http");

// 确保使用相同的上下文执行逻辑相关的请求
HttpClientContext context = HttpClientContext.create();
context.setCredentialsProvider(credsProvider);

//首先执行一个开销小的方法。 这将触发NTLM身份验证
HttpGet httpget = new HttpGet("/ntlm-protected/info");
CloseableHttpResponse response1 = httpclient.execute(target, httpget, context);
try {
    HttpEntity entity1 = response1.getEntity();
} finally {
    response1.close();
}

// 执行一个开销大的方法，然后重复使用相同的上下文（和连接）
HttpPost httppost = new HttpPost("/ntlm-protected/form");
httppost.setEntity(new StringEntity("lots and lots of data"));
CloseableHttpResponse response2 = httpclient.execute(target, httppost, context);
try {
    HttpEntity entity2 = response2.getEntity();
} finally {
    response2.close();
}

4.8 SPNEGO / Kerberos身份验证

SPNEGO（简单和受保护的GSSAPI协商机制）被设计为当两端都不知道对方能够使用/提供什么时，允许对服务进行认证。 这是最常用的Kerberos身份验证。 它可以包装其他机制，但是HttpClient中的当前版本仅仅考虑Kerberos。

4.8.1. SPNEGO支持HttpClient

SPNEGO身份验证方案与Sun Java 1.5及更高版本兼容。但强烈建议使用Java> = 1.6，因为它更完整地支持SPNEGO身份验证。
Sun JRE提供了几乎所有的Kerberos和SPNEGO令牌处理的支持类。这意味着很多设置是针对GSS类的。 SPNegoScheme是一个简单的类来处理编码和读写正确的头信息。
最好的方法是在示例中获取KerberosHttpClient.java文件，并尝试使其运行。有很多问题可以发生，但如果幸运的话，它将工作，没有太多的问题。它也应该提供一些输出来调试。
在Windows中，它应该默认使用登录的凭据;这可以通过使用例如’kinit’来覆盖。 $ JAVA_HOME bin kinit testuser@AD.EXAMPLE.NET，这对测试和调试问题非常有帮助。删除由kinit创建的缓存文件，以恢复到Windows Kerberos缓存。
确保在krb5.conf文件中列出domain_realms。这是问题的主要来源。

4.8.2. GSS / Java Kerberos安装程序

本文档假设您使用的是Windows，但大部分信息也适用于Unix。org.ietf.jgss类有很多可能的配置参数，主要是在krb5.conf / krb5.ini文件中。 有关格式的更多信息：http://web.mit.edu/kerberos/krb5-1.4/krb5-1.4.1/doc/krb5-admin/krb5.conf.html

4.8.3. login.conf文件

以下配置是在Windows XP中针对IIS和JBoss协商模块的基本设置。
系统属性java.security.auth.login.config可以用来指向login.conf文件。
login.conf内容可能如下所示：

com.sun.security.jgss.login {
  com.sun.security.auth.module.Krb5LoginModule required client=TRUE useTicketCache=true;
};

com.sun.security.jgss.initiate {
  com.sun.security.auth.module.Krb5LoginModule required client=TRUE useTicketCache=true;
};

com.sun.security.jgss.accept {
  com.sun.security.auth.module.Krb5LoginModule required client=TRUE useTicketCache=true;
};

4.8.4.krb5.conf / krb5.ini文件

如果未指定，将使用系统默认值。 通过设置系统属性java.security.krb5.conf指向一个自定义的krb5.conf文件来覆盖（如果需要）。
krb5.conf内容可能如下所示：

[libdefaults]
    default_realm = AD.EXAMPLE.NET
    udp_preference_limit = 1
[realms]
    AD.EXAMPLE.NET = {
        kdc = KDC.AD.EXAMPLE.NET
    }
[domain_realms]
.ad.example.net=AD.EXAMPLE.NET
ad.example.net=AD.EXAMPLE.NET

4.8.5. Windows特定配置

要允许Windows使用当前用户的权证，必须将系统属性javax.security.auth.useSubjectCredsOnly设置为false，并且应该添加并正确设置Windows注册表项allowtgtsessionkey，以允许在Kerberos Ticket-Granting中发送会话密钥权证。
在Windows Server 2003和Windows 2000 SP4上，这里是所需的注册表设置：

HKEY_LOCAL_MACHINESystemCurrentControlSetControlLsaKerberosParameters
Value Name: allowtgtsessionkey
Value Type: REG_DWORD
Value: 0x01

以下是Windows XP SP2中注册表设置的位置：

HKEY_LOCAL_MACHINESystemCurrentControlSetControlLsaKerberos
Value Name: allowtgtsessionkey
Value Type: REG_DWORD
Value: 0x01