| Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
| Oracle® Containers for J2EE Security Guide 10g (10.1.3.5.0) Part Number E13977-01 |
|
|
View PDF |
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:
See Also:
Oracle Containers for J2EE Resource Adapter Administrator's Guide for general information about resource adapters and the J2EE Connector Architecture
To ensure secure interactions between a J2EE application and an EIS, the J2EE Connector Architecture allows application components to associate a JAAS subject 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:
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 subject directly from a J2EE component to a resource adapter (for component-managed sign-on)
Propagating a 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 subject that differs from the subject with which the managed connection was initially created.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 a<res-auth> setting of Application in web.xml or ejb-jar.xml. Setup for sign-on is programmatic. There is no OC4J-specific configuration.
Container-managed sign-on: Requires a <res-auth> setting of Container in web.xml or ejb-jar.xml. 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 the <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 also described in "Using Declarative Container-Managed Sign-On"); reflected as use="principal-mapping-entries" with appropriate subelements under the <security-config> element.
Programmatic, using either a principal mapping class or a JAAS login module:
Principal mapping class: Implement the 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 under the <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 under the <security-config> element.
Choices for container-managed sign-on in OC4J are also illustrated in Figure 20-1 that follows.
Figure 20-1 Flow Chart of Choices for OC4J Container-Managed Sign-On
This section discusses the following key resource adapter configuration elements for security:
See Also:
Oracle Containers for J2EE Resource Adapter Administrator's Guide for additional information about the files and elements discussed here
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:
<principal-mapping-entries> element, specifying user names and passwords explicitly
<principal-mapping-interface> element, specifying the name of the mapping class
<jaas-module> element, specifying the JAAS module to be used for authentication
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>
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 20-2 shows the steps in component-managed sign-on, with the text that follows providing further detail.
The client makes a request, which is associated with an incoming subject (security context) for the initiating principal.
As part of servicing the request, the application component maps the incoming subject to an outgoing subject for the resource principal, or hard-codes an outgoing subject, then uses the outgoing subject to request a connection to the EIS.
As part of the connection acquisition, the resource adapter signs on to the EIS using the outgoing subject provided by the application component.
Once the connection is acquired, the application component can interact with the EIS under the established outgoing subject.
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);
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 subject and to perform authentication.
Figure 20-3 following illustrates the steps in container-managed sign-on. These steps are detailed following the diagram.
The client makes a request, which is associated with an incoming subject (security context) for the initiating principal.
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 the figure) maps the incoming subject to the outgoing subject for the resource principal. This is based on principal mapping entry elements, a principal mapping class, or a JAAS login module.
The resource adapter logs in to the EIS using the outgoing subject provided by OC4J.
Once the connection is acquired, the application component can interact with the EIS under the established outgoing subject.
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();
When you use 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.
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.
Notes:
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.
From the Connection Factories tab of the appropriate Resource Adapter page, choose the connection factory you want to edit. Connection factories are listed by JNDI location.
In the Edit Connection Factory page, go to the Security tab.
Choose to enable security for container-managed sign-on.
Specify declarative principal mappings. This is to specify the default resource user.
Specify the default resource user name.
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).
See Also:
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:
Specify the initiating user, which is the user name of an initiating principal.
Specify the resource user, which is the user name for a corresponding resource principal.
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.
Choose Apply to apply the changes.
Table 20-1 following summarizes how these settings correspond to XML entities in the oc4j-ra.xml file. An example follows the table.
Table 20-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 |
Being enabled corresponds to |
|
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 an OracleAS JAAS Provider default realm, as discussed in "Default Realm with the File-Based Provider or Oracle Identity Management". If you supply a simple user name, that name must be a member of the default realm.
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:
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:
Table 20-2 following describes how OC4J uses methods of the PrincipalMapping interface.
Table 20-2 Method Descriptions for PrincipalMapping Interface
| Method Signature | Use by OC4J |
|---|---|
|
void init(java.util.Properties prop) |
OC4J calls |
|
void setManagedConnectionFactory (ManagedConnectionFactory mcf) |
OC4J calls |
|
void setAuthenticationMechanisms (java.util.Map authMechanisms) |
OC4J calls |
|
Subject mapping(Subject initiatingSubject) |
OC4J calls |
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 20-3 that follows.
Table 20-3 Method Descriptions for AbstractPrincipalMapping Class
| Method Signature | Description |
|---|---|
|
abstract void init (java.util.Properties prop) |
The subclass must implement the |
|
void setManagedConnectionFactory (ManagedConnectionFactory mcf) |
The subclass need not implement the |
|
void setAuthenticationMechanisms (java.util.Map authMechanisms) |
The subclass need not implement the |
|
abstract Subject mapping (Subject initiatingSubject) |
The subclass must implement the |
|
ManagedConnectionFactory getManagedConnectionFactory() |
The |
|
java.util.Map getAuthenticationMechanisms() |
The |
|
boolean isBasicPasswordSupported() |
The |
|
boolean isKerbv5Supported() |
The |
|
Principal getPrincipal(Subject) |
The Note: In cases where there are multiple principals in a subject, this method would retrieve the first principal. (There is also a |
Example 20-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 20-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;
}
}
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, as discussed in "Using Password Indirection".Alternatively, you can manage sign-on to an EIS programmatically through JAAS.
See Also:
OC4J furnishes a JAAS pluggable authentication framework that conforms to the Connector Architecture 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 types of JAAS login modules:
Principal mapping login module
Credential mapping login module
Kerberos login module (for caller impersonation)
The 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 (essentially, if there is an anonymous user). The login method of the 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 login module is responsible for creating a new Subject instance containing the resource principal and the appropriate credential.
The oracle.j2ee.connector.InitiatingPrincipal class represents OC4J users to a 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.
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 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.
|
 Copyright © 2003, 2009, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|