Writing a custom NTLM grant handler and a sample client for API Manager with handshake support

NTLM is a challange/response based authentication protocol which is proprietary for Microsoft. If you are new to NTLM and need to have a basic idea what is happening you can read my previous blog post [1].

This blog explains how to write a custom grant handler to WSO2 API Manager to support NTLM grant type.

If you are going to try this please note you should be in a Windows environment. If you are trying this on a single machine (Client and server user accounts on a same computer), you would be able to try this without any issues (I have tried on a Windows 7/8 environments). But if you need to try an actual production environment (clients and server are different computers) , first of all you need to setup a Active Directory Domain. You can follow link [2] to setup that.

In this process we need to deal with Windows Platform related APIs. For that we can use Java Native Access (JNA) [3] library which is a simple way of native access without requiring to write JNI (Java Native Interface) code. There is another library which is built on top of JNA which is Waffle [4] which encapsulates all functionality you need to implement user authentication.

Following Maven dependencies can be used for setting up JNA and Waffle respectively.



First step of the NTLM handshake is to create the Type1 token by the client.

Generated token is then encoded into Base64 and should be send as a header.

Server (APIM) recieves the token from the request header. Then it validates the Type 1 token and generates a Type 2 token. It is sent back to the client. Then client should generate a Type 3 token based on Type 2 token. It is sent to the server as a Header.
Once server receives a token, it first determines the type of it. Type is the value of the 8th byte of the Base64 decoded NTLM token. If the server determines it as a Type 1 token, then it validates it and generates a Type 2 token based on that.
Following function can be used to determine the type of the token.

If the server determines it as a Type 1 token, then it validates it and generates a Type 2 token based on that. If it is Type 3 token, it will validate it and it will then identifies the user details communicating with the domain controller.
To write a custom grant handler we can basically follow the doc [5]. That includes a sample [6] code too. When writing our handler we need to basically extend AbstractAuthorizationGrantHandler when writing our class.
Following is the grant handler code.

The link [7] consists of full code of client and server.

Once you completed writing the handler code, you can do the following configuration to enable the new custom grant type.

There is a section called "SupportedGrantTypes" in identity.xml in /repository/conf folder. (If you are using APIM 1.10.x this can be found at /repository/conf/identity folder). Add your new grant type to that section as a new SupportedGrantType. Correctly put the fully qualified class name of the custom grant handler under . 



After setting this you can start the server. You can use the provided sample client at [7] to test the new NTLM grant handler. You can follow the Readme.txt file which is added there.


[1] NTLM Authentication Basics : http://malinthaprasan.blogspot.com/2015/10/ntlm-authentication-basics.html
[2] Setting up an Active Directory Domain: http://roshanwijesena.blogspot.com/2015/05/ntlm-grant-type-support-with-wso2-api.html
[3] Java Native Access (JNA) Library: https://github.com/java-native-access/jna
[4] Waffle : https://github.com/dblock/waffle
[5] Writing a custom grant type : https://docs.wso2.com/display/IS500/Writing+a+Custom+OAuth+2.0+Grant+Type
[6] Custom grant type sample code : https://svn.wso2.org/repos/wso2/people/asela/oauth/custom-grant/
[7] Sample NTLM grant handler with handshake support and a sample client code: https://drive.google.com/open?id=0B1jOwGWdNiSNMEw3UFJ1R3Z4WFU

NTLM Authentication basics

Introduction

NTLM which is denoted as NT LAN Manager (NTLM) is a suite of Microsoft security protocols (This is a Proprietary Microsoft authentication protocol) that provides authentication, integrity, and confidentiality to users which is used in various Microsoft network protocol implementations.

Basic Structure

This typically involves three systems as follows.

Three systems involved in NTLM authentication

Key Features 

Following are key features of the NTLM authentication scheme.

1. Uses a challenge-response mechanism for authentication, in which clients are able to prove their identities without sending a password to the server. 
2. Provides authentication, confidentiality and integrity
3. Enables Single Sign On.

The Three-Step Handshake

NTLM It consists of three messages, commonly referred to as Type 1 (negotiation), Type 2 (challenge) and Type 3 (authentication).

Following is the message flow that happens between the client and the server.

Three step handshake of NTLM authentication protocol

• (1) Client try to access the server's resource without authorization headers.

• (2) Server responds with 401 Unauthorized. With WWW-Authenticate: NTLM header, server requests the client to send NTLM authentication token.

• (3) Client re-sends the request with NTLM type 1 token. It initiates the NTLM authentication. This contains few information including the hostname and the domain name of the client [1].

NTLM Type 1 token structure

• (4) Server receives the Type 1 token from the client. In response to that, sever sends Type 2 token which consists of server's NTLM challenge. [2]

NTLM Type 2 token structure

• (5) In response to Type 2 token, client sends the Type 3 token as the final step in authentication. This demonstrates that the client has knowledge of the account password without sending the password directly. What actually client does is that it encrypts the server's challenge with its hashed password when generating the Type 3 token. Other than the response to the challenge, it consists the username too [3].

NTLM Type 3 token structure

 Once server receives the type 3 token, it sends the following three items to the domain controller [4].

• User name
• Challenge sent to the client
• Response received from the client

The domain controller uses the user name to retrieve the hash of the user's password from the Security Account Manager database. It uses this password hash to encrypt the challenge. The domain controller compares the encrypted challenge it computed to the response computed by the client. If they are identical, authentication is successful.

Weaknesses

1. Generated hashes of the client's password is not salted. So it remains same until the password is changed. So this is vulnerable to pass the hash [5] attack where once an attacker finds the hash once that can be used to encrypt the server's challenge successfully. 
2. NTLM does not support mutual authentication. i.e only client is authenticated. The client has to assume that the server is legitimate.
3. The password hash in NTLM is exposed each time the client uses NTLM for authenticating to a server. There are tools exists that scan network traffic for NTLM password hashes, capture them and then do a brute-force crack on them to derive the user's password.

Because of this problems Microsoft has recommended Kerberos protocol over NTLM which gives a greater security. It provides mutual authentication. The password hash is less frequently exposed as it is only required to send when the user requests a TGT (Ticket Granting Ticket) [6]. But still there are situations that Kerberos protocol cannot be applied. In such occasions NTLM is still used.

References

[1] NTLM Type 1 message Example : http://davenport.sourceforge.net/ntlm.html#type1MessageExample
[2] NTLM Type 2 message Example :
http://davenport.sourceforge.net/ntlm.html#type2MessageExample
[3] NTLM Type 3 message Example :
http://davenport.sourceforge.net/ntlm.html#type3MessageExample
[4] Microsoft NTLM : https://msdn.microsoft.com/en-us/library/windows/desktop/aa378749(v=vs.85).aspx
[5] Pass the hash : https://en.wikipedia.org/wiki/Pass_the_hash
[6] Authentication in Windows Server 2008 R2 and Windows 7 : http://windowsitpro.com/security/authentication-windows-server-2008-r2-and-windows-7