Develop your own J2C principal mapping module

 

Before you begin

We can develop your own J2EE Connector (J2C) mapping module if your application requires more sophisticated mapping functions. The mapping LoginModule that you might have developed on WebSphere Application Server V5.x is still supported in WAS v6.x. The V5.x LoginModules can be used in the connection factory mapping configuration (that is, they can be defined on the resource). They also can also be used in the resource manager connection factory reference mapping configuration. A V5.x mapping LoginModule is not able to take advantage of the custom mapping properties.

If you want to develop a new mapping LoginModule in V6, use the programming interface described in the following sections.

Migrate your V5.x mapping LoginModule to use the new programming model to take advantage of the new custom properties as well as the mapping configuration isolation at application scope. Note that mapping LoginModules developed using the WAS Release 6 cannot be used at the deprecated resource connection factory mapping configuration.

 

Overview

Resource Reference Mapping LoginModule invocation

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

WSMappingCallbackHandler can handle two new callback types defined in Release 6

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

The two Callback types should be used by new LoginModules that are used at the resource manager connection factory reference mapping configuration. The WSManagedConnectionFactoryCallback provides a ManagedConnectionFactory instance that should be set in the PasswordCredential. It allows a ManagedConnectionFactory instance to determine whether a PasswordCredential instance is used for sign-on to the target EIS instance. The WSMappingPropertiesCallback provides a HashMap that contains custom mapping properties. The property name "com.ibm.mapping.authDataAlias" is reserved for setting the authentication data alias.

The WAS Release 6.0.x WSMappingCallbackHandle continues to support the two WebSphere Application Server V5.x Callback types that can be used by older mapping LoginModules. The two Callbacks defined below can only be used by LoginModules that are used by login configuration at the connection factory. For backward compatibility, WebSphere Application Server Release 6.0.x passes the authentication data alias, if defined in the list of custom properties under the “com.ibm.mapping.authDataAlias” property name using the WSAuthDataAliasCallback to V5.x LoginModules

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

Connection Factory Mapping LoginModule Invocation

The WSPrincipalMappingCallbackHandler class handles two Callback types: WSManagedConnectionFactoryCallback and WSMappingPropertiesCallback

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

The WSPrincipalMappingCallbackHandler and the two Callbacks are deprecated in WAS Release 6 and should not be used by new development work.

Mapping LoginModule Resource Reference Mapping Properties

We can pass arbitrary custom properties to your mapping LoginModule. The following example shows how the WebSphere Application Server default mapping LoginModule 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 WAS V6 default mapping LoginModule requires one mapping property to define the authentication data alias. The property name, MAPPING_ALIAS, is defined in the Constants.class in the com.ibm.wsspi.security.auth.callback package.

MAPPING_ALIAS = "com.ibm.mapping.authDataAlias"

When you specify the Use default method > Select authentication data entry authentication method 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 choose to create your own custom login configuration and then use the default mapping LoginModule, you’ll have to 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 in the principal set and a WSCredential 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 or an org.ietf.jgss.GSSCredential instance in the set of private credentials.

The GenericCredential interface that was defined in Java Cryptography Architecture (JCA) Spec V1.0 has been removed in the JCA V1.5 spec. The GenericCredentail interface is supported by WAS v6.x to support older resource adapters that might have been programmed to the GenericCredential interface.

---

 

Related Tasks

Configuring application logins for Java Authentication and Authorization Service

 

See Also

Security: Resources for learning

 

---