Develop your own J2C principal mapping module

WebSphere Application Server - Express provides principal mapping when Java 2 Connector (J2C) connection factory is configured to perform container managed signon. For example, the application server can map the caller principal to a resource principal in order to open a new coonection to the backend server. With the container-managed signon, WebSphere Application Server - Express creates a Subject instance that contains EIS security domain credentials. A Subject object that is returned by a principal mapping module contains a Principal object represents the caller identity and a PasswordCredential or a GenericCredential.

WebSphere Application Server - Express provides a default principal mapping module that maps any authenticated user credentials to password credentials for the EIS security domain. The default mapping module is defined in the Application Login Configuration panel in the DefaultPrincipalMapping entry. The user ID and password for the EIS security domain is defined under each connection factory by an authDataAlias attribute container-managed authentication alias in the administrative console. The authDataAlias attribute does not actually contain the user name and password. An authDataAlias attribute contains an alias that refers to a user name and password pair that is defined in the security configuration document. Since it contains sensitive data, the security configurtion document requires the most privileged administrator role for both read and write access. This indirection avoids saving sensitive user name and password in configuration documents other than the security document.

The J2C Connection Factory configuration contains a mapping module which defines a principal mapping module alias (mappingConfigAlias attribute) and an authentication data alias (authDataAlias attribute). At runtime the J2C managed connection factory code passes a reference of the ManagedConnectionFactory and an authDataAlias object to the configured principal mapping module via the WSPrincipalMappingCallbackHandler object. WebSphere Application Server - Express allows users to plug-in a custom principal mapping module for a connection factory if the any-authenticated-to-one mapping provided by the default principal mapping module is insufficient. A custom mapping module is a special purpose JAAS LoginModule that perform principal or credential mapping in the login method. The WSSubject.getCallerPrincipal() method can be used to retrieve the application client identity. Plugging in a custom mapping module is very simple. Change the value of the mappingConfigAlias to the custom mapping module. Configuration can be performed with either the administrative console or the wsadmin scripting tool.

Follow these steps to configure a custom mapping module:

Start the administrative console. To add a custom mapping module for an application server, click Servers --> Application Servers. Click the name of your server.
Click Security --> JAAS Configuration.
Select JAAS Configuration and Application Login. Click New.
Enter a unique alias for the new mapping module, and click Apply.
Click JAAS Login Modules to define the custom mapping module class.
Click New, and complete mapping LoginModule class name.
Click Apply. Click Save to save the new configuration.
Configure a J2C Connection Factory to use the new mapping module. You can use either the administrative console or wsadmin to do this:
- If you use the administrative console, perform the following steps:
  1. Click Resources --> Resource Adapters --> resource_adapter, where resource_adapter is the name of your resource adapter.
  2. Under Additional Properties, click CMP Connection Factories.
  3. Click the name of your connection factory.
  4. Enter the resource name, Java Naming and Directory Interface (JNDI) name, a description of the resource, and a category in which to classify the resource.
  5. Click OK.
  6. Click Save in the upper-left section of the administrative console to save your configuration changes.
- If you use wsadmin, perform the following steps:
  1. At the wsadmin prompt, run the list command to show a list of J2CConnectionFactory objects:
```
wsadmin>$AdminConfig list J2CConnectionFactory
```
  2. To select the J2C Connection Factory, run the show command to show all the attributes. For example:
```
wsadmin>$AdminConfig show PetStore_CF
(cells/hillsideNetwork/nodes/hillside/servers/myserver:
resources.xml#CMPConnectorFactory_4)
```
  3. Examine the current mapping module configuration. Run the show command:
```
wsadmin>$AdminConfig show {mapping
 (cells/hillsideNetwork/nodes/hillside/servers/myserver:
 resources.xml#MappingModule_7)}
```
    The following shows sample results of the command:
```
{authDataAlias {}} {mappingConfigAlias DefaultPrincipalMapping}
```
    As shown in the previous example, the J2C Connection factory is configured to use the DefaultPrincipalMapping login configuration.
  4. Modify the mapping module configuration to use the new mapping module. Run the modify command:
```
wsadmin>$AdminConfig modify {mapping
 (cells/hillsideNetwork/nodes/hillside/servers/myserver:
 resources.xml#MappingModule_7)} {{mappingConfigAlias myMappingModule}}
```
  5. You may check the result with the show command:
```
wsadmin>$AdminConfig show {mapping
 (cells/hillsideNetwork/nodes/hillside/servers/myserver:
 resources.xml#MappingModule_7)} {authDataAlias {}}
 {mappingConfigAlias myMappingModule}
```
    Note: The authDataAlias property is left undefined. In practice, the authDataAlias is passed at runtime to the custom mapping module. Using the authDataAlias property to look up user IDs and passwords requires the WebSphere Common Configuration Model (WCCM) programming interface, which is not available at this time.
  6. Save your changes. Enter the save command:
```
wsadmin>save
```

This task allows you to use your own mapping module to fit your application environment. The WebSphere Application Server - Express default principal mapping module maps all authenticated user credentials to the same user ID and password credentials of the EIS security domain. The user ID and password are stored in the security configuration document and is looked up using the configured alias as a key. Your mapping module may be programmed to perform more sophisticated mapping and store passwords in other persistent storage or from a remote service.

To develop your own principal and credential mapping LoginModule, see JAAS LoginModule Developer's Guide (http://java.sun.com/security/jaas/doc/module.html).

In particular, a mapping module needs to obtain the security identity of the caller. The WSSubject.getCallerPrincipal() static method returns a java.lang.String object that represents the caller's security identity. Note that the return type is different from that of the getCallerPrincipal() method of the EJBContext interface, which is a java.security.Principal object.