Stateful HTTP connections

Stateful HTTP connections While HTTP specification assumes that session state information is always embedded in HTTP messages in the form of HTTP cookies and therefore HTTP connections are always Modified: httpcomponents/httpclient/branches/4.0.x/src/docbkx/authentication.xml URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/branches/4.0.x/src/docbkx/authentication.xml?rev=830758&r1=830757&r2=830758&view=diff ============================================================================== --- httpcomponents/httpclient/branches/4.0.x/src/docbkx/authentication.xml (original) +++ httpcomponents/httpclient/branches/4.0.x/src/docbkx/authentication.xml Wed Oct 28 20:54:58 2009 @@ -94,6 +94,8 @@ Despite its insecurity Basic authentication scheme is perfectly adequate if used in combination with the TLS/SSL encryption. + + Digest Digest authentication scheme as defined in RFC 2617. Digest authentication @@ -101,14 +103,15 @@ those applications that do not want the overhead of full transport security through TLS/SSL encryption. + + NTLM: NTLM is a proprietary authentication scheme developed by Microsoft and optimized for Windows platforms. NTLM is believed to be more secure than - Digest. This scheme is supported only partially and requires an external - NTLM engine. For details please refer to the - NTLM_SUPPORT.txt document included with HttpClient - distributions. + Digest. This scheme is requires an external NTLM engine to be functional. + For details please refer to the NTLM_SUPPORT.txt document + included with HttpClient distributions. @@ -126,6 +129,8 @@ If this parameter is not set HttpClient will handle authentication automatically. + + 'http.auth.credential-charset': defines the charset to be used when encoding user credentials. This @@ -146,16 +151,18 @@ Basic: Basic authentication scheme + + Digest: Digest authentication scheme - Please note NTLM scheme is NOT registered per - default. For details on how to enable NTLM support please refer to - the NTLM_SUPPORT.txt document included with HttpClient - distributions. + Please note NTLM scheme is NOT registered per + default. The NTLM cannot be enabled per default due to licensing and + legal reasons. For details on how to enable NTLM support please see + this section.

Credentials provider @@ -225,18 +232,24 @@ authentication scheme registry. The value of this attribute set in the local context takes precedence over the default one. + + 'http.auth.credentials-provider': CookieSpec instance representing the actual credentials provider. The value of this attribute set in the local context takes precedence over the default one. + + 'http.auth.target-scope': AuthState instance representing the actual target authentication state. The value of this attribute set in the local context takes precedence over the default one. + + 'http.auth.proxy-scope': AuthState instance representing the actual proxy @@ -315,4 +328,70 @@ httpclient.addRequestInterceptor(preemptiveAuth, 0); ]]>

+ +

+ NTLM Authentication + Currently HttpClient does not provide support for the NTLM authentication scheme out + of the box and probably never will. The reasons for that are legal rather than + technical. However, NTLM authentication can be enabled by using an external + NTLM engine such as JCIFS + library developed by the Samba + project as a part of their Windows interoperability suite of programs. For details + please refer to the NTLM_SUPPORT.txt document included with + HttpClient distributions. + +

+ NTLM connection persistence + NTLM authentication scheme is significantly more expensive + in terms of computational overhead and performance impact than the standard + Basic and Digest schemes. This is likely to be + one of the main reasons why Microsoft chose to make NTLM + authentication scheme stateful. That is, once authenticated, the user identity is + associated with that connection for its entire life span. The stateful nature of + NTLM connections makes connection persistence more complex, as + for the obvious reason persistent NTLM connections may not be + re-used by users with a different user identity. The standard connection managers + shipped with HttpClient are fully capable of managing stateful connections. However, + it is critically important that logically related requests within the same session + use the same execution context in order to make them aware of the current user + identity. Otherwise, HttpClient will end up creating a new HTTP connection for each + HTTP request against NTLM protected resources. For detailed + discussion on stateful HTTP connections please refer to + this section. + As NTLM connections are stateful it is generally recommended + to trigger NTLM authentication using a relatively cheap method, + such as GET or HEAD, and re-use the same + connection to execute more expensive methods, especially those enclose a request + entity, such as POST or PUT. + +