Develop your own J2C principal mapping module

WebSphere Application Server provides principal mapping when Java 2 Connector (J2C) connection factory is configured to perform container managed sign-on. 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 sign-on, WebSphere Application Server creates a Subject instance that contains EIS security domain credentials. A Subject object returned by a principal mapping module contains a Principal object represents the caller identity and a PasswordCredential or a GenericCredential. WebSphere Application Server 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 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. However, the configuration cannot be done via the administrative console and must be done through the wsadmin scripting tool.

Follow these steps to configure a custom mapping module. Use the WebSphere administrative console to perform the first several steps. Use the wsadmin administrative tool to perform the remaining configuration. For more information about wsadmin, see in the Administration topic.

  1. Start the administrative console. To add a custom mapping module for an application server, click Servers --> Application Servers. Click the name of your server.

  2. Click Security --> JAAS Configuration.

  3. Select JAAS Configuration and Application Login. Click New.

  4. Enter a unique alias for the new mapping module, and click Apply.

  5. Click JAAS Login Modules to define the custom mapping module class.

  6. Click New, and complete mapping LoginModule class name.

  7. Click Apply. Click Save to save the new configuration.

  8. Use wsadmin to configure a J2C Connection Factory to use the new mapping module:

    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/server1:
resources.xml#CMPConnectorFactory_4)

    3. Examine the current mapping module configuration. Run the show command:

      wsadmin>$AdminConfig show {mapping
 (cells/hillsideNetwork/nodes/hillside/servers/server1:
 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/server1:
 resources.xml#MappingModule_7)} {{mappingConfigAlias myMappingModule}}

    You may check the result with the show command:

    wsadmin>$AdminConfig show {mapping
 (cells/hillsideNetwork/nodes/hillside/servers/server1:
 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.

  9. 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 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 Link outside Information Center (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 java.security.Principal object.