Friday, May 8, 2015

NTLM Authentication WSO2 ESB (Developer Testing)


Thought of writing this blog as I got few queries on how ESB can be configured to communicate services which are secured with NTLM (which is also is known as Windows Authentication), please refer [1] to learn more information on NTLM
  When comes with WSO2 ESB we do not have OOTB approach to resolve this puzzle, we have tried  to add pass-through support for NTLM. But, there seems to be inherent technical problems in NTLM standard it self preventing it to work through a proxy.
NTLM is connection oriented, based on connection state. It authenticates the connection - not really the end user.
Kerberos is the preferred choice to connect through proxy servers than NTLM, due to the connection-based nature of NTLM.
When a client needs to authenticate itself to a proxy or server using the NTLM scheme then the following 4-way handshake takes place
1: C -> S GET ...
2: S -> C 401 Unauthorized
WWW-Authenticate: NTLM
3: C -> S GET ...
Authorization: NTLM <type-1-message>
4: S -> C 401 Unauthorized
WWW-Authenticate: NTLM <type-2-message>
5: C -> S GET ...
Authorization: NTLM <type-3-message>
6: S -> C 200 Ok
This manifests itself states that the network connection must be kept alive during the second part of the handshake,i.e. between the receiving of the type-2 message from the server (step 4) and the sending of the type-3 message (step 5). Each time the connection is closed this second part (steps 3 through 6) must be repeated over the new connection (i.e. it's not enough to just keep sending the last type-3 message).
Also, once the connection is authenticated, the Authorization header need not be sent anymore while the connection stays open, no matter what resource is accessed.
Microsoft also emphasizes that NTLM requires implicit end-to-end state and will not work through a proxy server.
So how we have overcome
  since we need to maintain "NTLM is connection oriented, based on connection state.", the solution we came is to use Class Mediator and CalloutMediator approach

Ok, lets start from the beginning, (for novice users this might helpful as I will go through setting up NTLM service from VM which has Windows 7)

Setup NTLM service in Windows

  • (Assume you have installed IIS service from windows features), Then need to enable Windows Authentication

  • Then you need to navigate to IIS admin service and enable Windows authentication for a selected site

  • Since this a developer testing, I will create a WCF service and host the created service under IIS

  • When you try to deploy the created WCF service from Microsoft Visual Studio few errors can be thrown and there are solutions being discussed under [2][3]
    • Config Error: This configuration section cannot be used at this path. This happens when the section is locked at a parent level. Locking is either by default (overrideModeDefault="Deny"), or set explicitly by a location tag with overrideMode="Deny" or the legacy allowOverride="false".
    • The authentication schemes configured on the host ('IntegratedWindowsAuthentication') do not allow those configured on the binding 'BasicHttpBinding' ('Anonymous'). Please ensure that the SecurityMode is set to Transport or TransportCredentialOnly. Additionally, this may be resolved by changing the authentication schemes for this application through the IIS management tool, through the ServiceHost.Authentication.AuthenticationSchemes property, in the application configuration file at the element, by updating the ClientCredentialType property on the binding, or by adjusting the AuthenticationScheme property on the HttpTransportBindingElement
  • If you successfully deploy service then when accessing the service it should look as

  • If you enter invalid Windows Credentials result would be

  • Successful invocation will results as

Setup WSO2 ESB
  • HttpClient has improved NTLM support please refer [4] for the relevant technical detail
  • Written simple client to test NTLM communication, client can be found from here

    • Invalid Request

  • And we have written a class mediator by referring the same NTLMClient i.e NTLMMediator, and once download you need to compile to OSGI jar then need to place at ESB_HOME/repository/components/dropins then restart server.
  • Since we do use proxy and Callout mediator approach the synapse configuration looks like give below.
  • If you setup everything correctly and when invoke ESB proxy then it will return result as 

<proxy xmlns=""
       transports="https http"

   <target faultSequence="fault">
         <class name="org.wso2.carbon.mediator.ntlm.NTLMMediator">
            <property name="username" value="ayash"/>
            <property name="host" value="xxx"/>
            <property name="domain" value="yyy"/>
            <property name="password" value="mmmm"/>

         <class name="org.wso2.carbon.mediator.ntlm.NTLMCalloutMediator">
            <property name="serviceURL" value="http://xxxxx:8080/Service1.svc"/>
            <property name="initAxis2ClientOptions" value="false"/>
            <property name="action" value=""/>

         <header name="To" action="remove"/>
         <property name="RESPONSE" value="true" scope="default" type="STRING"/>
         <property name="NO_ENTITY_BODY" scope="axis2" action="remove"/>

You could give a try on this. Its a very basic developer test for NTLM and can be enhanced many ways based on requirements.



  1. Could you upload the custom mediator?

  2. Please you could upload mediator? o explain code in detail, thank you, good work!!!

  3. Hey Arturo, I asked a question about NTLM auth on SO. I've answered with a full code walkthrough to build the custom mediator:

  4. Hay, Sorry folks for the late reply, however please do find [1], which has the mediator project and sample NTLM proxy configuration.
    Anyway that configuration is bit different from the sample I have shared through the blog