~~ ==================================================================== ~~ Licensed to the Apache Software Foundation (ASF) under one ~~ or more contributor license agreements. See the NOTICE file ~~ distributed with this work for additional information ~~ regarding copyright ownership. The ASF licenses this file ~~ to you under the Apache License, Version 2.0 (the ~~ "License"); you may not use this file except in compliance ~~ with the License. You may obtain a copy of the License at ~~ ~~ http://www.apache.org/licenses/LICENSE-2.0 ~~ ~~ Unless required by applicable law or agreed to in writing, ~~ software distributed under the License is distributed on an ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY ~~ KIND, either express or implied. See the License for the ~~ specific language governing permissions and limitations ~~ under the License. ~~ ==================================================================== ~~ ~~ This software consists of voluntary contributions made by many ~~ individuals on behalf of the Apache Software Foundation. For more ~~ information on the Apache Software Foundation, please see ~~ . ---------- NTLM support in HttpClient ---------- ---------- ---------- NTLM support in HttpClient Currently HttpClient 4.0 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. * {Background} NTLM is a proprietary authentication scheme developed by Microsoft and optimized for Windows operating system. Until year 2008 there was no official, publicly available, complete documentation of the protocol. {{{http://davenport.sourceforge.net/ntlm.html}Unofficial}} 3rd party protocol descriptions existed as a result of reverse-engineering efforts. It was not really known whether the protocol based on the reverse-engineering were complete or even correct. Microsoft published {{{http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NLMP%5D.pdf}MS-NLMP}} and {{{http://download.microsoft.com/download/a/e/6/ae6e4142-aa58-45c6-8dcf-a657e5900cd3/%5BMS-NTHT%5D.pdf}MS-NTHT}} specifications in February 2008 as a part of its {{{http://www.microsoft.com/interop/principles/default.mspx}Interoperability Principles initiative}}. Unfortunately, it is still not entirely clear whether NTLM encryption algorithms are covered by any patents held by Microsoft, which would make commercial users of open-source NTLM implementations liable for the use of Microsoft intellectual property. * {Enabling NTLM support in HttpClient 4.x} The good news is HttpClient is fully NTLM capable right out of the box. HttpClient ships with the NTLM authentication scheme, which, if configured to use an external NTLM engine, can handle NTLM challenges and authenticate against NTLM servers. ---------------------------------------- public interface NTLMEngine { String generateType1Msg( String domain, String workstation) throws NTLMEngineException; String generateType3Msg( String username, String password, String domain, String workstation, String challenge) throws NTLMEngineException; } ---------------------------------------- * {Using Samba JCIFS as an NTLM engine} Follow these instructions to build an NTLMEngine implementation using JCIFS library <>. * Download the latest release of the JCIFS library from the {{{http://jcifs.samba.org/}Samba}} web site * Implement NTLMEngine interface ---------------------------------------- import jcifs.ntlmssp.Type1Message; import jcifs.ntlmssp.Type2Message; import jcifs.ntlmssp.Type3Message; import jcifs.util.Base64; import org.apache.http.impl.auth.NTLMEngine; import org.apache.http.impl.auth.NTLMEngineException; public class JCIFSEngine implements NTLMEngine { public String generateType1Msg( String domain, String workstation) throws NTLMEngineException { Type1Message t1m = new Type1Message( Type1Message.getDefaultFlags(), domain, workstation); return Base64.encode(t1m.toByteArray()); } public String generateType3Msg( String username, String password, String domain, String workstation, String challenge) throws NTLMEngineException { Type2Message t2m; try { t2m = new Type2Message(Base64.decode(challenge)); } catch (IOException ex) { throw new NTLMEngineException("Invalid Type2 message", ex); } Type3Message t3m = new Type3Message( t2m, password, domain, username, workstation); return Base64.encode(t3m.toByteArray()); } } ---------------------------------------- * Implement AuthSchemeFactory interface ---------------------------------------- import org.apache.http.auth.AuthScheme; import org.apache.http.auth.AuthSchemeFactory; import org.apache.http.impl.auth.NTLMScheme; import org.apache.http.params.HttpParams; public class NTLMSchemeFactory implements AuthSchemeFactory { public AuthScheme newInstance(final HttpParams params) { return new NTLMScheme(new JCIFSEngine()); } } ---------------------------------------- * Register NTLMSchemeFactory with the HttpClient instance you want to NTLM enable. ---------------------------------------- httpclient.getAuthSchemes().register("ntlm", new NTLMSchemeFactory()); ---------------------------------------- * Set NTCredentials for the web server you are going to access. ---------------------------------------- httpclient.getCredentialsProvider().setCredentials( new AuthScope("myserver", -1), new NTCredentials("username", "password", "MYSERVER", "MYDOMAIN")); ----------------------------------------------------------- * You are done. * {Why this code is not distributed with HttpClient} JCIFS is licensed under the Lesser General Public License (LGPL). This license is not compatible with the Apache Licenses under which all Apache Software is released. Lawyers of the Apache Software Foundation are currently investigating under which conditions Apache software is allowed to make use of LGPL software.