You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2009/10/28 21:54:59 UTC
svn commit: r830758 - in
/httpcomponents/httpclient/branches/4.0.x/src/docbkx: advanced.xml
authentication.xml
Author: olegk
Date: Wed Oct 28 20:54:58 2009
New Revision: 830758
URL: http://svn.apache.org/viewvc?rev=830758&view=rev
Log:
Added detailed section on NTLM auth
Modified:
httpcomponents/httpclient/branches/4.0.x/src/docbkx/advanced.xml
httpcomponents/httpclient/branches/4.0.x/src/docbkx/authentication.xml
Modified: httpcomponents/httpclient/branches/4.0.x/src/docbkx/advanced.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/branches/4.0.x/src/docbkx/advanced.xml?rev=830758&r1=830757&r2=830758&view=diff
==============================================================================
--- httpcomponents/httpclient/branches/4.0.x/src/docbkx/advanced.xml (original)
+++ httpcomponents/httpclient/branches/4.0.x/src/docbkx/advanced.xml Wed Oct 28 20:54:58 2009
@@ -120,7 +120,7 @@
</listitem>
</itemizedlist>
</section>
- <section>
+ <section id="stateful_conn">
<title>Stateful HTTP connections</title>
<para>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.</para>
</formalpara>
+ </listitem>
+ <listitem>
<formalpara>
<title>Digest</title>
<para>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.</para>
</formalpara>
+ </listitem>
+ <listitem>
<formalpara>
<title>NTLM:</title>
<para>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
- <literal>NTLM_SUPPORT.txt</literal> document included with HttpClient
- distributions.</para>
+ Digest. This scheme is requires an external NTLM engine to be functional.
+ For details please refer to the <literal>NTLM_SUPPORT.txt</literal> document
+ included with HttpClient distributions.</para>
</formalpara>
</listitem>
</itemizedlist>
@@ -126,6 +129,8 @@
If this parameter is not set HttpClient will handle authentication
automatically.</para>
</formalpara>
+ </listitem>
+ <listitem>
<formalpara>
<title>'http.auth.credential-charset':</title>
<para>defines the charset to be used when encoding user credentials. This
@@ -146,16 +151,18 @@
<title>Basic:</title>
<para>Basic authentication scheme</para>
</formalpara>
+ </listitem>
+ <listitem>
<formalpara>
<title>Digest:</title>
<para>Digest authentication scheme</para>
</formalpara>
</listitem>
</itemizedlist>
- <para>Please note <literal>NTLM</literal> scheme is <emphasis>NOT</emphasis> registered per
- default. For details on how to enable <literal>NTLM</literal> support please refer to
- the <literal>NTLM_SUPPORT.txt</literal> document included with HttpClient
- distributions.</para>
+ <para>Please note <literal>NTLM</literal> scheme is <emphasis>NOT</emphasis> registered per
+ default. The <literal>NTLM</literal> cannot be enabled per default due to licensing and
+ legal reasons. For details on how to enable <literal>NTLM</literal> support please see
+ <link linkend="ntlm">this</link> section. </para>
</section>
<section>
<title>Credentials provider</title>
@@ -225,18 +232,24 @@
authentication scheme registry. The value of this attribute set in the local
context takes precedence over the default one.</para>
</formalpara>
+ </listitem>
+ <listitem>
<formalpara>
<title>'http.auth.credentials-provider':</title>
<para><interfacename>CookieSpec</interfacename> instance representing the actual
credentials provider. The value of this attribute set in the local context
takes precedence over the default one.</para>
</formalpara>
+ </listitem>
+ <listitem>
<formalpara>
<title>'http.auth.target-scope':</title>
<para><classname>AuthState</classname> instance representing the actual target
authentication state. The value of this attribute set in the local context
takes precedence over the default one.</para>
</formalpara>
+ </listitem>
+ <listitem>
<formalpara>
<title>'http.auth.proxy-scope':</title>
<para><classname>AuthState</classname> instance representing the actual proxy
@@ -315,4 +328,70 @@
httpclient.addRequestInterceptor(preemptiveAuth, 0);
]]></programlisting>
</section>
+
+ <section id="ntlm">
+ <title>NTLM Authentication</title>
+ <para>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
+ <literal>NTLM</literal> engine such as <ulink url="http://jcifs.samba.org/">JCIFS
+ </ulink> library developed by the <ulink url="http://www.samba.org/">Samba</ulink>
+ project as a part of their Windows interoperability suite of programs. For details
+ please refer to the <literal>NTLM_SUPPORT.txt</literal> document included with
+ HttpClient distributions.
+ </para>
+ <section>
+ <title>NTLM connection persistence</title>
+ <para><literal>NTLM</literal> authentication scheme is significantly more expensive
+ in terms of computational overhead and performance impact than the standard
+ <literal>Basic</literal> and <literal>Digest</literal> schemes. This is likely to be
+ one of the main reasons why Microsoft chose to make <literal>NTLM</literal>
+ authentication scheme stateful. That is, once authenticated, the user identity is
+ associated with that connection for its entire life span. The stateful nature of
+ <literal>NTLM</literal> connections makes connection persistence more complex, as
+ for the obvious reason persistent <literal>NTLM</literal> 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 <literal>NTLM</literal> protected resources. For detailed
+ discussion on stateful HTTP connections please refer to
+ <link linkend="stateful_conn">this </link> section. </para>
+ <para>As <literal>NTLM</literal> connections are stateful it is generally recommended
+ to trigger <literal>NTLM</literal> authentication using a relatively cheap method,
+ such as <literal>GET</literal> or <literal>HEAD</literal>, and re-use the same
+ connection to execute more expensive methods, especially those enclose a request
+ entity, such as <literal>POST</literal> or <literal>PUT</literal>. </para>
+ <programlisting><![CDATA[
+DefaultHttpClient httpclient = new DefaultHttpClient();
+
+NTCredentials creds = new NTCredentials("user", "pwd", "myworkstation", "microsoft.com");
+httpclient.getCredentialsProvider().setCredentials(AuthScope.ANY, creds);
+
+HttpHost target = new HttpHost("www.microsoft.com", 80, "http");
+
+// Make sure the same context is used to execute logically related requests
+HttpContext localContext = new BasicHttpContext();
+
+// Execute a cheap method first. This will trigger NTLM authentication
+HttpGet httpget = new HttpGet("/ntlm-protected/info");
+HttpResponse response1 = httpclient.execute(target, httpget, localContext);
+HttpEntity entity1 = response1.getEntity();
+if (entity1 != null) {
+ entity1.consumeContent();
+}
+
+// Execute an expensive method next reusing the same context (and connection)
+HttpPost httppost = new HttpPost("/ntlm-protected/form");
+httppost.setEntity(new StringEntity("lots and lots of data"));
+HttpResponse response2 = httpclient.execute(target, httppost, localContext);
+HttpEntity entity2 = response2.getEntity();
+if (entity2 != null) {
+ entity2.consumeContent();
+}
+]]></programlisting>
+ </section>
+ </section>
+
</chapter>