J2C principal mapping modules

If an application requires more sophisticated mapping functions we can develop our own J2EE Connector (J2C) mapping module

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, UnsupportedCallbackException; 
}

The WSMappingCallbackHandler handler can manage two new callback types defined in Version 6.0.x:

com.ibm.wsspi.security.auth.callback.WSManagedConnectionFactoryCallback 
com.ibm.wsspi.security.auth.callback.WSMappingPropertiesCallback

The new login modules use the two callback types used at the reference mapping configuration for the resource manager connection factory. The WSManagedConnectionFactoryCallback callback provides a ManagedConnectionFactory instance 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 containing custom mapping properties. The com.ibm.mapping.authDataAlias property can be used to reserve or to retrieve the Authentication Data Alias.

In the previous examples, the value of the MCF is set onto the PasswordCredential.

The WebSphere Application Server WSMappingCallbackHandle handle continues to support the two WebSphere Application Server Version 5.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, WAS v6.0.x and later passes the authentication data alias, if defined in the list of custom properties under the com.ibm.mapping.authDataAlias

com.ibm.ws.security.auth.j2c.WSManagedConnectionFactoryCallback 
com.ibm.ws.security.auth.j2c.WSAuthDataAliasCallback

Invoking the login module for the connection factory mapping

The WSPrincipalMappingCallbackHandler class handles two callback types:

com.ibm.wsspi.security.auth.callback.WSManagedConnectionFactoryCallback 
com.ibm.wsspi.security.auth.callback.WSMappingPropertiesCallback

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

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

  
try {
    wspm_callbackHandler.handle(callbacks);
        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.
            Constants.MAPPING_ALIAS);
            if (alias != null) {
                alias = alias.trim();
            }
        }
} catch (UnsupportedCallbackException unsupportedcallbackexception) {
 . . . // error handling

The default mapping login module for WAS v6.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 console automatically creates a MAPPING_ALIAS entry with the selected authentication data alias value in the mapping properties. If we create our own custom login configuration and use the default mapping login module, set this property manually on the mapping properties for the resource factory reference.

In a custom login module, we can 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 created by the 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 defined in Java Connector Architecture (JCA) Specification Version 1.0 is deprecated in the JCA Version 1.5 specification.

Related tasks

Manage Java 2 Connector Architecture authentication data entries for JAAS

Configure programmatic logins for Java Authentication and Authorization Service

Security: Resources for learning