Develop your own J2C principal mapping module

WAS provides principal mapping when Java 2 Connector (J2C) connection factory is configured to perform container managed sign-on. For example, the appserver can map the caller principal to a resource principal to open a new connection to the backend server. With the container-managed signon, WAS creates a Subject instance that contains Enterprise Information Systems (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. WAS 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 configuration 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 run time, the J2C-managed connection factory code passes a reference of the ManagedConnectionFactory and an authDataAlias object to the configured principal mapping module through the WSPrincipalMappingCallbackHandler object. WebSphere Application Server supports plugging 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 Login Module that performs 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 object to the custom mapping module. However, the configuration must be done through the wsadmin tool. The following steps are needed to perform this task. Use the administrative console for these steps. However, you also can use the wsadmin tool to configure the J2C Connection Factory.

  1. Start the administrative console. To add a custom mapping module for an appserver, click Servers > Application Servers. Click the particular server on the right navigation panel.

  2. Click Security > JAAS Configuration.

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

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

  5. Under Additional Properties, click JAAS Login Modules to define the custom mapping module class.

  6. Click New and enter the Module Classname and the Authentication Strategy.

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

  8. Configure the J2C Connection Factory to use the new mapping module using the wsadmin tool.

    1. Using the administrative console to configure the J2C Connection Factory.

      1. Click Resources > Resource Adapters > resource_adapter.

      2. Under Additional Properties, click CMP Connection Factories.

      3. Click the name of your connection factory.

      4. Enter the resource name, 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.

    2. Using the wsadmin tool to configure the J2C Connection Factory.

      1. At the wsadmin prompt, type the following command to show a list of J2CConnectionFactory objects: wsadmin>$AdminConfig list J2CConnectionFactory.

      2. Select the J2C Connection Factory and enter the following command to show all the attributes. For example, 

        wsadmin>$AdminConfig show PetStore_CF(cells/hillsideNetwork/nodes
/hillside/servers/server:resources.xml#CMPConnectorFactory_4)

        The previous example was split onto two lines because it displayed beyond the width of the page.

      3. Type the following command to examine the current mapping module configuration: 

        wsadmin>$AdminConfig show {mapping (cells/hillsideNetwork/nodes
/hillside/servers/server:resources.xml#MappingModule_7)}

        The previous example was split onto two lines because it displayed beyond the width of the page.

        The following shows sample results of the above command: {authDataAlias {}} {mappingConfigAlias DefaultPrincipalMapping}. As shown in the previous example, the J2C Connection factory is configured to use the DefaultPrincipalMapping login configuration.

      4. Type the following command to modify the mapping module configuration to use the new mapping module: 

        wsadmin>$AdminConfig modify {mapping (cells/hillsideNetwork/nodes
/hillside/servers/server:resources.xml#MappingModule_7)} { 
{mappingConfigAlias myMappingModule}}

        The previous example was split onto three lines because it displayed beyond the width of the page.

        You can check the result by typing: 

        wsadmin>$AdminConfig show {mapping (cells/hillsideNetwork/nodes
/hillside/servers/server:resources.xml#MappingModule_7)} 
{authDataAlias {}} {mappingConfigAlias myMappingModule}

        The previous example was split onto three lines because it displayed beyond the width of the page.

      5. Type save at the wsadmin prompt to save your changes.

      Note that The authDataAlias is left undefined. In practice, the authDataAlias passes at run time to the custom mapping module. But using the authDataAlias to look up user ID and password requires the WebSphere Common Configuration Model (WCCM) programming interface, which is not available at this time.

A mapping module is defined and is configured for the specified J2C Connection factory.

 

Usage Scenario

To develop your own principal and credential mapping LoginModule, refer to the JAAS documentation for general information. The JAAS documents are shipped with WAS are located in $$WAS_HOME/web/docs/jaas/JaasDocs.zip file. Refer to the login.html in the JaasDocs.zip file for details of how to develop JAAS login module.

In particular, a mapping module needs to obtain the security identity of the caller. The WSSubject.getCallerPrincipal() static method returns an com.ibm.websphere.security.auth.WSPrincipal object, which represents the security identity of an authenticated caller.

 

See Also

Configuring Java Authentication and Authorization Service login
Security: Resources for learning