13
J2EE Connector Architecture

This chapter describes how to use the J2EE Connector Architecture (J2EE Connector) in an Oracle9iAS Containers for J2EE (OC4J) application. This chapter covers the following topics:

• Introduction

• Resource Adapters

• Deploying Resource Adapters

• Specifying Container-Managed or Component-Managed Sign-On

• Authentication in Container-Managed Sign-On

Introduction

The J2EE Connector Architecture defines a standard architecture for connecting the J2EE platform to heterogeneous Enterprise Information Systems (EIS). Typical EIS include ERP, database systems, mainframe transaction processing, and legacy applications not written in the Java programming language.

Figure 13-1 Java Connector Architecture

Text description of the illustration jcaarch.gif

Resource Adapters

A resource adapter is a driver that an application server or an application client uses to connect to a specific EIS. Examples of resource adapters are JDBC or SQLJ drivers to connect to a relational database, an ERP resource adapter to connect to an ERP system, and a TP resource adapter to connect to a TP monitor. J2EE 1.3 requires application servers to support both standalone and embedded resource adapters.

• Standalone resource adapters are available to all applications deployed in the application server instance. These adapters are stored in standalone Resource Adapter Archive (RAR) files. Here is an example:

  /META-INF/ra.xml 
  /META-INF/oc4j-ra.xml 
  /howto.html 
  /images/icon.jpg 
  /ra.jar 
  /cci.jar 
  /win.dll 
  /solaris.so 
  

  Note: The JAR files referred to in the RAR file can be located in any directory within the archive.

• Embedded resource adapters are available only to the J2EE application(s) with which they are bundled in an enterprise application archive (EAR) file.

Classes that are defined within a resource adapter are available to all application components, including EJBs, that reference the resource adapter. Classes defined by standalone resource adapters are available to all applications deployed within OC4J; classes defined by embedded resource adapters are available only to applications within their own EAR file.

Application Contracts

The client API furnished by a resource adapter can be either the standard Common Client Interface (CCI), or a client API specific to the type of a resource adapter and its underlying EIS. For example, the JDBC API is the client API specific to relational database accesses. The EIS side of the contract is implemented by the resource adapter, transparently to the application components.

Quality of Service Contracts

Java Connector Architecture also defines three Quality of Service (QoS) contracts between an application server and an EIS.

• Connection Pooling enables an application server to pool connections to an underlying EIS, and enables application components to connect to an EIS.

  Note: The J2EE Connector connection-pooling interface differs from the JDBC interface; J2EE Connector connection pools are not shared with JDBC connection pools, nor do properties set for one connection pool affect the other.

• Transaction Management enables an application server to use a transaction manager (JTA XAResource) to manage transactions across multiple resource managers.

• Security management provides authentication, authorization, and secure communication between the J2EE server and the EIS.

All resource adapters must support their side of the QoS contracts to be pluggable into application servers.

Support for Optional Features

OC4J does not support the optional connection sharing (section 6.9 in the J2EE Connector Architecture 1.0 specification) and local transaction optimization (section 6.12) features.

Deploying Resource Adapters

This section discusses deployment descriptors, deploying standalone resource adapters, and deploying embedded resource adapters.

OC4J supports three deployment descriptors: ra.xml, oc4j-ra.xml, and oc4j-connectors.xml. The ra.xml descriptor is normally supplied with the resource adapter. Whenever you deploy a resource adapter within an EAR file, OC4J generates oc4j-connectors.xml and oc4j-ra.xml; you should manually edit the second file.

The ra.xml Descriptor

The ra.xml descriptor is the standard J2EE deployment descriptor for resource adapters. For details, see the J2EE Connector Architecture 1.0 specification.

The oc4j-ra.xml Descriptor

The oc4j-ra.xml descriptor provides OC4J-specific deployment information (JNDI pathname and connector properties) for resource adapters. For each resource adapter, oc4j-ra.xml contains one or more <connector-factory> elements specifying a JNDI name corresponding to a set of configuration parameter values. OC4J binds each connection into the proper JNDI namespace location as a ConnectionFactory instance.

A <connector-factory> element can contain any combination of the following elements (all are optional):

• <description>--Text description of the connector. This element is not interpreted by OC4J.

• <config-property>--Value for a property defined in ra.xml. All ra.xml files define the properties ServerName, PortNumber, UserName, Password, and ConnectionURL, although an adapter does not need to support them. Values defined in oc4j-ra.xml override any values defined in ra.xml.

