|
Oracle® Application Server Containers for J2EE Services Guide
10g Release 2 (10.1.2) for Windows or UNIX B14012-02 |
|
 Previous |
 Next |
|
Oracle® Application Server Containers for J2EE Services Guide
10g Release 2 (10.1.2) for Windows or UNIX B14012-02 |
|
|
Previous |
Next |
This chapter describes how to use the J2EE Connector Architecture (J2CA) 1.0 in an Oracle Application Server Containers for J2EE (OC4J) application. This chapter covers the following topics:
The J2EE Connector Architecture defines a standard architecture for connecting the J2EE platform to heterogeneous Enterprise Information Systems (EISs). Typical EISs include Enterprise Resource Planning (ERP), database systems, mainframe transaction processing, and legacy applications that are not written in the Java programming language. shows the J2EE Connector Architecture.
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 a JDBC driver to connect to a relational database, an ERP resource adapter to connect to an ERP system, and a transaction processing (TP) resource adapter to connect to a TP monitor. The J2EE 1.3 specification requires application servers to support both standalone and embedded resource adapters.
A resource adapter module that can be deployed directly into an application server independent of other applications is called a standalone resource adapter. These adapters, which are stored in standalone resource adapter archive (RAR) files, are available to all applications that are deployed in the application server instance. See "Example of RAR File Structure" for an example of the contents and structure of an RAR archive.
A resource adapter module that is deployed as part of a J2EE application that also contains one or more J2EE modules, is called an embedded resource adapter. These adapters are available only to the J2EE applications with which they are bundled in an enterprise application archive (EAR) file.
Here is an example of the contents and structure of an RAR archive:
/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 that are referred to in the RAR file can be located in any directory within the archive. |
|
Note: The file/META-INF/oc4j-ra.xml is not generally part of the RAR archive provided by the RAR vendor, and is typically generated by OC4J during deployment. But a deployer can choose to add the file oc4j-ra.xml to the RAR archive before deployment. Alternatively, the deployer can edit the generated file.
|
Depending on the resource adapter, applications or application modules might need to access adapter-specific classes that are bundled with the RAR. In the case of standalone resource adapters, these custom classes are available to all applications that are deployed within OC4J. In the case of embedded resource adapters, they are available only to modules that are part of the same application as the embedded adapter.
The client API furnished by a resource adapter can be either a client API that is specific to the type of a resource adapter and its underlying EIS, or the standard Common Client Interface (CCI). For more information on CCI, see the J2EE Connector 1.0 Specification. An example of a client API is JDBC, the client API that is specific to relational database accesses.
You can determine what client interface a resource adapter supports. The client interface is specified in the <connection-interface> element in the ra.xml file bundled in the RAR archive.
J2EE Connector Architecture also defines three Quality of Service (QoS) contracts between an application server and an EIS.
Connection Management enables application components to connect to an EIS and leverage any connection pooling provided by the application server. Also see "Configuring Connection Pooling".
|
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 to manage transactions across multiple resource managers.
Transaction management does not require any deployment-time configuration. For more information, see the J2EE Connector 1.0 Specification.
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.
OC4J does not support two-phase commit for J2EE Connector Architecture resource adapters. (For information on the limitations of two-phase commit, see Chapter 7, "Java Transaction API".)
Security management provides authentication, authorization, and secure communication between the J2EE server and the EIS. Also see "Managing EIS Sign-On".
All resource adapters must support their side of the QoS contracts to be pluggable into application servers.
This section discusses the details of deploying and undeploying resource adapters.
OC4J supports three deployment descriptors: ra.xml, oc4j-ra.xml, and oc4j-connectors.xml. The ra.xml descriptor is always supplied with the resource adapter. Whenever you deploy a resource adapter, OC4J generates oc4j-ra.xml if the file doesn't already exist in the archive. In addition, for an embedded resource adapter, OC4J generates oc4j-connectors.xml if it doesn't exist in the archive.
The oc4j-ra.xml descriptor provides OC4J-specific deployment information for resource adapters. The file contains one or more <connector-factory> elements.
You can do the following using oc4j-ra.xml:
Configure and bind instances of connection factories.
Connection factories are used by application components to obtain connections to the EIS. The name of the connection factory class is specified in the connectionfactory-impl-class element, defined in ra.xml. OC4J allows the deployer to configure instances of this class and to bind them to the Java Naming and Directory Interface (JNDI) name space.
The deployer can do this by creating <connector-factory> elements and assigning a JNDI location to each using the location attribute. The deployer can also configure each instance using <config-property> elements.
The list of configurable properties is specified in ra.xml, as <config-property> elements. The deployer can either specify or override values for these properties in oc4j-ra.xml, using <config-property> elements.
Example: Consider a resource adapter with a connection factory implementation of com.example.eis.ConnectionFactoryImpl. Assume that this adapter has been deployed standalone with one configured connection factory, whose JNDI location is myEIS/connFctry1. The <connector-factory> has been configured to connect to host myMc123 on port 1999. Also assume there is an EJB application that looks up and use this connection factory, using a logical name of eis/myEIS.
The following are the files that are relevant to this example.
ra.xml: Specification of connection factory implementation (as provided by the resource adapter vendor).
<resourceadapter> ... <config-property> <config-property-name>HostName</config-property-name> <config-property-type>java.lang.String</config-property-type> </config-property> <config-property> <config-property-name>Port</config-property-name> <config-property-type>java.lang.Integer</config-property-type> <config-property-value>2345</config-property-value> </config-property> <connectionfactory-impl-class> com.example.eis.ConnectionFactoryImpl </connectionfactory-impl-class> ... </resourceadapter>
oc4j-ra.xml: Specification of connection factory implementation with properties myMc123 (host) and 1999 (port), to be bound to JNDI location myEIS/connFctry1 (likely generated by OC4J and edited by deployer).
<connector-factory location="myEIS/connFctry1"> ... <config-property> <config-property-name>HostName</config-property-name> <config-property-value>myMc123</config-property-value> </config-property> <config-property> <config-property-name>Port</config-property-name> <config-property-value>1999</config-property-value> </config-property> ... </connector-factory>
|
Note: The<config-property-type> element does not appear in the oc4j-ra.xml file because the type cannot be changed.
|
ejb-jar.xml: Specification of resource reference (that is, connection factory) accessed by EJB (as provided by the application vendor).
<resource-ref> <res-ref-name>eis/myEIS</res-ref-name> <res-type>javax.resource.cci.ConnectionFactory</res-type> <res-auth>Application</res-auth> </resource-ref>
orion-ejb-jar.xml: Mapping of the logical reference name to the real JNDI name (likely generated by OC4J and edited by deployer).
<resource-ref-mapping name ="eis/myEIS" location ="myEIS/connFctry1"/>
EJB class: Usage of the connection factory (created by developer).
try
{
Context ic = new InitialContext();
cf = (ConnectionFactory) ic.lookup("java:comp/env/eis/myEIS");
} catch (NamingException ex) {
ex.printStackTrace();
}
Customize connection pooling
The deployer can configure connection pooling for each instance of a connection factory using the <connection-pooling> element. This element is discussed under "Configuring Connection Pooling".
Manage authentication
The deployer can use the <security-config> element to configure an authentication scheme for each instance of a connection factory. This element is applicable only if application components use container-managed sign-on. Also see "Managing EIS Sign-On".
Set up logging
The deployer can set up logging, per connection factory instance, using the <log> element. Here is an example:
<connector-factory location="myEIS/connFctry1">
<log>
<file path="./logConnFctry1.log" />
</log>
</connector-factory>
If the path name is not specified or if the directory does not exist, logging is not enabled and OC4J prints out a warning message. If the directory exists but the file does not, OC4J creates the file and enables logging. Because there is no default location for the log file, if the <log> element is not specified, logging is not enabled.
Additionally, the deployer can also add a <description> element to each <connector-factory> element. The element contains a description of the connection factory and is not interpreted by OC4J.
The resource adapters that are deployed to OC4J can be configured through the oc4j-connectors.xml descriptor. There is one oc4j-connectors.xml file for all of the standalone adapters (as a group) as well as one per application.
|
Note: The file /META-INF/oc4j-connectors.xml is not generally part of the EAR archive provided by the EAR vendor, and is typically generated by OC4J during deployment. But a deployer can choose to add the file oc4j-connectors.xml to the EAR archive before deployment. Alternatively, the deployer can edit the generated file. |
The root element is <oc4j-connectors>. Each individual connector is represented by a <connector> element that specifies the name and path name for the connector. Each <connector> element contains the following elements:
<description>: text description of the connector. It is not interpreted by OC4J. This element is optional.
<native-library path="pathname">: 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 directory. OC4J interprets the pathname attribute relative to the decompressed RAR directory. This element is optional.
<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. That is, the deployer has to explicitly grant the permissions requested by the resource adapter. The default behavior of OC4J is to not grant those permissions during deployment.
Example:
<oc4j-connectors>
<connector name="myEIS" path="eis.rar">
<native-library> path="lib"</native-library>
<security-permission>
<security-permission-spec enabled="false">
grant {permission java.lang.RuntimePermission "LoadLibrary.*"};
</security-permission-spec>
</security-permission>
</connector>
</oc4j-connectors>
|
Note: The path attribute of the <native-library> element should point to the directory in which the .dll or .so files are located. For the preceding example, here is a possible RAR structure:/META-INF/ra.xml /ra.jar /lib/win.dll /lib/solaris.so |
During deployment of standalone resource adapters, give each a unique name for future operations, such as undeployment of the resource adapter. OC4J does not permit deployment of two standalone resource adapters that have the same name.
The deployment descriptors and decompressed RAR files are located as shown in Table 8-2.
During deployment, OC4J decompresses the RAR file and creates OC4J-specific deployment descriptor files if they do not exist already. The deployment process automatically adds <connector> entries in the oc4j-connectors.xml file. Skeleton entries for <connector-factory> elements are created as well in oc4j-ra.xml. The deployer can edit these two files for further configuration. For more information, see the Oracle Application Server Administrator's Guide.
You deploy standalone resource adapters in one of the following ways:
To deploy a standalone resource adapter to an Oracle Application Server instance, use the command-line tool dcmctl with the deployApplication option. Here is the syntax:
dcmctl deployApplication -f example.rar -a example
The deployApplication switch is supported by additional command-line switches:
-f myRA.rar: path name of the resource adapter's RAR file. This switch is required.
-a myRA: resource adapter's name. This switch is required.
To remove a deployed resource adapter, dcmctl with the undeployApplication option. Here is the syntax:
dcmctl undeployApplication -a example
The required -a argument specifies which adapter is being removed.
dcmctl supports RAR files, as well as WAR and EAR files. For more information, see the Oracle Application Server Administrator's Guide.
To deploy a standalone resource adapter to an OC4J standalone instance, use the command-line tool admin.jar with the -deployconnector switch. Here is the syntax:
-deployconnector -file mypath.rar -name myname -nativeLibPath libpathname -grantAllPermissions
The -deployconnector switch is supported by additional command-line switches:
-file myRA.rar - path name of the resource adapter's RAR file. This switch is required.
-name myRA: resource adapter's name. This switch is required.
-nativeLibPath libpathname - path name 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 file (see also the <security-permission> element in "The oc4j-connectors.xml Descriptor").
java -jar admin.jar ormi://localhost admin welcome -deployconnector -file ./myRA.rar -name myRA
|
Note: For more information aboutadmin.jar, see the Oracle Application Server Containers for J2EE Stand Alone User's Guide. You can download this document when you download the OC4J standalone product from OTN.
|
Deploying Manually
If you prefer to deploy your connector manually, follow these steps:
Create a connectorname directory under OC4J_HOME/connectors_dir.
Copy the connector's RAR file into OC4J_HOME/connectors_dir/connectorname.
Create an oc4j-connectors.xml file in connectors_dir for the new resource adapter, or add a <connector> element to the file if it already exists.
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 that is 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.
|
To remove a deployed resource adapter, use the -undeployconnector switch of admin.jar. Here is the syntax:
-undeployconnector -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 directories and files that were created during deployment.
Embedded resource adapters cannot be deployed or undeployed independent of the application of which they are a part. The name of the adapter can be specified in the oc4j-connectors.xml file; if not specified in this file, the name used for the adapter is that of the RAR archive.
The deployment descriptors and decompressed RAR files are located as shown in Table 8-2.
As part of deploying the EAR file that contains the embedded resource adapter, OC4J decompresses the RAR file and creates OC4J-specific deployment descriptor files if they do not exist already. The deployment process automatically adds <connector> entries in the oc4j-connectors.xml file. Skeleton entries for <connector-factory> elements are created as well in oc4j-ra.xml. The deployer can edit these two files for further configuration.
Deploy applications that include embedded resource adapters in one of the following ways:
For information on using dcmctl, see the Oracle Application Server Administrator's Guide.
Table 8-1 shows the paths to various deployment directories that OC4J creates during deployment that are referenced throughout the guide. The paths are relative to the root directory of your OC4J installation. The deployment directories can be customized within server.xml by setting the attributes shown in the table. These attributes belong to the <application-server> element.
|
|
Attribute | Description of Attribute | Default Value |
|---|---|---|---|
connectors_dir
|
connector-directory
|
The root directory for all standalone resource adapters. | connectors
|
applications_dir
|
applications-directory
|
The root directory for all applications. | applications
|
application_deployments_dir
|
deployment-directory
|
The root directory for all files generated at deployment. | application-deployments
|
Table 8-2 shows the paths to various files produced during deployment that are referenced throughout the guide. The paths are relative to the root directory of your OC4J installation. In Table 8-2, appname is the name under which the application is deployed.
|
|
Standalone Resource Adapter | Embedded Resource Adapter |
|---|---|---|
| Location of decompressed RAR archive | connectors_dir/deployment_name
|
applications_dir/appname/rar_name
|
| oc4j-connectors.xml | config
or as defined in the |
application_deployments_dir/appname/META-INF
or as defined in the |
| oc4j-ra.xml | application_deployments_dir/default/deployment_name
|
application_deployments_dir/appname/rar_name
or
|
You can configure connection pooling and authentication mechanisms on a per-connection basis at deployment time. This section describes the different ways to accomplish this.
Connection pooling is a J2EE 1.3 feature that allows a set of connections to be reused within an application. Because the J2EE Connector 1.0 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 in oc4j-ra.xml, specify a <property> element within the optional <connection-pooling> element. If you don't specify this element, whenever the application requests a connection, a new connection is created. Here is the syntax:
<property name="propname" value="propvalue" />.
The value for propname must be one of:
maxConnections - maximum number of connections permitted within a pool. If no value is specified, there is no limit on the number of connections.
minConnections - minimum number of connections. If minConnections is greater than 0, the specified number of connections are 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. The default value is 0.
scheme - specifies how OC4J handles connection requests after the 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.
|
Note: OC4J does not destroy pooled connections upon close unless the pool size is above the maximum specified in the maxConnections property. |
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 that OC4J waits for an available connection if maxConnections has been exceeded and the fixed_wait scheme is in effect. In all other cases, this property is ignored.
|
Note: If you make no waitTimeout specification, the default behavior is not to time out. |
Here is an example of a <connection-pooling> element configuration:
<connection-pooling>
<description>my pooling configuration </description>
<property name="waitTimeout" value="60" />
<property name="scheme" value="fixed_wait" />
<property name="maxConnections" value="3" />
<property name="minConnections" value="1" />
</connection-pooling>
The example defines a connection pool with a minimum of one connection (OC4J tries to create one connection during start up) and a maximum of three connections. When all three connections are in use and a request for connection is issued, the pool with a fixed_wait scheme tries to wait a maximum of 60 seconds for a connection to be returned to the pool. If there is still no connection available after 60 seconds, an exception is thrown to the caller of the API that requested a new connection.
As part of extending the end-to-end security of the J2EE mode to cover integration to EISs, J2EE Connector architecture allows application components to associate a security context with connections established to the EIS.
Application components can either sign on to the EIS by themselves, or have OC4J manage the sign-on. Component-managed sign-on must be implemented programmatically, while container-managed sign-on can be specified either declaratively or programmatically. Specify the type of sign-on using the <res-auth> deployment descriptor element for EJB or Web components.
|
Note: The remainder of this section assumes that you are familiar with chapter 7 of the J2EE Connector Architecture 1.0 specification. The specification uses the terms initiating principal, caller principal, and resource principal. As used in this section, the incoming security context refers to either initiating principal or caller principal, and the outgoing security context refers to resource principal. |
When deploying applications that manage EIS sign-on by themselves, set <res-auth> to Application. The application component is responsible for providing explicit security information for the sign-on.
Figure 8-2 shows the steps involved in component-managed sign-on. The steps are detailed following the diagram.
The client makes a request, which is associated with an incoming security context.
As part of servicing the request, the application component maps the incoming security context to an outgoing security context and then uses the outgoing security context to request a connection to the EIS.
As part of the connection acquisition, the resource adapter logs on to the EIS using the outgoing security context provided by the application component.
Once the connection is acquired, the application component can interact with the EIS under the established outgoing security context.
The following example is an excerpt from an application that performs component-managed sign-on.
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");
// 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);
When deploying applications that depend on the container for EIS sign-on, set <res-auth> to Container. The container is responsible for providing security information for the sign-on. Additionally, the container uses deployment descriptors or pluggable authentication classes to determine outgoing security context.
shows the steps involved in container-managed sign-on. The steps are detailed following the diagram.
The client makes a request, which is associated with an incoming security context.
As part of servicing the request, the application component requests a connection to the EIS.
As part of the connection acquisition, the container (the OC4J security context manager shown in ) maps the incoming security context to outgoing security context, based on deployment descriptor elements (not shown in the figure) or authentication class provided.
The resource adapter logs on to the EIS using the outgoing security context provided by the container.
Once the connection is acquired, the application component can interact with the EIS under the established outgoing security context.
The following example is an excerpt from an application that depends on container-managed sign-on.
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();
You can create principal mappings in the oc4j-ra.xml file. To employ the principal mappings mechanism, use the <principal-mapping-entries> subelement under the <security-config> element.
Each <principal-mapping-entry> element contains a mapping from initiating principal to resource principal and password.
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 the element <principal-mapping-entries> is not specified, OC4J may not be able to log in to the EIS.
For example, if the OC4J principal scott should be logged in to the EIS 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>
|
Note: The<res-password> element supports password indirection. For more information, refer to the Oracle Application Server Containers for J2EE Security Guide.
|
OC4J supports the use of programmatic authentication—either through the use of an OC4J-specific mechanism or a standard mechanism like the Java Authentication and Authorization Service (JAAS). See the Sun JAAS specification for more information.
OC4J provides the oracle.j2ee.connector.PrincipalMapping interface for principal mapping. Its methods appear in Table 8-2.
To use OC4J-specific programmatic container-managed sign-on, an implementation of this interface must be provided.
Table 8-3 Method Description for oracle.j2ee.connector.PrincipalMapping Interface
| Method Signature | Description |
|---|---|
public void init(java.util.Properties prop)
|
Called by OC4J to initialize the settings for the PrincipalMapping implementation class. OC4J passes the properties specified in the <config-property> elements in oc4j-ra.xml to this method. The implementation class can use the properties for setting default user name and password, LDAP connection information, or default mapping.
|
public void setManagedConnectionFactory (ManagedConnectionFactory mcf)
|
Used by OC4J to provide the implementation class with the ManagedConnectionFactory instance that is needed to create a PasswordCredential.
|
public void setAuthenticationMechanisms (java.util.Map authMechanisms)
|
Called by OC4J to pass the authentication mechanisms 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 containing the corresponding credentials interface as declared in ra.xml, such as javax.resource.spi.security.PasswordCredential. The map can contain multiple elements if the resource adapter supports multiple authentication mechanisms.
|
public javax.security.auth.Subject mapping (javax.security.auth.Subject initiatingSubject)
|
Used by OC4J to allow the implementation class to perform the principal mapping. An application user subject is passed, and the implementation of this method should return a subject for use by the resource adapter to log in to the EIS resource per the J2CA 1.0 specifications. The implementation may return null if the proper resource principal cannot be determined.
|
When a connection to the EIS is created, OC4J invokes the mapping method with the initiating user as the initiatingPrincipal. The mapping method must return a Subject containing the resource principal and credential. The Subject that is returned must adhere to either option A or option B in section 8.2.6 of the Connector Architecture 1.0 specification.
OC4J also provides the abstract class oracle.j2ee.connector.AbstractPrincipalMapping. This class furnishes a default implementation of the setManagedConnectionFactory() and setAuthenticationMechanism() methods, as well as utility methods to determine whether the resource adapter supports the BasicPassword or Kerberos version 5 (Kerbv5) authentication mechanisms, 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.
The methods exposed by the oracle.j2ee.connector.AbstractPrincipalMapping class appear in Table 8-4.
Table 8-4 Method Description for oracle.j2ee.connector.AbstractPrincipalMapping Class
| Method Signature | Description |
|---|---|
public abstract void init (java.util.Properties prop)
|
This method must be implemented by the subclasses. See PrincipalMapping interface, described in Table 8-3, for details.
|
public void setManagedConnectionFactory (ManagedConnectionFactory mcf)
|
Stores the ManagedConnectionFactory instance that is passed in. Subclasses need not implement this method, and can make use of the getManagedConnectionFactory object saved by this method.
|
public void setAuthenticationMechanisms (java.util.Map authMechanisms)
|
Stores the map of authentication mechanisms. Subclasses need not implement this mechanism. Instead, they can make use of the isBasicPasswordSupported or isKerbv5Supported methods to determine which authentication mechanism is supported by the resource adapter. The method getAuthenticationMechanisms can be used to retrieve the authentication mechanisms as well.
|
public javax.security.auth.Subject mapping (javax.security.auth. Subject initiatingSubject)
|
Used by OC4J to allow the implementation class to perform the principal mapping. An application user subject is passed, and the implementation of this method should return a subject for use by the resource adapter to log in to the EIS resource per the J2EE Connector Architecture specifications. The implementation may return null if the proper resource principal cannot be determined. |
public abstract javax.security.auth.Subject mapping (javax.security.auth. Subject initiatingSubject)
|
This method must be implemented by the subclasses. See PrincipalMapping interface, described in Table 8-3, for details.
|
public ManagedConnectionFactory getManagedConnectionFactory()
|
Utility method provided by this abstract class to return the ManagedConnectionFactory instance that might be required to create a PasswordCredentials object.
|
public java.util.Map getAuthenticationMechanisms()
|
Utility method to return the map of all authentication mechanisms supported by this resource adapter, as provided by OC4J. The key of the map returned is a string containing the supported mechanism type, such as BasicPassword or Kerbv5. The value is a string containing the corresponding credentials interface as declared in ra.xml, such as javax.resource.spi.security.PasswordCredential.
|
public boolean isBasicPasswordSupported()
|
Utility method to allow subclass to determine whether the BasicPassword authentication mechanism is supported by this resource adapter. |
public boolean isKerbv5Supported()
|
Utility method to allow subclass to determine whether the Kerbv5 authentication mechanism is supported by this resource adapter. |
public java.security.Principal getPrincipal (javax.security.auth. Subject subject)
|
Utility method provided to extract the Principal object from the given application server user subject passed from OC4J . |
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. 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 supports 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 Connector 1.0 spec.
PasswordCredential cred =
new PasswordCredential(m_defaultUser, resPasswordArray);
cred.setManagedConnectionFactory(getManagedConnectionFactory());
initiatingSubject.getPrivateCredentials().add(cred);
return initiatingSubject;
}
}
After you create your implementation class, copy a JAR file containing the class into the directory containing the decompressed RAR file. See Table 8-2 for the location of the RAR file. After copying the file, edit oc4j-ra.xml to contain a <principal-mapping-interface> element for the new class.
For example:
<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>
You can also manage sign-on to the EIS programmatically with JAAS. 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.
Some examples of authentication modules are:
Principal Mapping JAAS module
Credential Mapping JAAS module
Kerberos JAAS module (for Caller Impersonation)
The JAAS login modules can be furnished by the customer, the EIS vendors, or the resource adapter vendors. 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 an implementation of java.security.Principal representing the OC4J user. OC4J can pass a null Subject if there is no authenticated user (that is, an anonymous user). The initiating user subject is passed to the initialize method of the JAAS login module.
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 that is 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.
Each <connector-factory> element in oc4j-ra.xml can specify a different JAAS login module. 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>JAASModuleDemo</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 that are specified in the <jaas-application-name> element to look up LoginModules. See the Oracle Application Server Containers for J2EE Security Guide for more information.
In addition to mapping from OC4J users to EIS users, login modules and OC4J-specific authentication classes can also map from OC4J groups to EIS users.
The the oracle.j2ee.connector package contains the InitiatingPrincipal class that represents OC4J users and the InitiatingGroup class that represents OC4J groups. OC4J creates instances of InitiatingPrincipal and incorporates them into the Subject that is passed to the initialize method of the login modules as well as to the mapping method of the OC4J-specific authentication class.
The the oracle.j2ee.connector package also contains the InitiatingPrincipal class that implements the java.security.Principal interface and adds the method getGroups(). The getGroups method returns a java.util.Set of oracle.j2ee.connector.InitiatingGroup objects, representing the OC4J groups or JAZN roles that this OC4J user belongs to. 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 functionality of the java.security.Principal interface.
