Skip Headers

Oracle® Containers for J2EE Security Guide 10g Release 3 (10.1.3) B14429-01 |
| Home | Solution Area | Contents | Index

Previous | Next |

# 16 Security Support for Resource Adapters

This chapter discusses security considerations and how to configure security and authentication when using resource adapters for an enterprise information system (EIS) connection. The following topics are covered:

- Overview of Security and Authentication Setup for EIS Connections

- Understanding Component-Managed Sign-On

- Understanding Container-Managed Sign-On

- Using Declarative Container-Managed Sign-On

- Using Programmatic Container-Managed Sign-On

## Overview of Security and Authentication Setup for EIS Connections

To ensure secure interactions between a J2EE application and an EIS, the J2EE Connector Architecture allows application components to associate a security context with connections established to the EIS. To accomplish this, the J2EE Connector Architecture security contract can work in conjunction with standard JAAS. The following sections provide an overview:

- Summary of J2EE Connector Architecture Security Contract

- Summary of Component-Managed Versus Container-Managed Sign-On

### Summary of J2EE Connector Architecture Security Contract

The J2EE Connector Architecture security contract, between an application server and a resource adapter, extends the connection management contract with functionality relating to secure connections. The security contract supports standard JAAS interfaces, allowing it to be independent of any particular security framework or mechanism. In particular, the security contract includes features for the following:

- Propagating a security context, or subject, directly from a J2EE component to a resource adapter (for component-managed sign-on)

- Propagating a security context, or subject, from an application server to a resource adapter (for container-managed sign-on)

The security contract supports two particular authentication mechanisms:

- The commonly used basic password mechanism relies on a user name / password pair, contained together in a password credential object. The application server passes this object to the resource adapter for authentication.

- The Kerberos version 5 mechanism ("Kerbv5" for short) is an authentication protocol distributed by the Massachusetts Institute of Technology. This mechanism uses a "generic credential" object that encapsulates credential information such as a Kerberos ticket. The application server passes this object to the resource adapter for verification.

Security contract functionality includes use of the following key interfaces:

- `javax.security.auth.Subject`

- `java.security.Principal`

- `javax.security.auth.spi.LoginModule`

- `javax.resource.spi.security.PasswordCredential`

  This J2EE Connector Architecture class represents a user name / password pair for basic password authentication.

- `org.ietf.jgss.GSSCredential` (in J2SE version 1.4)

  This interface represents a generic credential object for Kerberos version 5 authentication. (This replaces the J2EE Connector Architecture `javax.resource.spi.security.GenericCredential` interface, which is deprecated.)

Note: Reauthentication may be supported in the `ra.xml` file of a resource adapter, through a value of `true` in the `<reauthentication-support>` element. In this case, it is possible for a managed connection to be reused even for a connection request with a security context that differs from the security context with which the managed connection was initially created.

### Summary of Component-Managed Versus Container-Managed Sign-On

Sign-on from a J2EE application to an EIS can be managed either by the application component or by the J2EE container (OC4J). Component-managed sign-on must be set up programmatically and does not involve OC4J-specific configuration. Container-managed sign-on can be set up either declaratively, through OC4J-specific configuration without any programming requirements, or programmatically, involving a combination of OC4J-specific configuration and programming requirements. Programmatic container-managed sign-on can use either a principal mapping class or a JAAS login module.

The following list summarizes the options and the type of setup required for component-managed and container-managed sign-on. Bullets at each level represent choices.

- Component-managed sign-on: Requires `web.xml` or `ejb-jar.xml` `<res-auth>` setting of `Application`; programmatic setup for sign-on; no OC4J-specific configuration.

