hc-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ol...@apache.org
Subject svn commit: r830754 - in /httpcomponents/httpclient/trunk/src/docbkx: advanced.xml authentication.xml
Date Wed, 28 Oct 2009 20:38:55 GMT
Author: olegk
Date: Wed Oct 28 20:38:54 2009
New Revision: 830754

URL: http://svn.apache.org/viewvc?rev=830754&view=rev
Added detailed section on NTLM auth


Modified: httpcomponents/httpclient/trunk/src/docbkx/advanced.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/advanced.xml?rev=830754&r1=830753&r2=830754&view=diff
--- httpcomponents/httpclient/trunk/src/docbkx/advanced.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/advanced.xml Wed Oct 28 20:38:54 2009
@@ -120,7 +120,7 @@
-    <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

Modified: httpcomponents/httpclient/trunk/src/docbkx/authentication.xml
URL: http://svn.apache.org/viewvc/httpcomponents/httpclient/trunk/src/docbkx/authentication.xml?rev=830754&r1=830753&r2=830754&view=diff
--- httpcomponents/httpclient/trunk/src/docbkx/authentication.xml (original)
+++ httpcomponents/httpclient/trunk/src/docbkx/authentication.xml Wed Oct 28 20:38:54 2009
@@ -109,10 +109,9 @@
                     <para>NTLM is a proprietary authentication scheme developed by
Microsoft and
                         optimized for Windows platforms. NTLM is believed to be more secure
-                        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>
+                        included with HttpClient distributions.</para>
@@ -206,12 +205,12 @@
         <para>Please note <literal>NTLM</literal> and <literal>SPNEGO</literal>
schemes are
-                <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
-                <literal>SPNEGO</literal> setup tends to be system specific and
must be properly
-            configured in order to be functional. See section on <link linkend="spnego">SPNEGO
-            authentication </link> for details.</para>
+                <emphasis>NOT</emphasis> registered per default. The <literal>NTLM</literal>
+            be enabled per default due to licensing and legal reasons. For details on how
+            enable <literal>NTLM</literal> support please see <link linkend="ntlm">this</link>
+            section. <literal>SPNEGO</literal> setup tends to be system specific
and must be 
+            properly configured in order to be functional. See <link linkend="spnego">this
+            section for details. </para>
         <title>Credentials provider</title>
@@ -378,6 +377,71 @@
+    <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
+                associated with that connection for its entire life span. The stateful nature
+                <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
+                shipped with HttpClient are fully capable of managing stateful connections.
+                it is critically important that logically related requests within the same
+                use the same execution context in order to make them aware of the current
+                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
+                entity, such as <literal>POST</literal> or <literal>PUT</literal>.
+            <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();
+        </section>
+    </section>
     <section id="spnego">
         <title><literal>SPNEGO</literal>/Kerberos Authentication</title>
         <para><literal>SPNEGO</literal> (<emphasis>S</emphasis>imple

View raw message