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 FileNet® 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):

- A Content Engine web service
client sends a request that contains a custom set of credentials that
are packaged in a WS-Security header.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.