WS-EAF

This topic briefly introduces JAAS and provides an overview of WS-EAF.

JAAS

WS-EAF makes heavy use of the JAAS programming model. JAAS is a standard Java™ framework to manage authentication and authorization tasks. JAAS is composed of an application programming interface (API) and a service programming interface (SPI).

Authentication occurs in JAAS LoginModules. In addition to supporting the pluggable authentication model (PAM), LoginModules are also stackable. Stacking LoginModules allows for defining scenarios in which more than one step is required to complete successfully for authentication to succeed. For example, a configuration might require username/password authentication and a separate biometric authentication.

For more information about JAAS architecture and its programming and authentication models, see Resources.

WS-EAF Overview

By using the JAAS authentication model, WS-EAF automatically supports a pluggable and stackable authentication mechanism. WS-EAF is a generic authentication framework and does not expose any Content Cortex specific SPIs for use in extending its functionality. Instead, you typically use the standard JAAS API and an application server-specific SPI available from your application server vendor.

WS-EAF consists of a set of conventions for writing a JAAS LoginModule that is able to interact with the Content Engine web service listener to obtain the credentials that are present in the WS-Security header of an incoming request packet. The following diagram illustrates how this interaction occurs for the first login process (descriptions of the numbered steps follow the diagram):

Interaction diagram for Content Engine web service listener.

  1. A Content Engine web service client sends a request that contains a custom set of credentials that are packaged in a WS-Security header.
  2. The request arrives at the Content Engine web service listener. The web service listener starts the WS-EAF authentication mechanism. A JAAS CallbackHandler (CBH) is created by WS-EAF and seeded with the contents of the WS-Security header.
  3. A JAAS login is performed, specifying the FileNetP8Engine JAAS configuration, and the CallbackHandler created in the previous step.
    Note: The FileNetP8Engine login stanza is the default JAAS configuration entry to WS-EAF. Because this login stanza is just another of the available JAAS key-value pairs of configuration parameters, you can define an alternative login stanza through the administration console by using the JAASConfigurationName key. For the purposes of illustration, this document uses the default name that it references the stanza in text and examples.
  4. The standard JAAS run time looks up the LoginModules that are listed in the JAAS configuration file for the FileNetP8Engine stanza, and calls each of the listed LoginModules, passing in the web service CallbackHandler as a parameter.
  5. The custom WS-EAF JAAS login module instantiates one or more standard JAAS callbacks and passes these callbacks to the handle method of the CallbackHandler For each callback that the client requests, the web service CallbackHandler supplies the callback with requested XML fragments from the incoming WS-Security header, such that they can be retrieved by the custom WS-EAF JAAS LoginModule.
  6. The LoginModule is now in possession of the WS-Security header information, and is able to use this information to perform its proprietary authentication process. If the authentication is successful, then a JAAS Subject is populated and returned.
  7. The web service listener now has a valid JAAS Subject, and can call the Content Engine service to handle the request through the Content Engine EJB.

To improve performance, WS-EAF caches the authenticated Subject upon a successful JAAS login. The cache key is an encoded form of a username/password combination or a binary security token. The cache is configurable through the IBM® Administration Console for Content Platform Engine. If another SOAP request is sent to the web service listener with the same credentials, the WS-EAF retrieves the Subject directly from local cache without performing another JAAS login, if the cache entry is still valid (that is, not timed out or purged).

Extending WS-EAF involves the following tasks:
  • Develop one or more custom LoginModules. These LoginModules must implement the standard javax.security.auth.spi.LoginModule interface.
  • Configure the LoginModules into a WS-EAF JAAS configuration stanza. The stanza name is configurable with the JAASConfigurationName key and its default value is FileNetP8Engine. This step means replacing or stacking the custom LoginModules into the WS-EAF JAAS configuration stanza, for example, FileNetP8Engine. You can do this step either through the application server user interface or by editing the plain text JAAS configuration file.
Inside a custom LoginModule, the following standard JAAS callbacks are supported:
  • javax.security.auth.callback.NameCallback
  • javax.security.auth.callback.PasswordCallback
  • javax.security.auth.callback.TextInputCallback
NameCallback and PasswordCallback are used for Username/Password token authentication mechanisms. Because the Content Platform Engine server supports username/password authentication, developers that create custom solutions must use a TextInputCallback object for handling custom binary security. You can instantiate one or more TextInputCallback objects, passing in different string prompts for each. Depending on the prompt that is passed, WS-EAF sets appropriate values to the instance of TextInputCallback and corresponding credential information can be retrieved by using TextInputCallback.getText inside a custom LoginModule. The supported prompts and the values that are returned by the getText method are listed below with brief descriptions:
  • USERNAME returns username, or null if the WS-Security header contains no user information.
  • PASSWORD returns password, or null if the WS-Security header does not contain a password.
  • BINARYTOKEN returns the binary security token or null.
  • BINARYTOKEN_VALUETYPE returns the binary security token valueType or null.
  • WSIHEADER returns the entire WS-Security header XML element as a string.

If you are using WS-EAF and want to retrieve the WS-Security header XML string from within your custom login module, you must specify the following JVM argument for the Content Platform Engine server: -Dcom.filenet.authentication.wsi.needsWSIHeader (You can also add it as an entry to the FileNet.properties file.) The needsWSIHeader property controls whether the WS-Security header XML string is generated for each WSI request, which has a performance cost. If you do not use WS-EAF, you do not need to specify this JVM property. This property is also not needed if you use WS-EAF but do not want to retrieve the WS-Security header XML string from within your custom LoginModule.

The following example illustrates the usage of TextInputCallback and the prompt parameter. Suppose the user designed a custom binary security token for use with the Content Engine 4.0 web service transport. When the Content Engine web service listener receives the SOAP call, the WS-Security header is similar to the following code sample:
<wsse:Security soap:mustUnderstand="1">
	<wsse:BinarySecurityToken ValueType="binary"
	EncodingType="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-security-1.0#Base64Binary"
	xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
	wsu:Id="SecurityToken-f6da72f4-df43-4765-adb7-86eb583e7419">
		RGFwaG5lVGVzdHxmaWxlbmV0MTIz
	</wsse:BinarySecurityToken>
</wsse:Security>
Notice the BinarySecurityToken block, which represents the custom binary security token. After WS-EAF initiates the JAAS authentication process, the custom authentication credential can be retrieved by a custom LoginModule with the following code snippet:
javax.security.auth.callback.Callback[] callbacks = new Callback[2];
callbacks[0] = new TextInputCallback("BINARYTOKEN");
callbacks[1] = new TextInputCallback("BINARYTOKEN_VALUETYPE");
callbackhandler.handle(callbacks);

//Retrieve the binary security token.
String binaryToken = ((TextInputCallback)callback[0]).getText();
//Retrieve the binary security token value type.
String valueType = ((TextInputCallback)callback[1]).getText();

If the TextInputCallback is constructed with the WSIHEADER prompt, the getText method returns the entire WS-Security header as an XML string. The custom LoginModule can parse this XML string to locate the credential.

By using TextInputCallback, WS-EAF provides sufficient knowledge for a custom LoginModule to authenticate the SOAP request.

Developing custom LoginModules for different application servers can be complicated. The Using WS-EAF topic describes some of the issues that are related to using WS-EAF in different Java EE application server environments that are supported by the Content Platform Engine.