- Container-managed sign-on: Requires `web.xml` or `ejb-jar.xml` `<res-auth>` setting of `Container`; setup for sign-on may be declarative or programmatic; use OC4J-specific configuration, as follows, for each of the container-managed sign-on modes:

  - None: Implies either component-managed sign-on or no security; specify by disabling security for container-managed sign-on through Application Server Control (as described in "Using Declarative Container-Managed Sign-On"); reflected as `use="none"` in `<security-config>` element of `oc4j-ra.xml`.

  - Declarative: OC4J configuration through principal mapping entries; specify by enabling security for container-managed sign-on through Application Server Control (as described in "Using Declarative Container-Managed Sign-On"); reflected as `use="principal-mapping-entries"` with appropriate subelements in `<security-config>` element of `oc4j-ra.xml`.

  - Programmatic, using either a principal mapping class or a JAAS login module:

    - Principal mapping class: Implement `PrincipalMapping` interface directly or extend `AbstractPrincipalMapping` class (both in package `oracle.j2ee.connector`); configure directly through `oc4j-ra.xml` (no Application Server Control support) with `use="principal-mapping-interface"` and appropriate subelements in `<security-config>` element.

    - JAAS login module: Use a JAAS login module; configure directly through `oc4j-ra.xml` (no Application Server Control support) with `use="jaas-module"` and appropriate subelements in `<security-config>` element.

Choices for container-managed sign-on in OC4J are also illustrated in Figure 16-1.

Figure 16-1 Flow Chart of Choices for OC4J Container-Managed Sign-On

Description of "Figure 16-1 Flow Chart of Choices for OC4J Container-Managed Sign-On"

### Summary of Security-Related Resource Adapter Configuration Elements

This section discusses the following key resource adapter configuration elements for security:

- The oc4j-ra.xml File <security-config> Element

- The oc4j-connectors.xml File <security-permission> Element

For additional information about the files and elements discussed here, refer to the Oracle Containers for J2EE Resource Adapter Administrator's Guide.

#### The oc4j-ra.xml File <security-config> Element

