Authentication with Oracle HTTPClient

Oracle's HTTPClient supports Basic, Digest and NTML (since 10.1.3.1) schemes. I could not find good documentation on these. Here is my attempt to fill this gap. These code examples are taken from unit tests I wrote some years back.

Basic Authentication

I won't go in details on HTTP Basic auth. But here is an example of code that shows how the reader can configure HTTPClient to send HTTP Basic authentication info.



URL url = new URL("http://localhost:1234");
HTTPConnection client = new HTTPConnection(url);

try {
client.addBasicAuthorization("realm name", "user", "password");
HTTPResponse response = client.Get(url.getFile());
//assertEquals(200, response.getStatusCode());

} finally {
client.stop();
}


Digest Authentication

HTTPConnection client = new HTTPConnection(url);
try {
client.addDigestAuthorization("ProxyAuthDigestSchemeTestServlet",validUserName,validPassword);
HTTPResponse response = client.Get(url.getFile());
// assertEquals(200, response.getStatusCode());

} finally {
client.stop();
}



Starting 10.1.3.1 HTTPClient supported NTML as well. I'll cover NTLM support in HTTPClient in my next post.

Setting authentication method on the HTTPConnection object is just one way to set the credential. The two other ways are providing authentication info via an AuthorizationPrompter implementation or Providing it in the AuthorizationInfo object. See OracleHTTPClient javadoc for details.

Debugging HTTPClient

Oracle HTTPClient extensively logs activity during setup and communication. This page provides some tips for enabling logging in HTTPClient.


HTTPClient versions 10.1.2 & earlier

HTTPClient versions 10.1.2. and earlier used a proprietary logging mechanism.

To enable all logging, set the "HTTPClient.log.mask" system property to "-1"

HTTPClient versions 10.1.3 & later

HTTPClient versions 10.1.3 and later uses the standard JDK java.util.logging package.


By default, HTTPClient is enabled by the JDK java.util.logging properties specified at JVM startup. This is describe in the JavaDoc for java.util.logging.LogManager. Usually the JDK logging properties are configured in "/lib/logging.properties".

Additionally, HTTPClient logging may be enabled using System Properties. Set the "HTTPClient.log.level" System Property to one of the valid java.util.logging.Level values. See Log Levels, below.

Log Levels

HTTPClient only uses the trace portion of the JDK logging levels. This is because HTTPClient is a utility library, and is unaware of the application context within which an error occurs.

For example, consider the occurrence of a connection loss. A financial application may log a connection loss as SEVERE. A server-monitoring application may log a connection loss as INFO. Since the severity depends on the application context, HTTPClient internally only logs messages at trace levels (CONFIG and lower), and expects the application to log exceptions as appropriate for the application.

The following list indicates the HTTPClient usage of java.util.logging.Level:

* SEVERE - Not used by HTTPClient (v11 & up), reserved for application
* WARNING - Not used by HTTPClient (v11 & up), reserved for application
* INFO - Not used by HTTPClient (v11 & up), reserved for application
* CONFIG - System properties and other configuration data
* FINE - Exceptions and other error conditions
* FINER - Warnings
* FINEST - Informational logging

* ALL - Everything logged in HTTPClient is visible at this level



If the version of HTTPClient is 11 and later, verbose logging may be enabled. To enable verbose mode, set the Java System Property "HTTPClient.log.verbose=true".

Verbose logging adds the following fields to the logging output:

* Log Entry Date
* Logger Name - Usually the class name where the log entry occurred
* Log Level - Per java.util.logging.Level
* Exception Stack Trace

In iAS Installation

HTTPClient logging in iAS is effectively the same as standalone, except for the way Java System Properties are set. HTTPClient logging is directed to system out, which is written to one of the iAS logs.
Enabling

To set the HTTPClient logging System Properties, following these steps:

1. Open the file $ORACLE_HOME/opmn/conf/opmn.xml
2. Search for the OC4J process whose id matches that of the OC4J instance where you want to enable HTTPClient logging

For example:










3. Set the HTTPClient logging System Properties in the value attribute of the element "java-options", under the element "start-parameters"
4. Start the OC4J instance
5. Review the HTTPClient log where the iAS installation writes the System Out. This log may be "$ORACLE_HOME/opmn/logs/OC4J~<>~default_island~1"

Thanks to Alex Kosowski for providing latest version of this information.