Support for NTLMv2 with Apache HttpClient using JCIFS

Here, I'll explain how to get NTLMv2 support in HttpClient 3.x using JCIFS by using 1 addditional class and inserting 1 new line into your existing calls to HttpClient.
Of course you can use JCIFS NTLM authentication directly in Java even if you don't have Apache HttpClient - I'm not looking at that but you can refer to this guide on JCIFS home page.

HttpClient

Apache's HttpClient provides some useful encapsulation for fetching/posting data over HTTP through Java code. The common version is HttpClient 3.x whereas the latest version is HttpClient 4.x.

NTLM

One of HttpClient's advantages is that it has built in support to manage communications over an NTLM proxy.

NTLM is a very closely guarded Proxy protocol used by Microsoft but still popularly used.

JCIFS

Unfortunately, HttpClient does not have built in support for NTLM v2. The good news is, it allows you to integrate NTLMv2 support through another library called JCIFS.

JCIFS is an Open Source  client library that implements the CIFS/SMB networking protocol in 100% Java. See more details/download from here. But since JCIFS started NTLMv2 support only from 1.3.0, make sure you have the latest JCIFS jar (I tested with JCIFS 1.3.14).

JCIFS in HttpClient

Thankfully, HttpClient 4.x home site has a page containing unofficial steps for integrating JCIFS into HTTPClient. However, these steps will only work for 4.x and not for for 3.x. This is because HttpClient 4.x is not backward compatible with 3.x. There are major changes like package structures, new Engines instead of States, etc.

Since I was using HttpClient 3.x, I started thinking of upgrading to 4.x – but it was obvious upgrading to 4.x from 3.x was a nightmare just to get NTLMv2 support.

Thankfully, it was just a matter of understanding HttpClient 3.x internal calls from the source. I was able to create 1 simple class that will do the integration in 1 smooth move.

Steps and source-code

1)      I created a new class, JCIFS_NTLMScheme.java that would be used in place of HTTPClient's NTLMScheme.

This new class simply makes calls to JCIFS internally to generate NTLMv2's Type1, 2 and 3 messages- just reimplemented the methods with slight logic changes to generate the messages:

package org.xyz;

import java.io.IOException;

import org.apache.commons.httpclient.Credentials;

import org.apache.commons.httpclient.HttpMethod;

import org.apache.commons.httpclient.NTCredentials;

import org.apache.commons.httpclient.auth.AuthChallengeParser;

import org.apache.commons.httpclient.auth.AuthScheme;

import org.apache.commons.httpclient.auth.AuthenticationException;

import org.apache.commons.httpclient.auth.InvalidCredentialsException;

import org.apache.commons.httpclient.auth.MalformedChallengeException;

import org.sac.crosspather.common.util.AppLogger;

import org.sac.crosspather.common.util.HTTPHelper;

/**

 * This is a reimplementation of HTTPClient 3.x's

 * org.apache.commons.httpclient.auth.NTLMScheme.<BR/>

 * It will basically use JCIFS (v1.3.15) in order to provide added support for

 * NTLMv2 (instead of trying to create its own Type, 2 and 3 messages). <BR/>

 * This class has to be registered manually with HTTPClient before setting

 * NTCredentials: AuthPolicy.registerAuthScheme(AuthPolicy.NTLM,

 * JCIFS_NTLMScheme.class); <BR/>

 * Will <B>not</B> work with HttpClient 4.x which requires AuthEngine to be overriden instead of AuthScheme.

 *

 * @author Sachin M

 */

public class JCIFS_NTLMScheme implements AuthScheme {

       private static AppLogger logger = new AppLogger(HTTPHelper.class.getName());

       /** NTLM challenge string. */

       private String ntlmchallenge = null;

       private static final int UNINITIATED = 0;

       private static final int INITIATED = 1;

       private static final int TYPE1_MSG_GENERATED = 2;

       private static final int TYPE2_MSG_RECEIVED = 3;

       private static final int TYPE3_MSG_GENERATED = 4;

       private static final int FAILED = Integer.MAX_VALUE;

       /** Authentication process state */

       private int state;

       public JCIFS_NTLMScheme() throws AuthenticationException {

              // Check if JCIFS is present. If not present, do not proceed.

              try {

                     Class.forName("jcifs.ntlmssp.NtlmMessage",false,this.getClass().getClassLoader());

              } catch (ClassNotFoundException e) {

                     throw new AuthenticationException("Unable to proceed as JCIFS library is not found.");

              }

       }

      

       public String authenticate(Credentials credentials, HttpMethod method)

                     throws AuthenticationException {

              logger.doLog(AppLogger.FINEST,

                           "Enter JCIFS_NTLMScheme.authenticate(Credentials, HttpMethod)",

                           null);

              if (this.state == UNINITIATED) {

                     throw new IllegalStateException(

                                  "NTLM authentication process has not been initiated");

              }

              NTCredentials ntcredentials = null;

              try {

                     ntcredentials = (NTCredentials) credentials;

              } catch (ClassCastException e) {

                     throw new InvalidCredentialsException(

                                  "Credentials cannot be used for NTLM authentication: "

                                                + credentials.getClass().getName());

              }

             

              NTLM ntlm = new NTLM();

              ntlm.setCredentialCharset(method.getParams().getCredentialCharset());

              String response = null;

              if (this.state == INITIATED || this.state == FAILED) {

                     response = ntlm.generateType1Msg(ntcredentials.getHost(),

                                  ntcredentials.getDomain());

                     this.state = TYPE1_MSG_GENERATED;

              } else {

                     response = ntlm.generateType3Msg(ntcredentials.getUserName(),

                                  ntcredentials.getPassword(), ntcredentials.getHost(),

                                  ntcredentials.getDomain(), this.ntlmchallenge);

                     this.state = TYPE3_MSG_GENERATED;

              }

              return "NTLM " + response;

       }

