Integrated Windows Authentication, NTLM, and Java HTTP Clients

2 May 2006
revised 13 May 2007

Oakland Software


The information in this paper is believed to be accurate as of the above date. If you know of any corrections or omissions, I will gratefully fix them. Please email me at the above address. Though I work for Oakland Software, which sells one of the represented products, the intention of this paper is to be completely fair in the comparison so the reader can make the best choice.


This paper will help you determine the best way to deal with the authentication issues when accessing Internet Information Services (IIS) from Java using the HTTP protocol.

The HTTP protocol provides a flexible means of authenticating a request according to a separately specified authentication protocol. The most commonly used authentication protocol is Basic Authentication where a simple check of a user name and password is done to determine if access is allowed. Digest Authentication is another popular authentication method, providing some additional security.

One of the standard ways to configure IIS is to enable Integrated Windows Authentication, as shown below.

The advantage of doing this is that HTTP clients can be authenticated using the user and password information already set up in the windows environment.

When you enable Integrated Windows Authentication, you require the HTTP client to complete an authentication exchange using the NTLM protocol (this is an alternative to Basic and Digest authentication mentioned above). The NTLM protocol is a proprietary Microsoft protocol used to identify and authenticate clients connecting to servers. This protocol is used on top of different protocol stacks for different purposes (for example, it is used with the SMB protocol for file access). One of the uses is as an authentication mechanism for HTTP.

The next section goes into more detail about the ways you can configure your Windows environment to use the NTLM protocol, and options for Java-based solutions for HTTP access using NTLM.

Configuring NTLM

As a practical matter, when used in conjunction with HTTP, NTLM is a broad term covering a set of authentication protocols used with Windows. Java HTTP client implementations that provide NTLM support include the support for the earlier LAN Manager (LM) protocol, and may include support for the NTLM V2 protocol.

The use of NTLM is configured at the level of the machine, rather than for a specific protocol. Thus changing the authentication requirements will affect not only the HTTP protocol, but all means of connecting to the machine from other computers for any purpose that uses NTLM (like remote file access). Thus you may not be able to change the configuration of the NTLM protocol just for HTTP since it affects other services.

You can specify different levels of the NTLM protocol to be required on the Windows server machine as the dialog below illustrates. We can call these levels 0-5, which is their value as set in the system registry.

The dialog above was for Network Access: LAN Manager Authentication Level property. This can be accessed on a Windows XP or Windows Server 2003 machine by going to Control Panel -> Administrative Tools -> Local Security Policy -> Local Policies -> Security Options -> Network Access: LAN Manager Authentication Level. The method for setting the level to use may be different on your machine, but the allowed levels are the same. Microsoft knowledge base article 239859 contains instructions for setting the level directly in the registry, which is required on some servers.

Microsoft knowledge base article 823659 provides some good information about setting the LAN Manager Authentication level (search for that term in the article).

An additional setting may sometimes be set which requires NTLM V2 authentication. This property is found in the same place as the above, and is called: Network security: Minimum session security for NTLM SSP based (including secure RPC) servers (the corresponding property with for the clients seems to have no bearing on HTTP NTLM support, which is understandable because the NTLM request under HTTP is handled by a server).

As mentioned in the above KB article, the default configuration for Windows Server 2003 is to require the use of NTLM V2 only.

If you are getting a HTTP 500 Response code, accompanied by the message: "-2146893054 (0x80090302)" (which may manifest in a browser as "The function requested is not supported" if 'friendly errors' is turned on at the browser). this means that IIS is expecting an NTLM V2 authentication and not getting it. Normally when NTLM authentication fails, you will get a 401 response, however this case appears to be handled differently by IIS. If you are getting this response with a Java HTTP implementation, make sure the implementation correctly supports NTLM V2.

Java HTTP Client Options

This section talks about the known implementations of NTLM support with a Java HTTP client so that you can select the implementation that best serves your needs.

The available implementations are:

If your Java implementation is 1.4.2 or greater and you are running Java on Windows, use the built in JRE support and you are done. Use the class optionally in conjunction with setting some networking properties

If you can change the Windows machine to an NTLM configuration level less that 4 (to not require NTLM V2), and make sure the Network security: Minimum session security for NTLM SSP based (including secure RPC) servers is not set to require NTLM V2, then use either the Jakarta HTTP Client (if you don't care about plug compatibility) or the JCIFS HTTP client if you do. Also, if you are accessing your HTTP server through a proxy that supports only OEM encoding for NTLM, then you cannot use the Jakarta HTTP client (is this also true of JCIFS?).

Note however, there is a potential compatibility related downside to the JCIFS HTTP client. If there is any HTTP access in the process prior to setting the property to configure the JCIFS HTTP client, you will not be able to use that client, as the HTTP implementation is bound on the first access and cannot be unbound. If you have this situation, and desire (mostly) plug compatibility, use the Oakland Software implementation because that provides an option to bypass the binding restriction (by providing a separate API to create the HttpURLConnection).

If you must use NTLM V2 (you cannot change the Windows server) and are not running Java on Windows, the Oakland Software implementation is the only choice available now. Or if you are not running Java on Windows and must support an NTLM proxy that uses OEM encoding (unless JCIFS supports OEM encoding).

Please note there are many other considerations in choosing an HTTP client, and Oakland Software provides a more complete comparison of the available clients.