• <connection-pooling>-- Parameters describing how J2EE Connector pooled connections are to be handled. This element is discussed in "The <connection-pooling> Element" .

• <security-config>--Parameters describing how to supply usernames and passwords to the EIS. This element is discussed in "The <security-config> Element" .

• <log>-- Pathname of a log file for a connection property set. The syntax is:

  <log>
    <file path="pathname" />
  </log>
  

The <connection-pooling> Element

Connection pooling is a J2EE 1.3 feature that allows a set of connections to be reused within an application. Because the J2EE Connector specification is intended to be general rather than database-specific, the J2EE Connector connection-pooling interface differs significantly from the JDBC interface.

To set a connection pooling property, specify a <property> element within the <connection-pooling> element. The syntax is:

<property name="propname" value="propvalue" />.

The propname must be one of:

• maxConnections--Maximum number of connections permitted within pool. Defaults to infinity.

• minConnections--Minimum number of connections. Defaults to 0. If minConnections is greater than 0, the specified number of connections will be opened when OC4J is initialized. OC4J may not be able to open the connections if necessary information is unavailable at initialization time. For instance, if the connection requires a JNDI lookup, it cannot be created, because JNDI information is not available until initialization is complete.

• scheme--Specifies how OC4J handles connection requests after maximum permitted number of connections is reached. You must specify one of the following values:
  • dynamic--OC4J always creates a new connection and returns it to the application, even if this violates the maximum limit. When these limit-violating connections are closed, they are destroyed instead of being returned to the connection pool.

  • fixed--OC4J raises an exception when the application requests a connection and the maximum limit has been reached.

  • fixed_wait--OC4J blocks the application's connection request until an in-use connection is returned to the pool. If waitTimeout is specified, OC4J throws an exception if no connection becomes available within the specified time limit.

• waitTimeout--Maximum number of seconds OC4J will wait for an available connection if maxConnections has been exceeded and the fixed_wait scheme is in effect. Defaults to infinity.

The <security-config> Element

The <security-config> element specifies the user name and password for container-managed sign-ons.

There are two ways of supplying this information in the <security-config> element of the oc4j-ra.xml file:

• Specifying mapping subelements explicitly (<principal-mapping-entries> subelement)

• Specifying the name of a user-created mapping class that either implements oracle.j2ee.connector.PrincipalMapping or inherits from oracle.j2ee.AbstractPrincipalMapping (<principal-mapping-interface> subelement)

Authentication issues are discussed in detail in "Authentication in Container-Managed Sign-On". This section discusses only the syntax for the <security-config> element.

A <security-config> element contains either a <principal-mapping-entries> element, specifying user names and passwords explicitly; a <principal-mapping-interface> element, specifying the name of the mapping class; or a <jaas-module> element, specifying the JAAS module to be used for authentication.

<security-config>
  <principal-mapping-entries>                       // 1
     <default-mapping>                              // 2
        <res-user>username</res-user>            // 3 
        <res-password>password</res-password>    // 4
     </default-mapping> 
     <principal-mapping-entry>                      // 5
        <initiating-user>iuname</initiating-user> // 6
        <res-user>username</res-user>
        <res-password>password</res-password>
     </principal-mapping-entry>
  </principal-mapping-entries>
  
  <principal-mapping-interface>                    // 7
    <impl-class>classname</impl-class>          // 8
    <property name="propname" 
              value="propvalue" />              // 9
  </principal-mapping-interface>

  <jaas-module>                                    // 10
      <jaas-application-name>                      // 11
         appname
      </jaas-application-name>
  </jaas-module>
</security-config>

1. <principal-mapping-entries>-- Provides a declarative specification for resource mapping. This element begins with an optional <default-mapping> element; it continues with one or more <principal-mapping-entry> elements.

2. <default-mapping>-- Specifies the user name and password for the default resource principal.

3. <res-user>-- Specifies user name.

4. <res-password>-- Specifies password.

5. <principal-mapping-entry>-- Specifies a mapping from a single initiating principal to a resource principal and password.

6. <initiating-user>-- Specifies the initiating principal.

7. <principal-mapping-interface>-- Specifies information necessary to employ user-created classes to provide mappings.

8. <impl-class>-- Specifies the name of the user-provided PrincipalMapping implementation.

9. <property name="name" value="value"> (optional; can be repeated)-- Specifies information specific to your PrincipalMapping implementation: for instance, the path of the principal mapping file, or LDAP server connection information.

