NTLM support in Oracle HTTPClient

Continuing my coverage of authentication support in Oracle HTTPClient from my previous posting. HTTPClient started supporting NTLM in 10.1.3.x time frame. It is supported but not yet documented. This document is created by Alex Kosowski who took over HTTPClient development from me a few years ago.



How to use NTLM with Oracle HTTPClient

Purpose

This document provides a brief description of NTLM, and describes how to use NTLM authentication with Oracle HTTPClient.

NTLM Overview

NTLM is a proprietary challenge/response authentication protocol used by Microsoft browsers, proxies, and servers. A client using NTLM is able to prove its identity to a server without sending a password.

NTLM is a connection-oriented protocol. Once the connection is authenticated, no further credentials are required as long as the connection remains open.

Proxy servers may also use NTLM for client authentication. However, unlike request-oriented authentication like Basic and Digest, an NTLM client may only authenticate its connection with the proxy, not the resource server.

NTLM support has been built into the Oracle HTTPClient, from OC4J 10.1.3.1 and up.

NT Domain Name

In NTLM, the NT Domain name qualifies the username. The account identifier is \. The NT Domain may be specified in HTTPClient by prefixing the username with the NT Domain name followed by a backslash.

For example, for the NT Domain OPERATIONS and the username jsmith, the fully qualified username is OPERATIONS\jsmith.

If no NT Domain is given, the default (if any) is assumed. The default NT Domain is set in HTTPClient using the System Property HTTPClient.ntlm.defaultDomainName. If the username is given without an NT Domain, and no default NT Domain is defined in HTTPClient, the NTLM-protected server may assume its own default NT Domain.

Realm

A Realm, as specified in authentication schemes such as Basic, does not apply to NTLM. The NTLM challenge does not have a realm directive. Therefore, all NTLM credentials are assumed to be part of the same empty ("") realm within HTTPClient.

How to connect to an NTLM-protected resource server (e.g. IIS)

To connect to an NTLM-protected resource server, add the NTLM credentials to the HTTPClient AuthorizationInfo credential store. As with Basic and Digest authentication, HTTPClient will automatically query the credential store, when challenged by an NTLM server.

Credentials may be added either by using an HTTPConnection instance

HTTPConnection conn = new HTTPConnection( myHost, myPort );
conn.addNtlmAuthentication( myUsername, myPassword );

or directly using AuthorizationInfo.

AuthorizationInfo.addNtlmAuthentication( myHost, myPort, myUsername, myPassword )

A complete example:

HTTPConnection conn = new HTTPConnection( myHost, myPort );
conn.addNtlmAuthentication( myUsername, myPassword );
HTTPResponse response = conn.Get( "/index.htm" );
int status = response.getStatusCode();
assertEquals( 200, status );

How to connect to an NTLM-protected proxy server

To connect to an NTLM-protected proxy server, add the NTLM credentials to the HTTPClient AuthorizationInfo credential store. As with Basic and Digest authentication, HTTPClient will automatically query the credential store, when challenged by an NTLM server.

Credentials may ONLY be added directly using AuthorizationInfo; the HTTPConnection.addNtlmAuthentication(..) method does not add credentials for a proxy.

AuthorizationInfo.addNtlmAuthentication( myProxyHost, myProxyPort, myUsername, myPassword )

A complete example:

HTTPConnection conn = new HTTPConnection( myHost, myPort );
conn.setCurrentProxy( myProxyHost, myProxyPort );
AuthorizationInfo.addNtlmAuthentication( myProxyHost, myProxyPort, myUsername, myPassword, conn.getContext() )
HTTPResponse response = conn.Get( "/index.htm" );
int status = response.getStatusCode();
assertEquals( 200, status );