J2C principal mapping modules

You can develop your own J2EE Connector (J2C) mapping module if your application requires more sophisticated mapping functions. The mapping login module that you might have developed on WebSphere Application Server V5.x is still supported in WAS Version 6.0.x and later.

Use the V5.x login modules in the connection factory mapping configuration. These login modules can also be used in the reference mapping configuration for the resource manager connection factory. A version 5.x mapping login module is not able to use the custom mapping properties.

If you want to develop a new mapping login module in v6.x and later, use the programming interface that is described in the following sections.

For transitioning users: Migrate your V5.x mapping login module to use the new programming model and the new custom properties as well as the mapping configuration isolation at application scope. Note that mapping login modules that are developed using WebSphere Application Server v6.x cannot be used in the deprecated mapping configuration for the resource connection factory.trns

Invoking the login module for the resource reference mapping

A com.ibm.wsspi.security.auth.callback.WSMappingCallbackHandler class, which implements the javax.security.auth.callback.CallbackHandler interface, is a new WebSphere Application Service Provider Programming Interface (SPI) in WAS v6.x.

Application code uses the com.ibm.wsspi.security.auth.callback.WSMappingCallbackHandlerFactory helper class to retrieve a CallbackHandler object

package  com.ibm.wsspi.security.auth.callback;

public class WSMappingCallbackHandlerFactory {
  private WSMappingCallbackHandlerFactory;
  public static CallbackHandler getMappingCallbackHandler(
ManagedConnectionFactory mcf,
HashMap mappingProperties);

The WSMappingCallbackHandler class implements the CallbackHandler interface

package com.ibm.wsspi.security.auth.callback;

public class WSMappingCallbackHandler implements CallbackHandler {
  public WSMappingCallbackHandler(ManagedConnectionFactory mcf,
HashMap mappingProperties);
  public void handle(Callback[] callbacks) throws IOException,

The WSMappingCallbackHandler handler can manage two new callback types that are defined in v6.x


The new login modules use the two callback types that are used at the reference mapping configuration for the resource manager connection factory. The WSManagedConnectionFactoryCallback callback provides a ManagedConnectionFactory instance that you set in the PasswordCredential credential. With this setting, the ManagedConnectionFactory instance can determine whether a PasswordCredential instance is used for signon to the target Enterprise Information Systems (EIS) instance. The WSMappingPropertiesCallback callback provides a hash map that contains custom mapping properties. The com.ibm.mapping.authDataAlias property name is reserved for setting the authentication data alias.

The WAS WSMappingCallbackHandle handle continues to support the two WAS V5.x callback types that older mapping login modules can use. The two callbacks defined can be used only by login modules that the login configuration uses at the connection factory. For backward compatibility, WebSphere Application Server v6.x and later passes the authentication data alias, if defined in the list of custom properties under the com.ibm.mapping.authDataAlias property name using the WSAuthDataAliasCallback callback to V5.x login modules


Invoking the login module for the connection factory mapping

The WSPrincipalMappingCallbackHandler class handles two callback types


The WSPrincipalMappingCallbackHandler handler and the two callbacks are deprecated in WAS V6.

Passing the mapping properties for the resource reference to the mapping login module

You can pass arbitrary custom properties to your mapping login module. The following example shows how the WAS default mapping login module looks for the authentication data alias property.

    try {
              String userID = null;
              String password = null;
              String alias = null;
              wspm_properties = ((WSMappingPropertiesCallback)callbacks[1]).getProperties();
              if (wspm_properties != null) {
                  alias = (String) wspm_properties.get(com.ibm.wsspi.security.auth.callback.
                  if (alias != null) {
                      alias = alias.trim();
              } catch (UnsupportedCallbackException unsupportedcallbackexception) {
  . . . // error handling

The default mapping login module for WAS Version 6.0.x requires one mapping property to define the authentication data alias. The mapping property, which is called MAPPING_ALIAS, is defined in the Constants.class file in the com.ibm.wsspi.security.auth.callback package.

MAPPING_ALIAS =   "com.ibm.mapping.authDataAlias"

When you click Use default method > Select authentication data entry authentication on the Map resource references to resources panel, the administrative console automatically creates a MAPPING_ALIAS entry with the selected authentication data alias value in the mapping properties. If you create your own custom login configuration and then use the default mapping login module, set this property manually on the mapping properties for the resource factory reference.

In a custom login module, use the WSSubject.getRunAsSubject method to retrieve the subject that represents the identity of the current running thread. The identity of the current running thread is known as the RunAs identity. The RunAs subject typically contains a WSPrincipal principal in the principal set and a WSCredential credential in the public credential set. The subject instance that is created by your mapping module contains a Principal instance in the principals set and a PasswordCredential credential or an org.ietf.jgss.GSSCredential instance in the set of private credentials.

The GenericCredential interface that is defined in Java Cryptography Architecture (JCA) Specification V1.0 is removed in the JCA V1.5 specification. The GenericCredential interface is supported by WebSphere Application Server v6.x to support older resource adapters that might be programmed to the GenericCredential interface.

Related tasks
Configuring programmatic logins for Java Authentication and Authorization Service Manage J2EE Connector Architecture authentication data entries Related reference
Security: Resources for learning




WebSphere is a trademark of the IBM Corporation in the United States, other countries, or both.
IBM is a trademark of the IBM Corporation in the United States, other countries, or both.