10. <jaas-module>-- Specifies the JAAS module used for authentication. Has only one element, <jaas-application-name>.

11. <jaas-application-name>-- Specifies the name of the JAAS module used for authentication.

The oc4j-ra.xml DTD

The XML DTD for the resource adapter descriptor is:

<!ENTITY % JNDIPATH "CDATA">
<!-- Define a property set for a Connector Architecture 
   compliant resource adapter. -->
<!ELEMENT config-property (#PCDATA)>
<!ATTLIST config-property name CDATA 
   #REQUIREDvalue CDATA #REQUIRED>
<!-- Define a property set for a Connector Architecture c
     ompliant resource adapter. -->
<!ELEMENT connector-factory (description?, config-property*, 
connection-pooling?, security-config?, log?)>
<!ATTLIST connector-factory connector-name CDATA #REQUIRED
  location %JNDIPATH; #REQUIRED>
<!ELEMENT connection-pooling (property*)>
<!ELEMENT default-mapping (res-user, res-password)>
<!-- A short description. -->
<!ELEMENT description (#PCDATA)>
<!-- A relative/absolute path to log events to. -->
<!ELEMENT file (#PCDATA)>
<!ATTLIST file path CDATA #IMPLIED>
<!-- name of the class which implements the
  oracle.j2ee.connector.PrincipalMapping interface -->
<!ELEMENT impl-class (#PCDATA)>
<!-- logged in user name of J2EE application -->
<!ELEMENT initiating-user (#PCDATA)>
<!ELEMENT jaas-application-name (#PCDATA)>
<!ELEMENT jaas-module (jaas-application-name)>
<!-- Logging settings. -->
<!ELEMENT log (file)>
<!-- This file contains the definition of property sets 
  configuration for an installed Connector Architecture 
  compliant resource adapters. -->
<!ELEMENT oc4j-connector-factories (connector-factory*)>
<!ELEMENT principal-mapping-entries (description?, 
   default-mapping?, principal-mapping-entry*)>
<!ELEMENT principal-mapping-entry 
  (initiating-user, res-user, res-password)>
<!ELEMENT principal-mapping-interface (impl-class, property*)>
<!-- Contains a name/value pair initialization param. -->
<!ELEMENT property (#PCDATA)><!ATTLIST property name 
  CDATA  #IMPLIEDvalue CDATA #IMPLIED>
<!-- password of the EIS resource -->
<!ELEMENT res-password (#PCDATA)>
<!-- user name of the EIS resource -->
<!ELEMENT res-user (#PCDATA)>
<!-- principal mapping configurations -->
<!ELEMENT security-config (
  principal-mapping-entries | principal-mapping-interface
  | jaas-module )>

The oc4j-connectors.xml Descriptor

The oc4j-connectors.xml descriptor configures the resource adapters deployed by oc4j-ra.xml. The oc4j-connectors.xml descriptor lists the standalone resource adapters deployed in this OC4J instance, as well as the resource adapters embedded within an application.

Note: The name and pathname of the connectors descriptor are defined by the <connectors> element under the <orion-application> element in the file orion-application.xml. If no <connectors> element is specified in orion-application.xml, then the default path is $OC4J_HOME/connectors/rarname./oc4j-connectors.xml.

The root element is <oc4j-connectors>. Each individual connector is represented by a <connector> element that specifies the name and pathname for the connector. Each <connector> element contains the following elements:

• <description> Optional--Text description of the connector. Not interpreted by OC4J.

• <native-library path="pathname"> Optional--Directory containing native libraries. If you do not specify this element, OC4J expects the libraries to be located in the directory containing the decompressed RAR. OC4J interprets the pathname attribute relative to the decompressed RAR directory.

• <security-permission enabled="booleanvalue">--Permissions to be granted to each resource adapter. Each <security-permission> contains a <security-permission-spec> that conforms to the Java 2 Security policy file syntax.

  OC4J automatically generates a <security-permission> element in oc4j-connectors.xml for each <security-permission> element in ra.xml. Each generated element has the enabled attribute set to false. Setting the enabled attribute to true grants the named permission.

Example:

<oc4j-connectors> 
  <connector name="myEIS" path="eis.rar"> 
    <native-library> path="mylibrary"</native-library> 
    <security-permission>
      <security-permission-spec enabled="false">
        grant {permission java.lang.RuntimePermission "LoadLibrary", *'};
      </security-permission-spec>
    </security-permission>
  </connector> 
</oc4j-connectors> 

The oc4j-connectors.xml DTD

The XML DTD for the connectors descriptor is:

<!-- An installed Connector Architecture compliant resource adapter. -->
<!ELEMENT connector 
   (description?, native-library?, security-permission*)>
<!ATTLIST connector name CDATA #REQUIRED path CDATA #REQUIRED>
<!-- A short description. -->
<!ELEMENT description (#PCDATA)>
<!-- Relative path of native libraries in the resource adatper. -->
<!ELEMENT native-library (#PCDATA)>
<!ATTLIST native-library path CDATA #IMPLIED>
<!-- This file contains the configuration for the installed 
      Connector Architecture compliant resource adapters 
      of an application-server. -->
<!ELEMENT oc4j-connectors (connector*)>
<!-- Java security permissions for 
     resource adapter jar files. -->
<!ELEMENT security-permission (security-permission-spec)>
<!ATTLIST security-permission enabled (true|false) "false">
<!--The element permission-spec specifies a security permission 
basedon the Security policy file syntax 
[reference: Java 2, Security  architecture specification] 
http://java.sun.com/products/jdk/1.3/docs/guide/security/PolicyFiles.html#FileSy
ntax-->
<!ELEMENT security-permission-spec (#PCDATA)>

Deploying Standalone Resource Adapter Archives

You can deploy standalone resource adapter archives in OC4J. During deployment, give each standalone resource adapter a unique name for future operations, such as undeployment of the resource adapter. You deploy standalone resource adapters in one of the following ways:

• Deploying Using admin.jar

• Deploying Manually

Deploying Using admin.jar

To deploy standalone resource adapters you use the -deployconnector switch of the command-line tool admin.jar. The syntax is:

-deployconnector -file mypath.rar -name myname -nativeLibPath 
libpathname -grantAllPermissions

The -deployconnector switch is supported by additional command-line switches:

• -file mypath (required) -- pathname of the resource adapter's RAR file

• -name myname (required)-- resource adapter's name

• -nativelibpath libpathname -- pathname for native libraries within the RAR file (see also the <native-library> element in "The oc4j-connectors.xml Descriptor".)

• -grantallpermissions--grants all runtime permissions requested within the RAR (see also the <security-permission> element in "The oc4j-connectors.xml Descriptor")

The admin.jar tool decompresses the RAR file into $OC4J_HOME/connectordirectory/myname, creating the directory if it does not exist.

The default connectordirectory is $OC4J_HOME/connectors. To specify a different connector directory, edit the server.xml file, setting the connector-directory attribute of the <application-server> element to the correct pathname.

<application-server connector-directory="my_connectors">

The admin.jar tool then creates (or updates) oc4j-connectors.xml and oc4j-ra.xml in my_connectors. See "The oc4j-ra.xml Descriptor" and "The oc4j-connectors.xml Descriptor" for a discussion of these files. If the deployment descriptor specifies transaction level and authentication mechanisms that are not supported by OC4J, the admin.jar tool prints an error message.

Example:

java -jar admin.jar ... -deployconnector -name accounts -file ./accounts.rar 

Deploying Manually

If you prefer to deploy your connector manually, you must:

1. Create a connectorname directory under $OC4J_HOME/connectordirectory,.

2. Copy the connector's RAR file into $OC4J_HOME/connectordirectory,/connectorname.

3. Create an oc4j-connectors.xml file in connectordirectory for the new resource adapter, or add a <connector> element to the file if it already exists.

4. Restart OC4J. OC4J generates a new oc4j-ra.xml in $OC4J_HOME/application-deployments/default/connectorname for the adapter. You must modify the generated file to contain a <connector_factory> element appropriate for your connector.

   Note: See "The oc4j-ra.xml Descriptor" and "The oc4j-connectors.xml Descriptor" for details on oc4j-connectors.xml and oc4j-ra.xml.

Removing Resource Adapters

To remove a deployed resource adapter, use the -undeployconnector switch of admin.jar. The syntax is:

-deployconnector -name myname

The required -name argument specifies which adapter is being removed. This command removes all <connector> entries that use the specified resource adapter from oc4j-connectors.xml and deletes the $OC4J_HOME/connector_directory/myname directory.

If you prefer, you can remove an adapter manually by deleting all <connector> entries that refer to the adapter from oc4j-connectors.xml and deleting the $OC4J_HOME/connector_directory/myname directory.

Deploying Embedded Resource Adapters

Each application deployed in an OC4J instance that contains resource adapter(s) has a corresponding oc4j-connectors.xml file under $OC4J_HOME/application-deployments/app-name/.

The oc4j-connectors.xml file contains the list of resource adapters for the Web application packaged within an EAR file (one entry for each resource adapter). For details on this file, see "The oc4j-ra.xml Descriptor" and "The oc4j-connectors.xml Descriptor". Applications with embedded RARs are deployed in the same fashion (either using the admin.jar tool or manually) as applications without RARs.

A resource adapter archive, myPackaged.rar, is packaged in the EAR file myApp.ear. The application is then deployed with OC4J under $OC4J_HOME/applications/myapp/myPackaged.

If the EAR file includes an oc4j-connectors.xml file specifying the deployment name myRA, the generated oc4j-ra.xml file is located in $OC4J_HOME/application-deployment/myapp/myRA/. An oc4j-connectors.xml file is created under $OC4J_HOME/application-deployment/myapp/.

Example:

Assume that a standalone resource adapter connection is configured in oc4j-ra.xml to be bound to the location eis/myEIS. An application component looks up its connection factory using the JNDI name "java:comp/env/eis/myEIS". The application component must have the <resource-ref> element defined in its deployment descriptor in web.xml or ejb-jar.xml, which may look like the following example:

<resource-ref> 
  <res-ref-name>eis/myEIS</res-ref-name> 
  <res-type>javax.resource.cci.ConnectionFactory</res-type> 
  <res-auth>Application</res-auth> 
  <res-sharing-scope>Shareable</res-sharing-scope> 
</resource-ref> 

try 
{ 
 Context ic = new InitialContext(); 
 cf = (ConnectionFactory) 
   ic.lookup("java:comp/env/eis/myEIS"); 
 } catch (NamingException ex) { 
ex.printStackTrace(); 
} 

Specifying Container-Managed or Component-Managed Sign-On

Applications can use either application components or the OC4J application server to manage resource-adapter sign-on to the EIS system. You specify the manager using the <res-auth> deployment descriptor element for EJB or Web components. If <res-auth> is set to Application, the application component signs on to the EIS programmatically. The application component is responsible for providing explicit security information for the sign-on. If <res-auth> is set to Container, OC4J provides the resource principal and credentials required for signing on to the EIS.

Example:

Context initctx = new InitialContext(); 
// perform JNDI lookup to obtain a connection factory 
javax.resource.cci.ConnectionFactory cxf = 
       
(javax.resource.cci.ConnectionFactory)initctx.lookup("java:com/env/eis/MyEIS"); 
  // For container-managed sign-on, no security information is passed in the 
getConnection call 
  javax.resource.cci.Connection cx = cxf.getConnection(); 
  // If component-managed sign-on is specified, the code should instead provide 
explicit security 
  // information in the getConnection call 
  // We need to get a new ConnectionSpec implementation instance for setting 
login 
  // attributes 
  com.myeis.ConnectionSpecImpl connSpec = ... 
  connSpec.setUserName("EISuser"); 
  connSpec.setPassword("EISpassword"); 
  javax.resource.cci.Connection cx = cxf.getConnection(connSpec);

In either case, the createManagedConnection method in the resource adapter's implementation of javax.resource.spi.ManagedConnectionFactory interface is called to create a physical connection to the EIS.

If you specify component-managed sign-on, OC4J invokes the createManagedConnection method with a null Subject and the ConnectionRequestInfo object passed in from the application component code. If you specify container-managed sign-on, OC4J provides a javax.security.auth.Subject object to the createManagedConnection method. The content of the Subject object depends on the value in the <authentication-mechanism-type> and <credential-interface> elements in the resource adapter deployment descriptor.

If <authentication-mechanism-type> is BasicPassword and <credential-interface> is javax.resource.spi.security.PasswordCredential, then the Subject object must contain javax.resource.spi.security.PasswordCredential objects in the private credential set.

On the other hand, if <authentication-mechanism-type> is Kerbv5 or any other non-password-based authentication mechanism, and <credential-interface> is javax.resource.spi.security. GenericCredential, then the Subject object must contain credentials represented by instances of implementers of the javax.resource.spi.security.GenericCredential interface. The GenericCredential interface is used for resource adapters that support non-password-based authentication mechanisms, such as Kerberos.

Authentication in Container-Managed Sign-On

When using container-managed sign-on, OC4J must provide a resource principal and its credentials to the EIS. The principal and credentials can be obtained in one of the following ways:

• Configured Identity - The resource principal is independent of the initiating/caller principal and can be configured at deployment time in a deployment descriptor.

• Principal Mapping - The resource principal is determined by a mapping from the identity and/or security attributes of the initiating/caller principal.

• Caller Impersonation - The resource principal acts on behalf of an initiating/caller principal by delegating the caller's identity and credentials to the EIS.

• Credentials Mapping - The resource principal is the same as the initiating/caller principal, but with its credential mapped from the authentication type used by OC4J to the authentication type used by the EIS. An example would be to map a public key certificate-based credential associated with a principal to a Kerberos credential.

OC4J supports all these methods with three authentication mechanisms:

• JAAS Pluggable Authentication

• User-Created Authentication Classes

• Modifying oc4j-ra.xml

The following sections discuss these mechanisms in detail.

JAAS Pluggable Authentication

OC4J furnishes a JAAS pluggable authentication framework that conforms to Appendix C in the Connector Architecture 1.0 specification. With this framework, an application server and its underlying authentication services remain independent from each other, and new authentication services can be plugged in without requiring modifications to the application server.

Authentication services can obtain resource principals and credentials using any of the following modules:

• Principal Mapping JAAS module

• Credential Mapping JAAS module

• Kerberos JAAS module (used for Caller Impersonation)

The JAAS login modules can be provided by resource adapter vendors, the EIS vendors, or by the customer. Login modules must implement the javax.security.auth.spi.LoginModule interface, as documented in the Sun JAAS specification.

OC4J provides initiating user subjects to login modules by passing an instance of javax.security.auth.Subject containing any public certificates and an instance of oracle.j2ee.connector.InitiatingPrincipal representing the OC4J user. OC4J may pass a null Subject if there is no authenticated user (that is, an anonymous user). The JAAS login module's login method must, based on the initiating user, find the corresponding resource principal and create new PasswordCredential or GenericCredential instances for the resource principal. The resource principal and credential objects are then added to the initiating Subject in the commit method. The resource credential is passed to the createManagedConnection method in the javax.resource.spi.ManagedConnectionFactory implementation provided by the resource adapter. If a null Subject is passed, the JAAS login module is responsible for creating a new javax.security.auth.Subject containing the resource principal and the appropriate credential.

The InitiatingPrincipal and InitiatingGroup Classes

The classes oracle.j2ee.connector.InitiatingPrincipal and oracle.j2ee.connector.InitiatingGroup are used to represent OC4J users to the JAAS login modules. OC4J creates instances of oracle.j2ee.connector.InitiatingPrincipal and incorporates them into the Subject that is passed to the initialize method of the login modules. The oracle.j2ee.connector.InitiatingPrincipal class implements the java.security.Principal interface, and adds the method getGroups().

  /**
   * Returns a Set of groups (or roles in JAZN terminology) that this
   * principal is a member of.
   *
   * @return A set of InitiatingGroup objects representing the groups
   *      that this pricipal belongs to.
   */
  public Set getGroups()

The getGroups method returns a java.util.Set of oracle.j2ee.connector.InitiatingGroup objects, representing the OC4J groups or JAZN roles for this OC4J user. The group membership is defined in OC4J-specific descriptor files such as principals.xml or jazn-data.xml, depending on the user manager. The oracle.j2ee.connector.InitiatingGroup class implements but does not extend the java.security.Principal interface.

Login modules can use getGroups() to provide mappings between OC4J groups and EIS users. The java.security.Principal interface methods support mappings between OC4J users and EIS users. Login modules do not need to refer to the oracle.j2ee.connector.InitiatingPrincipal and oracle.j2ee.connector.InitiatingGroup classes if they do not provide mappings between OC4J groups and EIS users.

JAAS and the <connector-factory> Element

Each <connector-factory> element in oc4j-ra.xml can specify a different JAAS login module. You specify a name for the connector factory configuration in the <jaas-module> element. Here is an example of a <connector-factory> element in oc4j-ra.xml that uses JAAS login modules for container-managed sign-on:

  <connector-factory connector-name="myBlackbox" location="eis/myEIS1"> 
    <description>Connection to my EIS</description>
    <config-property name="connectionURL" 
value="jdbc:oracle:thin:@localhost:5521:orcl" />
    <security-config>
      <jaas-module>
        <jaas-application-name>JCADemo</jaas-application-name>
      </jaas-module>
    </security-config>
  </connector-factory>

In JAAS you must specify which LoginModule to use for a particular application, and in what order to invoke the LoginModules. JAAS uses the value specified in the <jaas-application-name> element to look up LoginModules.

User-Created Authentication Classes

OC4J provides the oracle.j2ee.connector.PrincipalMapping interface for principal mapping.

package oracle.j2ee.connector;

public interface PrincipalMapping
{
/**
* Initializes the various settings for the PrincipalMapping implementation 
class.
* Implementation class may use the properties for setting default user name and
* password, LDAP connect info, or default mapping.
*
* OC4J will pass the properties specified in the <principal-mapping-interface>
* element in oc4j-ra.xml to this method.
*
* @param prop A Properties object containing the set up information required
*             by the implementation class.
*/
  public void init(Properties prop);

/**
* The ManagedConnectionFactory instance that can be used in creating a 
   * PasswordCredential.
   *
 * @param mcf The ManagedConnectionFactory instance that is needed when
  *creating a PasswordCredential instance
  */
  public void setManagedConnectionFactory(ManagedConnectionFactory mcf);

  /**
* Passes the authentication mechanism(s) supported by the resource
* adapter to the PrincipalMapping implementation class.
   * The key of the map passed is a String containing the supported mechanism
* type, such as "BasicPassword", or "Kerbv5". The value is a String
  * containig the corresponding credentials interface as declared in ra.xml,
* such as "javax.resource.spi.security.PasswordCredential".
  *
 * The map may contain multiple elements if the resource adatper supports
  * multiple authentication mechanisms.
   *
 * @param authMechanisms The authentication mechanisms and their corresponding
   *  credentials intereface supported by the resource adapter
  */
  public void setAuthenticationMechanisms(Map authMechanisms);

    /**
* This is the method that performs the principal mapping. An application user
   * subject is passed, and the implemetation of this method should return
   * a subject for use by the resource adapter to log in to the EIS resource 
* per the JCA specifications.
   *
 * OC4J will only called this method for container-managed sign on.
*
 * @param initiatingSubject A Subject containing the application server logged
   *     in principals and public credentials.
     *
    * @return A Subject for use by resource adapter to log in to the remote EIS.
    *      It may return null if the proper resource principal cannot be 
determined.
  */
  public Subject mapping(Subject initiatingSubject);
}

The mapping method must return a Subject containing the resource principal and credential. The Subject returned must adhere to either option A or option B in section 8.2.6 of the Connector Architecture 1.0 specification. OC4J invokes the mapping method with the initiating user as the initiatingPrincipal.

OC4J also provides the abstract class oracle.j2ee.connector.AbstractPrincipalMapping. This class provides a default implementation of the setManagedConnectionFactory() and setAuthenticationMechanism() methods, as well as utility methods to determine whether the resource adapter supports the BasicPassword or Kerbv5 authentication methods, and a method for extracting the Principal from the application server user Subject. By extending the oracle.j2ee.connector.AbstractPrincipalMapping class, developers need only implement the init and mapping methods.

Here are the utility methods provided by the oracle.j2ee.connector.AbstractPrincipalMapping class:

/**
   *  Utility method provided by this abstract class to return
  *  the ManagedConnectionFactory instance for use to create a
    *  PasswordCredentials object
   *
    *  @return The ManagedConnectionFactory instance that is needed when
    *    creating a PasswordCredential instance
    */
  public ManagedConnectionFactory getManagedConnectionFactory()

   /**
   * Utility method provided by this abstract class to return the Map
   * of all authentication mechanisms supported by this resource adapter.
  * The key of the map passed is a String containing the supported mechanism
   * type, such as "BasicPassword", or "Kerbv5". The value is a String
  * containig the corresponding credentials interface as declared in ra.xml,
   * such as "javax.resource.spi.security.PasswordCredential".
  *
    * @return The authentication mechanisms and their corresponding
      *      credentials intereface supported by the resource adpater
   */ 
    public Map getAuthenticationMechanisms()

     /**
   * Utility method provided by this abstract class to return whether
   * BasicPassword authention mechanism is supported by this resource
   * adapter.
   *
    * @return true if BasicPassword authentication mechanism is supported
   *      by the resource adapter, false otherwise.
  */ 
    public boolean isBasicPasswordSupported()

    /**
   * Utility method provided by this abstract class to return whether
   * Kerbv5 authention mechanism is supported by this resource
  * adapter.
   *
    * @return true if Kerbv5 authentication mechanism is supported
  *      by the resource adapter, false otherwise.
  */ 
    public boolean isKerbv5Supported()

   /**
   * Utility method provided by this abstract class to extract the
      * Principal object from the given application server user subject
    * passed from OC4J.
  *
    * @param subject The application server user subject passed from
     *       OC4J.
  *
    * @return The principal extracted from the given subject
     */ 
    public Principal getPrincipal(Subject subject)

After you create your implementation class, copy a JAR file containing the class into the directory containing the decompressed RAR file. This directory is typically $OC4J_HOME/applications/application_name/rar-name. After copying the file, edit oc4j-ra.xml to contain a <principal-mapping-interface> element for the new class; see "The <security-config> Element" for details.

Extending AbstractPrincipalMapping

This simple example demonstrates how to extend the oracle.j2ee.connector.AbstractPrincipalMapping abstract class to provide a principal mapping that always maps the user to the default user and password. You specify the default user and password by using properties under the <principal-mapping-interface> element in oc4j-ra.xml.

The PrincipalMapping class is called MyMapping. It is defined as follows:

package com.acme.app;

import java.util.*;
import javax.resource.spi.*;
import javax.resource.spi.security.*;
import oracle.j2ee.connector.AbstractPrincipalMapping;
import javax.security.auth.*;
import java.security.*;

public class MyMapping extends AbstractPrincipalMapping
{
  String m_defaultUser;

   String m_defaultPassword;

    public void init(Properties prop)
    {
      if (prop != null)
      {
           // Retrieves the default user and password from the properties
         m_defaultUser = prop.getProperty("user");
           m_defaultPassword = prop.getProperty("password");
      }
    }

    public Subject mapping(Subject initiatingSubject)
    {
      // This implementation only supporst BasicPassword authentication
      // mechanism. Return if the resource adapter does not support it.
      if (!isBasicPasswordSupported())
            return null;

      // Use the utility method to retrieve the Principal from the
      // OC4J user. This code is included here only as an example.
      // The principal obtained is not being used in this method.
       Principal principal = getPrincipal(initiatingSubject);

    char[] resPasswordArray = null;
      if (m_defaultPassword != null)
         resPasswordArray = m_defaultPassword.toCharArray();

       // Create a PasswordCredential using the default user name and 
      // password, and add it to the Subject per option A in section
    // 8.2.6 in the JCA 1.0 spec.
     PasswordCredential cred = new PasswordCredential(m_defaultUser, 
resPasswordArray);
        cred.setManagedConnectionFactory(getManagedConnectionFactory());
       initiatingSubject.getPrivateCredentials().add(cred);
      return initiatingSubject;
    }
}

You add a <principal-mapping-interface> entry to oc4j-ra.xml that specifies com.acme.app.MyMapping for the principal mapping mechanism:

  <connector-factory name="..." location="...">
    ...
    <security-config>
   <principal-mapping-interface>
     <impl-class>com.acme.app.MyMapping</impl-class>
     <property name="user" value="scott" />
     <property name="password" value="tiger" />
   </principal-mapping-interface>
    </security-config>
    ...
  </connector-factory>

Modifying oc4j-ra.xml

If you prefer, you can create default principal mappings in the oc4j-ra.xml file. To use the default principal mappings mechanism, use the <principal-mapping-entries> subelement under the <security-config> element. For syntax details, see "The <security-config> Element".

You use the <default-mapping> element to specify the user name and password for the default resource principal. This principal is used to log on to the EIS if there is no <principal-mapping-entry> element whose initiating user corresponds to the current initiating principal. If no default mapping is specified, OC4J uses the values of the configuration properties UserName and Password from the deployment descriptor (either in ra.xml or oc4j-ra.xml), assuming these defaults are acceptable to the resource adapter. If neither configuration properties nor a default mapping is specified, OC4J may not be able to log in to the EIS.

Each <principal-mapping-entry> element contains a mapping from initiating principal to resource principal and password.

For example, if the OC4J principal scott should be logged in to a certain EIS, myEIS1, as user name scott and password tiger, while all other OC4J users should be logged in to the EIS using user name guest with password guestpw, the <connector-factory> element in oc4j-ra.xml should look like this:

<connector-factory name="..." location="...">
    ...
  <security-config>
    <principal-mapping-entries>
      <default-mapping>
        <res-user>guest</res-user>
        <res-password>guestpw</res-password>
      </default-mapping>
      <principal-mapping-entry>
        <initiating-user>scott</initiating-user>
        <res-user>scott</res-user>
        <res-password>tiger</res-password>
      </principal-mapping-entry>
    </principal-mapping-entries>
  </security-config>
    ...
</connector-factory>