The `oc4j-ra.xml` descriptor provides OC4J-specific deployment information (JNDI path name 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 an optional `<security-config>` element that describes how to supply user names and passwords to the EIS.

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:

- Specify mapping subelements explicitly (in the `<principal-mapping-entries>` subelement).

- Specify the name of a user-created mapping class that either implements `oracle.j2ee.connector.PrincipalMapping` or inherits from `oracle.j2ee.AbstractPrincipalMapping` (in the `<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 one of the following:

- A `<principal-mapping-entries>` element, specifying user names and passwords explicitly

- A `<principal-mapping-interface>` element, specifying the name of the mapping class

- A `<jaas-module>` element, specifying the JAAS module to be used for authentication

#### The oc4j-connectors.xml File <security-permission> Element

The `oc4j-connectors.xml` descriptor configures the resource adapters that are deployed by `oc4j-ra.xml`. The `oc4j-connectors.xml` descriptor lists the standalone resource adapters that are deployed in this OC4J instance, as well as the resource adapters that are embedded within applications. This descriptor contains, for each individual connector, a `<connector>` element that specifies the name and path name for the connector. Each `<connector>` element contains a `<security-permission>` element that defines the permissions granted to each resource adapter. The syntax is:

    <security-permission enabled="booleanvalue">

This element specifies the permissions to be granted to each resource adapter. Each `<security-permission>` element contains a `<security-permission-spec>` setting 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.

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

## Understanding Component-Managed Sign-On

When deploying an application that is to manage its EIS sign-on, use a `<res-auth>` setting of `Application` in the appropriate descriptor file (`web.xml` for a Web component or `ejb-jar.xml` for an EJB component). The application component is then responsible for providing explicit security information for the sign-on. Here is an example:

              <resource-ref>
                 <res-ref-name>...</res-ref-name>
                 <res-type>...</res-type>
                 <res-auth>Application</res-auth>
                 <res-sharing-scope>...</res-sharing-scope>
              </resource-ref>

No OC4J-specific configuration is required for component-managed sign-on.

Figure 16-2 shows the steps in component-managed sign-on, with the text that follows providing further detail.

Figure 16-2 Component-Managed Sign-On

Description of "Figure 16-2 Component-Managed Sign-On"

1. The client makes a request, which is associated with an incoming security context for the initiating principal.

2. As part of servicing the request, the application component maps the incoming security context to an outgoing security context for the resource principal, or hard-codes an outgoing security context, then uses the outgoing security context to request a connection to the EIS.

3. As part of the connection acquisition, the resource adapter signs on to the EIS using the outgoing security context provided by the application component.

4. 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");
    // Assume a custom class ConnectionSpecImpl, used to store sign-on credentials.
    com.myeis.ConnectionSpecImpl connSpec = ...
    connSpec.setUserName("EISuser");
    connSpec.setPassword("EISpassword");
    // Pass sign-on credentials through getConnection() method call.
    javax.resource.cci.Connection cx = cxf.getConnection(connSpec);

## Understanding Container-Managed Sign-On

When deploying an application that is to depend on OC4J to manage EIS sign-on, use a `<res-auth>` setting of `Container` in the appropriate descriptor file (`web.xml` for a Web component or `ejb-jar.xml` for an EJB component). OC4J is then responsible for providing security information for the sign-on. Here is an example:

              <resource-ref>
                 <res-ref-name>...</res-ref-name>
                 <res-type>...</res-type>
                 <res-auth>Container</res-auth>
                 <res-sharing-scope>...</res-sharing-scope>
              </resource-ref>

For declarative container-managed sign-on, OC4J uses configuration information that you specify through Application Server Control, as described in "Using Declarative Container-Managed Sign-On". For programmatic container-managed sign-on, through either a principal mapping class or a JAAS login module, OC4J uses configuration information that you specify directly through the `oc4j-ra.xml` file. When an application tries to obtain a connection, OC4J uses the applicable mechanism to determine the outgoing security context and to perform authentication.

Figure 16-3 illustrates the steps in container-managed sign-on. These steps are detailed following the diagram.

Figure 16-3 Container-Managed Sign-On

Description of "Figure 16-3 Container-Managed Sign-On"

1. The client makes a request, which is associated with an incoming security context for the initiating principal.

2. As part of servicing the request, the application component requests a connection to the EIS.

3. As part of the connection acquisition, the container (the OC4J security context manager shown in Figure 16-3) maps the incoming security context to the outgoing security context for the resource principal. This is based on principal mapping entry elements, a principal mapping class, or a JAAS login module.

4. The resource adapter logs in to the EIS using the outgoing security context provided by OC4J.

5. 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();

## 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 or 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 security attributes of the initiating or caller principal.

- Caller impersonation: The resource principal acts on behalf of an initiating or caller principal by delegating the caller identity and credentials to the EIS.

- Credentials mapping: The resource principal is identical to the initiating or caller principal, but with its credential mapped from the authentication type that OC4J uses to the authentication type that the EIS uses. 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 through JAAS pluggable authentication, user-created authentication classes, or appropriate settings in the `oc4j-ra.xml` file.

## Using Declarative Container-Managed Sign-On

This section describes how to set up authentication through OC4J-specific configuration of principal mapping entries. We refer to this as "declarative container-managed sign-on" (as opposed to "programmatic container-managed sign-on"). You can configure this through Application Server Control.

Specify a default resource user and a set of principal mapping entries. Each principal mapping entry specifies an initiating principal and a corresponding resource principal. If the actual initiating principal (OC4J user) during program execution matches one of the initiating principals you specified, then the corresponding resource principal is used for sign-on to the EIS. If the actual initiating principal does not match any you specified, then the default resource user is used for sign-on to the EIS, assuming one is provided or defined. If no default resource user is specified, then a `null` subject will be passed to the EIS. In this case, the EIS has the option of signing on with its own default.

Use the following steps in the Application Server Control Console:

1. From the Connection Factories tab of the appropriate Resource Adapter page, choose the connection factory you want to edit.

2. In the Edit Connection Factory page, go to the Security tab.

3. Choose to enable security for container-managed sign-on.

4. Specify declarative principal mappings. This is to specify the default resource user.

   1. Specify the default resource user name.

   2. Specify a password for the default resource user. You can choose to do this either indirectly or by typing the desired password in clear text. For an indirect password, specify a key (which might just be the user name, for example). OC4J uses the key to do a lookup in the security provider (such as through the `system-jazn-data.xml` file).

5. Specify initiating user mappings. Specify a mapping for each initiating principal that you want to map to a resource principal. You can edit an existing row or change an existing mapping, or add another row to specify a new mapping. For each mapping:

   1. Specify the initiating user, which is the user name of an initiating principal.

   2. Specify the resource user, which is the user name for a corresponding resource principal.

   3. Specify the resource password, which is a password for the mapped resource principal. As with the default principal mapping, you can choose to do this either indirectly or by typing the password directly.

Note: To get to the Resource Adapter page for a standalone resource adapter: From the OC4J Home page, select the Applications tab. View "Standalone Resource Adapters". Select the resource adapter of interest. To get to the Resource Adapter page for a resource adapter deployed with an application: From the OC4J Home page, select the Applications tab. View "Applications". Select the desired application. From the resulting Application Home page, under "Modules", select the resource adapter of interest.

Table 16-1 summarizes how these settings correspond to XML entities in the `oc4j-ra.xml` file. An example follows the table.

Table 16-1 Properties for Declarative Container-Managed Sign-On

Application Server Control Property | Corresponding XML Entity | Description
--- | --- | ---
Enable security for container-managed sign-on | <security-config> element `use` attribute | Being enabled corresponds to `use="principal-mapping-entries"` (assuming declarative container-managed sign-on). Being disabled corresponds to `use="none"`.
Default Resource User | <res-user> subelement of <default-mapping> | User name for the default resource principal.
Indirect Password or Password (for Declarative Principal Mappings) | <res-password> subelement of <default-mapping> | Password for the default resource principal, specified either indirectly or directly.
Initiating User | <initiating-user> subelement of <principal-mapping-entry> | User name for an initiating principal that you want to map to a resource principal. This may be a simple user name, or a realm name followed by a slash and the user name.
Resource User | <res-user> subelement of <principal-mapping-entry> | User name for a resource principal that you want to map to an initiating principal. Each initiating-user/resource-user pair uses a separate <principal-mapping-entry> element.
Resource Password | <res-password> subelement of <principal-mapping-entry> | Password for the resource principal, specified either indirectly or directly.

    <oc4j-connector-factories ... >
       <connector-factory ... >
          ...
          <security-config use="principal-mapping-entries">
             <principal-mapping-entries>
                <default-mapping>
                   <res-user>scott</res-user>
                   <res-password>->tiger</res-password>
                </default-mapping>
                <principal-mapping-entry>
                   <initiating-user>servletuser1</initiating-user>
                   <res-user>jmsuser1</res-user>
                   <res-password>->jmsuser1</res-password>
                </principal-mapping-entry>
                <principal-mapping-entry>
                   <initiating-user>servletuser2</initiating-user>
                   <res-user>jmsuser2</res-user>
                   <res-password>->jmsuser2</res-password>
                </principal-mapping-entry>
             </principal-mapping-entries>
          </security-config>
       </connector-factory>
       ...
    </oc4j-connector-factories>

Note: At this release, the initiating user's name can be specified in the `<initiating-user>` element either as a simple name (`scott`) or as a realm name / user name pair separated by a slash, as in `myRealm/scott`. The user name must be a valid OracleAS JAAS Provider user. In either case, you must specify a OracleAS JAAS Provider default realm. If you supply a simple user name, that name must be a member of the default realm.

## Using Programmatic Container-Managed Sign-On

OC4J can manage programmatic authentication, either through an OC4J-specific mechanism that uses a principal mapping class, or through a pluggable JAAS mechanism that uses a JAAS login module. The following sections discuss these mechanisms plus additional features:

- Using a Principal Mapping Class

- Using a JAAS Login Module for an EIS Connection

### Using a Principal Mapping Class

One option in OC4J for programmatic container-managed sign-on is to use an Oracle feature that implements principal mapping. The application must include a principal mapping class, which is a class that implements the `oracle.j2ee.connector.PrincipalMapping` interface. A developer can accomplish this by implementing the interface directly, or by extending the `oracle.j2ee.connector.AbstractPrincipalMapping` class, supplied by Oracle for convenience. You must configure a principal mapping class through the `oc4j-ra.xml` file. The following sections describe aspects of using a principal mapping class:

- Understanding the PrincipalMapping Interface APIs

- Extending the AbstractPrincipalMapping Class

- Configuring a Principal Mapping Class

#### Understanding the PrincipalMapping Interface APIs

Table 16-2 describes how OC4J uses methods of the `PrincipalMapping` interface.

Table 16-2 Method Descriptions for PrincipalMapping Interface

Method Signature | Use by OC4J
--- | ---
void init (java.util.Properties prop) | OC4J calls `init()` to initialize the settings for the `PrincipalMapping` instance, passing in property values specified under the `<principal-mapping-interface>` element in `oc4j-ra.xml`. (See "Configuring a Principal Mapping Class".) The implementation class can use the properties to set either a default user name and password, information for LDAP connection, or a default mapping.
void setManagedConnectionFactory (ManagedConnectionFactory mcf) | OC4J calls `setManagedConnectionFactory()` to provide the `PrincipalMapping` instance with a `ManagedConnectionFactory` instance (for connections to the EIS), which is used in creating a `PasswordCredential` instance.
void setAuthenticationMechanisms (java.util.Map authMechanisms) | OC4J calls `setAuthenticationMechanisms()` to pass the authentication mechanisms supported by the resource adapter to the `PrincipalMapping` instance. The key in the map that is passed is a string containing the supported mechanism type, such as `"BasicPassword"` or `"Kerbv5"`. The value corresponding to the key is a string containing the fully qualified name of the corresponding credentials interface, as declared in a `<credential-interface>` element in `ra.xml`, such as for the `PasswordCredential` interface. The map can contain multiple entries if the resource adapter supports multiple authentication mechanisms.
Subject mapping (Subject initiatingSubject) | OC4J calls `mapping()` to instruct the `PrincipalMapping` instance to perform the principal mapping. A `Subject` instance for the OC4J user (initiating principal) is passed in, and this method returns a `Subject` instance for the resource principal, for use by the resource adapter for sign-on to the EIS. (The implementation may return `null` if the proper resource principal cannot be determined.)

#### Extending the AbstractPrincipalMapping Class

As a convenience, OC4J provides the abstract class `AbstractPrincipalMapping`, which implements the `PrincipalMapping` interface. This class provides default implementations of the `setManagedConnectionFactory()` and `setAuthenticationMechanism()` methods, as well as utility methods to accomplish the following:

- Retrieve the managed connection factory used for connections to the EIS.

- Retrieve the authentication mechanisms supported by the resource adapter.

- Determine whether the resource adapter supports the basic password authentication mechanism.

- Determine whether the resource adapter supports the Kerberos version 5 authentication mechanism.

- Extract a `Principal` instance from a `Subject` instance.

When extending the `AbstractPrincipalMapping` class, developers need only implement the `init()` and `mapping()` methods.

The methods exposed by the `AbstractPrincipalMapping` class are summarized in Table 16-3.

Table 16-3 Method Descriptions for AbstractPrincipalMapping Class

Method Signature | Description
--- | ---
abstract void init (java.util.Properties prop) | The subclass must implement the `init()` method. See Table 16-2 for a description.
void setManagedConnectionFactory (ManagedConnectionFactory mcf) | The subclass need not implement the `setManagedConnectionFactory()` method. See Table 16-2 for a description.
void setAuthenticationMechanisms (java.util.Map authMechanisms) | The subclass need not implement the `setAuthenticationMechanisms()` method. See Table 16-2 for a description. Note that the subclass can use the `isBasicPasswordSupported()` and `isKerbv5Supported()` methods (described later in this table) to determine which authentication mechanism is supported by the resource adapter. The subclass can also use the `getAuthenticationMechanisms()` method to retrieve the authentication mechanisms.
abstract Subject mapping (Subject initiatingSubject) | The subclass must implement the `mapping()` method. See Table 16-2 for a description.
ManagedConnectionFactory getManagedConnectionFactory () | The `getManagedConnectionFactory()` utility method returns the `ManagedConnectionFactory` instance (for connections to the EIS), which might be required to create a `PasswordCredential` instance.
java.util.Map getAuthenticationMechanisms () | The `getAuthenticationMechanisms()` utility method returns a map of all authentication mechanisms supported by the resource adapter. See `setManagedConnectionFactory()` in Table 16-2 for a description of the map.
boolean isBasicPasswordSupported () | The `isBasicPasswordSupported()` utility method determines whether the basic password authentication mechanism is supported by the resource adapter.
boolean isKerbv5Supported () | The `isKerbv5Supported()` utility method determines whether the Kerbv5 authentication mechanism is supported by the resource adapter.
Principal getPrincipal (Subject) | The `getPrincipal()` utility method extracts the `Principal` instance from the OC4J user `Subject` instance passed from OC4J. Note: In cases where there are multiple principals in a subject (which is not typical), this method would retrieve the first principal. (There is also a `getPrincipals()` method, and the "first" principal is the first element of the collection of principals that this method would return.)

Example 16-1 extends the `AbstractPrincipalMapping` class to provide a principal mapping from the OC4J user to the EIS default user and password. This assumes a default user and password are specified under the `<principal-mapping-interface>` element in `oc4j-ra.xml`, as shown in "Configuring a Principal Mapping Class".

Example 16-1 Extending AbstractPrincipalMapping

    package com.example.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 is for 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 incoming Subject
        // (security context), corresponding to the OC4J user.
        // This code is included here only as an example.
        // The principal obtained is not actually used in this example.
        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, as in "Option A" in the
        // J2EE Connector Architecture specification.
        PasswordCredential cred =
          new PasswordCredential(m_defaultUser, resPasswordArray);
        cred.setManagedConnectionFactory(getManagedConnectionFactory());
        initiatingSubject.getPrivateCredentials().add(cred);
        return initiatingSubject;
      }
    }

#### Configuring a Principal Mapping Class

To use a principal mapping class, you must update `oc4j-ra.xml` to include a `<principal-mapping-interface>` element for the class. This is a subelement of the `<security-config>` element and must include the following:

- An `<impl-class>` subelement to specify the fully qualified name of the principal mapping class.

- Property settings appropriate to the principal mapping class implementation. For the class shown in the preceding section, there would be a `<property>` subelement with `name="user"` and a `value` setting to specify the default user name for EIS sign-on, and a `<property>` subelement with `name="password"` and a `value` setting to specify the password for the default user, as shown in the following example.

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

Note: You can use password indirection to hide the password. For a full discussion of password indirection, see "Guidelines for Password Management".

### Using a JAAS Login Module for an EIS Connection

Alternatively, you can manage sign-on to an EIS programmatically through JAAS.

See Also: Chapter 8, "Login Modules"

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 (for caller impersonation)

The JAAS login modules can be furnished by the customer, the EIS vendor, or the resource adapter vendor. Login modules implement the `javax.security.auth.spi.LoginModule` interface.

OC4J provides initiating user subjects to login modules by passing an instance of the `javax.security.auth.Subject` class containing any public certificates and an instance of `oracle.j2ee.connector.InitiatingPrincipal` representing the OC4J user. OC4J can pass a null subject if there is no authenticated user (that is, an anonymous user). The login method of the JAAS login module 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` instance 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` instance is passed, the JAAS login module is responsible for creating a new `Subject` instance containing the resource principal and the appropriate credential.

#### The InitiatingPrincipal and InitiatingGroup Classes

The `oracle.j2ee.connector.InitiatingPrincipal` class represents OC4J users to a JAAS login module. OC4J creates instances of `InitiatingPrincipal` and incorporates them into the subject that is passed to the `initialize()` method of a login module. The `InitiatingPrincipal` class implements the `java.security.Principal` interface and adds the method `getGroups()`.

The `oracle.j2ee.connector.InitiatingGroup` class also implements the `Principal` interface, but represents OC4J roles. OC4J creates an `InitiatingPrincipal` instance and incorporates it into the subject that is passed either to the `initialize()` method of a login module, or to the `mapping()` method of a principal mapping class. The `InitiatingPrincipal` class also has a `getGroups()` method.

The `getGroups()` method returns a set (`java.util.Set` instance) of `InitiatingGroup` objects, representing the OC4J roles or OracleAS JAAS Provider roles for this OC4J user. The role membership is defined in an OC4J-specific descriptor file, typically `system-jazn-data.xml`.

Login modules can use `getGroups()` to provide mappings between OC4J roles and EIS users. The `Principal` interface methods support mappings between OC4J users and EIS users. Login modules are not required to refer to the `InitiatingPrincipal` and `InitiatingGroup` classes if they do not provide mappings between OC4J roles and EIS users.

#### JAAS and the <connector-factory> Element

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 a JAAS login module 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/myservice" />
        <security-config>
          <jaas-module>
            <jaas-application-name>JAASModuleDemo</jaas-application-name>
          </jaas-module>
        </security-config>
      </connector-factory>

With JAAS, you must specify which login module to use for a particular application, and in what order to invoke the login modules. JAAS uses values specified in `<jaas-application-name>` elements to look up login modules.