       public String authenticate(Credentials credentials, String method,

                     String uri) throws AuthenticationException {

              throw new RuntimeException(

                           "Not implemented as it is deprecated anyway in Httpclient 3.x");

       }

       public String getID() {

              throw new RuntimeException(

                           "Not implemented as it is deprecated anyway in Httpclient 3.x");

       }

       /**

        * Returns the authentication parameter with the given name, if available.

        *

        * <p>

        * There are no valid parameters for NTLM authentication so this method

        * always returns <tt>null</tt>.

        * </p>

        *

        * @param name

        *            The name of the parameter to be returned

        *

        * @return the parameter with the given name

        */

       public String getParameter(String name) {

              if (name == null) {

                     throw new IllegalArgumentException("Parameter name may not be null");

              }

              return null;

       }

       /**

        * The concept of an authentication realm is not supported by the NTLM

        * authentication scheme. Always returns <code>null</code>.

        *

        * @return <code>null</code>

        */

       public String getRealm() {

              return null;

       }

       /**

        * Returns textual designation of the NTLM authentication scheme.

        *

        * @return <code>ntlm</code>

        */

       public String getSchemeName() {

              return "ntlm";

       }

       /**

        * Tests if the NTLM authentication process has been completed.

        *

        * @return <tt>true</tt> if Basic authorization has been processed,

        *         <tt>false</tt> otherwise.

        *

        * @since 3.0

        */

       public boolean isComplete() {

              return this.state == TYPE3_MSG_GENERATED || this.state == FAILED;

       }

       /**

        * Returns <tt>true</tt>. NTLM authentication scheme is connection based.

        *

        * @return <tt>true</tt>.

        *

        * @since 3.0

        */

       public boolean isConnectionBased() {

              return true;

       }

       /**

        * Processes the NTLM challenge.

        *

        * @param challenge

        *            the challenge string

        *

        * @throws MalformedChallengeException

        *             is thrown if the authentication challenge is malformed

        *

        * @since 3.0

        */

       public void processChallenge(final String challenge)

                     throws MalformedChallengeException {

              String s = AuthChallengeParser.extractScheme(challenge);

              if (!s.equalsIgnoreCase(getSchemeName())) {

                     throw new MalformedChallengeException("Invalid NTLM challenge: "

                                  + challenge);

              }

              int i = challenge.indexOf(' ');

              if (i != -1) {

                     s = challenge.substring(i, challenge.length());

                     this.ntlmchallenge = s.trim();

                     this.state = TYPE2_MSG_RECEIVED;

              } else {

                     this.ntlmchallenge = "";

                     if (this.state == UNINITIATED) {

                           this.state = INITIATED;

                     } else {

                           this.state = FAILED;

                     }

              }

       }

       private class NTLM {

           /** Character encoding */

           public static final String DEFAULT_CHARSET = "ASCII";

          

           /**

               * The character was used by 3.x's NTLM to encode the username and

               * password. Apparently, this is not needed in when passing username,

               * password from NTCredentials to the JCIFS library

               */

           private String credentialCharset = DEFAULT_CHARSET;

          

              void setCredentialCharset(String credentialCharset) {

                     this.credentialCharset = credentialCharset;

              }

              private String generateType1Msg(String host, String domain) {

                     jcifs.ntlmssp.Type1Message t1m = new jcifs.ntlmssp.Type1Message(jcifs.ntlmssp.Type1Message.getDefaultFlags(),

                                  domain, host);

                     return jcifs.util.Base64.encode(t1m.toByteArray());

              }

              private String generateType3Msg(String username, String password, String host,

                           String domain, String challenge) {

                     jcifs.ntlmssp.Type2Message t2m;

                     try {

                           t2m = new jcifs.ntlmssp.Type2Message(jcifs.util.Base64.decode(challenge));

                     } catch (IOException e) {

                           throw new RuntimeException("Invalid Type2 message", e);

                     }

                     jcifs.ntlmssp.Type3Message t3m = new jcifs.ntlmssp.Type3Message(t2m, password, domain,

                                  username, host, 0);

                     return jcifs.util.Base64.encode(t3m.toByteArray());

              }

       }

}

2)      Then it was Register the new JCIFS_NTLMScheme class as the replacement for NTLMScheme by using the following command:

AuthPolicy.registerAuthScheme(AuthPolicy.NTLM, org.xyz.JCIFS_NTLMScheme.class);

 (AuthPolicy is a class in HTTPClient 3.x jar)

That's it! Use your HTTPClient as normal but just make sure you call the above register command before you create and bind the HttpClient's NTCredentials class