HTTPCLIENT-523: SPNEGO auth scheme

* Updated example
* Minor code tweaks
 
Contributed by Matthew Stevenson <mavricknzwork at yahoo.dot> 


git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpclient/trunk@815735 13f79535-47bb-0310-9956-ffa450edef68

httpclient/src/examples/org/apache/http/examples/client/ClientKerberosAuthentication.java

@@ -52,8 +52,31 @@ import org.apache.http.protocol.HttpContext;
 
 /**
  * Kerberos auth example.
- * <p>
+ * 
- * <b>krb5.conf</b>
+ * <p>Takes one arguement args[0] = 'http://examplehost/path/'</p>
+ * <h5>Information</h5>
+ * <p>For the best compatibility use Java >= 1.6 as it supports SPNEGO authentication more 
+      completely.</p>
+ * <p><em>NegotiateSchemeFactory</em></p>
+ * <p>Has three custom methods</p>
+ * <p><em>setStripPort(boolean)</em> - default is false, with strip the port off the Kerberos
+ * service name if true. Found useful with JbossNegotiation. Java >= 1.5</p>
+ * 
+ * <p>Below are for Java 1.5.</p>
+ * 
+ * <p><em>setSpnegoCreate(boolean)</em> - defaults to false, try to create an SPNEGO token via
+ * the token set in setSpengoGenerator. TODO - merge logic so just setSpengoGenerator</p>
+ * 
+ * <p><em>setSpengoGenerator(new SpnegoTokenGenerator())</em> - default is null, class to use to wrap
+ * kerberos token. An example is in contrib - <em>org.apache.http.contrib.auth.BouncySpnegoTokenGenerator</em>.
+ * Requires use of <a href="http://www.bouncycastle.org/java.html">bouncy castle libs</a>
+ * </p>
+ * 
+ * <h6>Addtional Config Files</h6>
+ * <p>Two files control how Java uses/configures Kerberos. Very basic examples are below. There
+ * is a large amount of information on the web.</p>
+ * <p><a href="http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html">http://java.sun.com/j2se/1.5.0/docs/guide/security/jaas/spec/com/sun/security/auth/module/Krb5LoginModule.html</a>
+ * <p><b>krb5.conf</b></p>
  * <pre>
  * [libdefaults]
  *     default_realm = AD.EXAMPLE.NET
@@ -122,16 +145,19 @@ public class ClientKerberosAuthentication {
 
         DefaultHttpClient httpclient = new DefaultHttpClient();
 
+        /* NegotiateSchemeFactory creates the NegotiateScheme instance to be use for each request
+         * if using Java 5/6 and IIS7 you can just use the defaults. JbossNegotiate use setStripPort(true),
+         * or add service names with ports to kerberos DB. JbossNegotiate needs Java 6 or a SpengoGenerator.
+         */
+        NegotiateSchemeFactory negotiateFact = new NegotiateSchemeFactory();
+//        negotiateFact.setStripPort(false);
+//        negotiateFact.setSpnegoCreate(true);
+//        negotiateFact.setSpengoGenerator(new BouncySpnegoTokenGenerator());
+        
         AuthSchemeRegistry authSchemeRegistry = httpclient.getAuthSchemes();
         authSchemeRegistry.unregister("basic");
         authSchemeRegistry.unregister("digest");
         authSchemeRegistry.unregister("NTLM");
-        
-        NegotiateSchemeFactory negotiateFact = new NegotiateSchemeFactory();
-        negotiateFact.setStripPort(false);
-        negotiateFact.setSpnegoCreate(false);
-//        negotiateFact.setSpengoGenerator(new BouncySpnegoTokenGenerator());
-        
         authSchemeRegistry.register("Negotiate", negotiateFact);
 //        authSchemeRegistry.register("NTLM", new NTLMSchemeFactory());
 //        authSchemeRegistry.register("Basic", new BasicSchemeFactory());

httpclient/src/main/java/org/apache/http/impl/auth/NegotiateSchemeFactory.java

@@ -40,7 +40,7 @@ public class NegotiateSchemeFactory implements AuthSchemeFactory {
         negotiateScheme.setStripPort(stripPort);
         negotiateScheme.setSpnegoCreate(spnegoCreate);
         negotiateScheme.setSpengoGenerator(spengoGenerator);
-        return new NegotiateScheme();
+        return negotiateScheme;
     }
 
     public NegotiateSchemeFactory(){

src/docbkx/authentication.xml

@@ -94,6 +94,8 @@ pwd
                         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,6 +103,8 @@ pwd
                         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
@@ -126,6 +130,8 @@ pwd
                         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,6 +152,8 @@ pwd
                     <title>Basic:</title>
                     <para>Basic authentication scheme</para>
                 </formalpara>
+            </listitem>
+            <listitem>
                 <formalpara>
                     <title>Digest:</title>
                     <para>Digest authentication scheme</para>
@@ -225,18 +233,24 @@ null
                         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