Foundation for Security in Oracle Fusion Middleware:Oracle Platform Security Services

Here is my presentation from Oracle Open World 08 on OPSS

Oracle Platform Security Services

As some of you know I am the product manager for this security framework. Come see the official OPSS page at the OTN & attend the OPSS session at the OOW 08.

Session at Oracle Open World 2008

The theme for this year's Open World is Your.Open.World. I am presenting a session on Oracle Platform Security Services (OPSS). The session in titled "Foundation for Security in Oracle Fusion Middleware: Oracle Platform Security Services" on Wednesday 09/24/2008 at 17:00 - 18:00 in Marriott Golden Gate C3. Please join the session to talk about security foundation for Oracle Fusion Middleware. See you at OOW 08.

JAAS authentication integration with Containers

Often developers write custom jaas login modules. Upon successful authentication the loginContext.getSubject API returns an authenticated subject. LoginModule doesn't automatically make the JavaEE container aware of this subject. So if you need to invoke isUserInRole or IsCallerInRole API and have it evaluate based on the subject created by the loginContext you will need to assert the subject into the container which basically means having the subject associated with the current thread serving the request. Once you do that your programmatic login is integrated with the container. On oc4j the api to do this is Security.setSubject and on WLS the equivalent is Security.RunAs which takes in a subject and a privileged action.

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 );

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.

Security in Oracle Application Client Container

The Application Client container has been part of the JavaEE spec for a while now. The JavaEE specification devotes barely 4 or 5 pages to it. The Application Client container provides access to a subset of JavaEE apis in a remove JVM. A standalone java application that wishes to use JavaEE feature could be run in an application client container.

OC4J provides a standalone application client container as documented on http://download-uk.oracle.com/docs/cd/B32110_01/web.1013/b28958/appclient.htm

While more details are on this above link, I am clarifying here the usage of Callback handler within oc4j's application client container.

The application client container reads a jar that is bundled with application-client.xml. In this deployment descriptor one can specify their Callback handler among various other things. A callback handler typically collect user name password from the user. If you don't provide the callback handler implementation, the Application Client Container looks for jndi.properties file in your application client jar.

OC4J requires username, password and provider url to connect over ormi. These three properties can either be provided in the jndi.properties bundled with your application client, or your callback handler implementation must provide them. If both jndi.properties and the callbackhandler implementation are there the callbackhandler takes priority.

You might need to write your own custom Callbackhandler implementation to launch gui for example. The customer callback handler would implement the javax.security.auth.callback.CallbackHandler interface. You will need to bundled your Callbackhandler and its dependencies in the jar that is passed to Oc4j's Application Client container.

Note that the CallbackHandler implementation has to supply a no args constructor, for oc4j's app client container only looks for a no args call back handler.

Now you don't need to write your own login module. When the oc4j application client container needs to authenticate, it will get the user name and the password from the Callbackhandler. It uses its own LoginModule to send the user name and password over the wire to the server to authenticate the client.

Dear readers, A question for you: Does the limitation to provide an implementation of CallbackHandler with a no args constructor seem overbeering to you? The JavaEE spec is silent about this.