|
Oracle® Application Server Containers for J2EE Security Guide
10g Release 2 (10.1.2) Part No. B14013-01 |
|
 Previous |
 Next |
|
Oracle® Application Server Containers for J2EE Security Guide
10g Release 2 (10.1.2) Part No. B14013-01 |
|
|
Previous |
Next |
This chapter describes the security issues affecting the J2EE Connector Architecture in an Oracle Application Server Containers for J2EE (OC4J) application. For full information on the J2EE Connector Architecture, see the Oracle Application Server Containers for J2EE Services Guide. This chapter covers the following topics:
This section discusses deployment descriptors, deploying standalone resource adapters, and deploying embedded resource adapters.
Oracle Application Server Containers for J2EE supports three deployment descriptors: ra.xml, oc4j-ra.xml, and oc4j-connectors.xml. The ra.xml descriptor is normally supplied with the resource adapter. Whenever you deploy a resource adapter within an EAR file, Oracle Application Server Containers for J2EE generates oc4j-connectors.xml and oc4j-ra.xml. You should manually edit the second file.
The oc4j-ra.xml descriptor provides Oracle Application Server Containers for J2EE-specific deployment information (Java Naming and Directory Interface (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. Oracle Application Server Containers for J2EE 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:
Specifying mapping sub-elements explicitly (in the <principal-mapping-entries> sub-element)
Specifying 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> sub-element)
Authentication issues are discussed in detail in "Authentication in Container-Managed Sign-On". This section discusses only the syntax for the <security-config> element.
A <security-config> element contains either a <principal-mapping-entries> element, specifying user names and passwords explicitly; a <principal-mapping-interface> element, specifying the name of the mapping class; or a <jaas-module> element, specifying the JAAS module to be used for authentication.
<security-config>
<principal-mapping-entries> // 1
<default-mapping> // 2
<res-user>username</res-user> // 3
<res-password>password</res-password> // 4
</default-mapping>
<principal-mapping-entry> // 5
<initiating-user>iuname</initiating-user> // 6
<res-user>username</res-user>
<res-password>password</res-password>
</principal-mapping-entry>
</principal-mapping-entries>
<principal-mapping-interface> // 7
<impl-class>classname</impl-class> // 8
<property name="propname"
value="propvalue" /> // 9
</principal-mapping-interface>
<jaas-module> // 10
<jaas-application-name> // 11
appname
</jaas-application-name>
</jaas-module>
</security-config>
<principal-mapping-entries>:
Provides a declarative specification for resource mapping. This element begins with an optional <default-mapping> element; it continues with one or more <principal-mapping-entry> elements.
<default-mapping>: specifies the user name and password for the default resource principal.
<res-user>: specifies user name.
<res-password>: specifies password.
|
Note: This element supports password indirection. For more information, refer to "Creating An Indirect Password" . |
<principal-mapping-entry>: specifies a mapping from a single initiating principal to a resource principal and password.
<initiating-user>: specifies the initiating principal.
<principal-mapping-interface>: specifies information necessary to employ user-created classes to provide mappings.
<impl-class>: specifies the name of the user-provided PrincipalMapping implementation.
<property name="propname" value="propvalue">: specifies information specific to your PrincipalMapping implementation: for instance, the path of the principal mapping file, or LDAP server connection information. (This element is optional and it can be repeated.)
<jaas-module>: specifies the JAAS module that is used for authentication. It has only one element, <jaas-application-name>.
<jaas-application-name>: specifies the name of the JAAS module that is used for authentication.
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 Oracle Application Server Containers for J2EE instance, as well as the resource adapters that are embedded within an application. 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> contains a <security-permission-spec> that conforms to the Java 2 Security policy file syntax.
Oracle Application Server Containers for J2EE 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>
Applications can use either application components or the Oracle Application Server Containers for J2EE application server to manage resource-adapter sign-on to the EIS system. Specify the manager using the <res-auth> deployment descriptor element for EJB or Web components. If <res-auth> is set to Application, then the application component signs on to the EIS programmatically. The application component is responsible for providing explicit security information for the sign-on. If <res-auth> is set to Container, then Oracle Application Server Containers for J2EE provides the resource principal and credentials that are required for signing on to the EIS.
Example:
Context initctx = new InitialContext();
// perform JNDI lookup to obtain a connection factory
javax.resource.cci.ConnectionFactory cxf =
(javax.resource.cci.ConnectionFactory)initctx.lookup("java:com/env/eis/MyEIS");
// For container-managed sign-on, no security information is passed in the getConnection call
javax.resource.cci.Connection cx = cxf.getConnection();
// If component-managed sign-on is specified, the code should instead provide explicit security
// information in the getConnection call
// We need to get a new ConnectionSpec implementation instance for setting login
// attributes
com.myeis.ConnectionSpecImpl connSpec = ...
connSpec.setUserName("EISuser");
connSpec.setPassword("EISpassword");
javax.resource.cci.Connection cx = cxf.getConnection(connSpec);
In either case, the createManagedConnection method in the resource adapter's implementation of javax.resource.spi.ManagedConnectionFactory interface is called to create a physical connection to the EIS.
If you specify component-managed sign-on, then Oracle Application Server Containers for J2EE invokes the createManagedConnection method with a null Subject and the ConnectionRequestInfo object that is passed in from the application component code. If you specify container-managed sign-on, then Oracle Application Server Containers for J2EE provides a javax.security.auth.Subject object to the createManagedConnection method. The content of the Subject object depends on the value in the <authentication-mechanism-type> and <credential-interface> elements in the resource adapter deployment descriptor.
If <authentication-mechanism-type> is BasicPassword and <credential-interface> is javax.resource.spi.security.PasswordCredential, then the Subject object must contain javax.resource.spi.security.PasswordCredential objects in the private credential set.
On the other hand, if <authentication-mechanism-type> is Kerberos version 5 (Kerbv5) or any other non-password-based authentication mechanism, and <credential-interface> is javax.resource.spi.security.GenericCredential, then the Subject object must contain credentials represented by instances of implementers of the javax.resource.spi.security.GenericCredential interface. The GenericCredential interface is used for resource adapters that support non-password-based authentication mechanisms, such as Kerberos.
When using container-managed sign-on, Oracle Application Server Containers for J2EE 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's 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 Oracle Application Server Containers for J2EE 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.
Oracle Application Server Containers for J2EE supports all these methods with three authentication mechanisms:
The following sections discuss these mechanisms in detail.
Oracle Application Server Containers for J2EE 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 vendors, or the resource adapter vendors. Login modules must implement the javax.security.auth.spi.LoginModule interface, as documented in the Sun JAAS specification.
Oracle Application Server Containers for J2EE provides initiating user subjects to login modules by passing an instance of javax.security.auth.Subject containing any public certificates and an instance of oracle.j2ee.connector.InitiatingPrincipal representing the Oracle Application Server Containers for J2EE user. Oracle Application Server Containers for J2EE can pass a null Subject if there is no authenticated user (that is, an anonymous user). The JAAS login module's login method must, based on the initiating user, find the corresponding resource principal and create new PasswordCredential or GenericCredential instances for the resource principal. The resource principal and credential objects are then added to the initiating Subject in the commit method. The resource credential is passed to the createManagedConnection method in the javax.resource.spi.ManagedConnectionFactory implementation 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.
The classes oracle.j2ee.connector.InitiatingPrincipal and oracle.j2ee.connector.InitiatingGroup represent Oracle Application Server Containers for J2EE users to the JAAS login modules. Oracle Application Server Containers for J2EE creates instances of oracle.j2ee.connector.InitiatingPrincipal and incorporates them into the Subject that is passed to the initialize method of the login modules. The oracle.j2ee.connector.InitiatingPrincipal class implements the java.security.Principal interface and adds the method getGroups().
/** * Returns a Set of groups (or roles in JAZN terminology) that this * principal is a member of. * * @return A set of InitiatingGroup objects representing the groups * that this pricipal belongs to. */ public Set getGroups()
The getGroups method returns a java.util.Set of oracle.j2ee.connector.InitiatingGroup objects, representing the Oracle Application Server Containers for J2EE groups or JAZN roles for this Oracle Application Server Containers for J2EE user. The group membership is defined in Oracle Application Server Containers for J2EE-specific descriptor files such as principals.xml or jazn-data.xml, depending on the user manager. The oracle.j2ee.connector.InitiatingGroup class implements but does not extend the java.security.Principal interface.
Login modules can use getGroups() to provide mappings between Oracle Application Server Containers for J2EE groups and EIS users. The java.security.Principal interface methods support mappings between Oracle Application Server Containers for J2EE users and EIS users. Login modules do not need to refer to the oracle.j2ee.connector.InitiatingPrincipal and oracle.j2ee.connector.InitiatingGroup classes if they do not provide mappings between Oracle Application Server Containers for J2EE groups 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 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.
Oracle Application Server Containers for J2EE provides the oracle.j2ee.connector.PrincipalMapping interface for principal mapping.
package oracle.j2ee.connector;
public interface PrincipalMapping
{
/**
* Initializes the various settings for the PrincipalMapping implementation class.
* Implementation class may use the properties for setting default user name and
* password, LDAP connect info, or default mapping.
*
* OC4J will pass the properties specified in the <principal-mapping-interface>
* element in oc4j-ra.xml to this method.
*
* @param prop A Properties object containing the set up information required
* by the implementation class.
*/
public void init(Properties prop);
/**
* The ManagedConnectionFactory instance that can be used in creating a
* PasswordCredential.
*
* @param mcf The ManagedConnectionFactory instance that is needed when
*creating a PasswordCredential instance
*/
public void setManagedConnectionFactory(ManagedConnectionFactory mcf);
/**
* Passes the authentication mechanism(s) supported by the resource
* adapter to the PrincipalMapping implementation class.
* The key of the map passed is a String containing the supported mechanism
* type, such as "BasicPassword", or "Kerbv5". The value is a String
* containig the corresponding credentials interface as declared in ra.xml,
* such as "javax.resource.spi.security.PasswordCredential".
*
* The map may contain multiple elements if the resource adatper supports
* multiple authentication mechanisms.
*
* @param authMechanisms The authentication mechanisms and their corresponding
* credentials intereface supported by the resource adapter
*/
public void setAuthenticationMechanisms(Map authMechanisms);
/**
* This is the method that performs the principal mapping. An application user
* subject is passed, and the implemetation of this method should return
* a subject for use by the resource adapter to log in to the EIS resource
* according to the Connector specifications.
*
* OC4J will only called this method for container-managed sign on.
*
* @param initiatingSubject A Subject containing the application server logged
* in principals and public credentials.
*
* @return A Subject for use by resource adapter to log in to the remote EIS.
* It may return null if the proper resource principal cannot be determined.
*/
public Subject mapping(Subject initiatingSubject);
}
The mapping method must return a Subject containing the resource principal and credential. The Subject that is returned must adhere to either option A or option B in section 8.2.6 of the Connector Architecture 1.0 specification. Oracle Application Server Containers for J2EE invokes the mapping method with the initiating user as the initiatingPrincipal.
Oracle Application Server Containers for J2EE 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 methods, and a method for extracting the Principal from the application server user Subject. By extending the oracle.j2ee.connector.AbstractPrincipalMapping class, developers need only implement the init and mapping methods.
Here are the utility methods provided by the oracle.j2ee.connector.AbstractPrincipalMapping class:
/**
* Utility method provided by this abstract class to return
* the ManagedConnectionFactory instance for use to create a
* PasswordCredentials object
*
* @return The ManagedConnectionFactory instance that is needed when
* creating a PasswordCredential instance
*/
public ManagedConnectionFactory getManagedConnectionFactory()
/**
* Utility method provided by this abstract class to return the Map
* of all authentication mechanisms supported by this resource adapter.
* The key of the map passed is a String containing the supported mechanism
* type, such as "BasicPassword", or "Kerbv5". The value is a String
* containig the corresponding credentials interface as declared in ra.xml,
* such as "javax.resource.spi.security.PasswordCredential".
*
* @return The authentication mechanisms and their corresponding
* credentials intereface supported by the resource adpater
*/
public Map getAuthenticationMechanisms()
/**
* Utility method provided by this abstract class to return whether
* BasicPassword authention mechanism is supported by this resource
* adapter.
*
* @return true if BasicPassword authentication mechanism is supported
* by the resource adapter, false otherwise.
*/
public boolean isBasicPasswordSupported()
/**
* Utility method provided by this abstract class to return whether
* Kerbv5 authention mechanism is supported by this resource
* adapter.
*
* @return true if Kerbv5 authentication mechanism is supported
* by the resource adapter, false otherwise.
*/
public boolean isKerbv5Supported()
/**
* Utility method provided by this abstract class to extract the
* Principal object from the given application server user subject
* passed from OC4J.
*
* @param subject The application server user subject passed from
* OC4J.
*
* @return The principal extracted from the given subject
*/
public Principal getPrincipal(Subject subject)
After you create your implementation class, copy a JAR file containing the class into the directory containing the decompressed RAR file. This directory is typically OC4J_HOME/applications/application_name/rar-name. After copying the file, edit oc4j-ra.xml to contain a <principal-mapping-interface> element for the new class; see "The <security-config> Element" for details.
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 supporst BasicPassword authentication
// mechanism. Return if the resource adapter does not support it.
if (!isBasicPasswordSupported())
return null;
// Use the utility method to retrieve the Principal from the
// OC4J user. This code is included here only as an example.
// The principal obtained is not being used in this method.
Principal principal = getPrincipal(initiatingSubject);
char[] resPasswordArray = null;
if (m_defaultPassword != null)
resPasswordArray = m_defaultPassword.toCharArray();
// Create a PasswordCredential using the default user name and
// password, and add it to the Subject, as in 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;
}
}
You add a <principal-mapping-interface> entry to oc4j-ra.xml that specifies com.acme.app.MyMapping for the principal mapping mechanism:
<connector-factory name="..." location="...">
...
<security-config>
<principal-mapping-interface>
<impl-class>com.acme.app.MyMapping</impl-class>
<property name="user" value="scott" />
<property name="password" value="tiger" />
</principal-mapping-interface>
</security-config>
...
</connector-factory>
If you prefer, you can create default principal mappings in the oc4j-ra.xml file. To employ the default principal mappings mechanism, use the <principal-mapping-entries> sub-element under the <security-config> element. For syntax details, see "The <security-config> Element".
Use the <default-mapping> element to specify the user name and password for the default resource principal. This principal is used to log on to the EIS if there is no <principal-mapping-entry> element whose initiating user corresponds to the current initiating principal. If no default mapping is specified, Oracle Application Server Containers for J2EE uses the values of the configuration properties UserName and Password from the deployment descriptor (either in ra.xml or oc4j-ra.xml), assuming that these defaults are acceptable to the resource adapter. If neither configuration properties nor a default mapping is specified, Oracle Application Server Containers for J2EE may not be able to log in to the EIS.
Each <principal-mapping-entry> element contains a mapping from initiating principal to resource principal and password.
For example, if the Oracle Application Server Containers for J2EE principal scott should be logged in to a certain EIS, myEIS1, as user name scott and password tiger, while all other Oracle Application Server Containers for J2EE 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>
