EJB.15.2 Bean Provider s Responsibilities

EJB.15.2 Bean Provider's Responsibilities

This section defines the bean provider's perspective of the EJB architecture support for security, and defines his responsibilities.

EJB.15.2.1 Invocation of Other Enterprise Beans

An enterprise bean business method can invoke another enterprise bean via the other bean's remote or home interface. The EJB architecture provides neither pro-grammatic nor deployment descriptor interfaces for the invoking enterprise bean to control the principal passed to the invoked enterprise bean.

The management of caller principals passed on enterprise bean invocations (i.e., principal delegation) is set up by the deployer and system administrator in a container-specific way. The bean provider and application assembler should describe all the requirements for the caller's principal management of inter-enterprise bean invocations as part of the description. The default principal management (in the absence of other deployment instructions) is to propagate the caller principal from the caller to the callee. (That is, the called enterprise bean will see the same returned value of the EJBContext.getCallerPrincipal() as the calling enterprise bean.)

EJB.15.2.2 Resource Access

Section EJB.14.4 defines the protocol for accessing resource managers, including the requirements for security management.

EJB.15.2.3 Access of Underlying OS Resources

The EJB architecture does not define the operating system principal under which enterprise bean methods execute. Therefore, the bean provider cannot rely on a specific principal for accessing the underlying OS resources, such as files. (See Section EJB.15.6.8 for the reasons behind this rule.)

We believe that most enterprise business applications store information in resource managers such as relational databases rather than in resources at the operating system levels. Therefore, this rule should not affect the portability of most enterprise beans.

EJB.15.2.4 Programming Style Recommendations

The bean provider should neither implement security mechanisms nor hard-code security policies in the enterprise beans' business methods. Rather, the bean provider should rely on the security mechanisms provided by the EJB container, and should let the application assembler and deployer define the appropriate security policies for the application.

The bean provider and application assembler may use the deployment descriptor to convey security- related information to the deployer. The information helps the deployer to set up the appropriate security policy for the enterprise bean application.

EJB.15.2.5 Programmatic Access to Caller's Security Context

Note

In general, security management should be enforced by the container in a manner that is transparent to the enterprise beans' business methods. The security API described in this section should be used only in the less frequent situations in which the enterprise bean business methods need to access the security context information.

The javax.ejb.EJBContext interface provides two methods (plus two deprecated methods that were defined in EJB 1.0) that allow the bean provider to access security information about the enterprise bean's caller.

 public interface javax.ejb.EJBContext {    ...     //     // The following two methods allow the EJB class     // to access security information.     //     java.security.Principal getCallerPrincipal();     boolean isCallerInRole(String roleName);     //     // The following two EJB 1.0 methods are deprecated.     //     java.security.Identity getCallerIdentity();     boolean isCallerInRole(java.security.Identity role);     ...  } 

The bean provider can invoke the getCallerPrincipal and isCallerInRole methods only in the enterprise bean's business methods for which the container has a client security context, as specified in Table EJB.6-1 on page 406, Table EJB.6-2 on page 417, and Table EJB.9-1 on page 459. If they are invoked when no security context exists, they should throw the java.lang.IllegalStateException runtime exception.

The getCallerIdentity() and isCallerInRole(Identity role) methods are deprecated in EJB 1.1. The bean provider must use the getCallerPrincipal() and isCallerInRole(String roleName) methods for new enterprise beans.

An EJB 1.1 compliant container may choose to implement the two deprecated methods as follows .

• A container that does not want to provide support for this deprecated method should throw a RuntimeException (or subclass of RuntimeException ) from the getCallerIdentity() method.

• A container that wants to provide support for the getCallerIdentity() method should return an instance of a subclass of the java.security.Identity abstract class from the method. The getName() method invoked on the returned object must return the same value that getCallerPrincipal().getName() would return.

• A container that does not want to provide support for this deprecated method should throw a RuntimeException (or subclass of RuntimeException ) from the isCallerInRole(Identity identity) method .

• A container that wants to implement the isCallerInRole(Identity identity) method should implement it as follows:

   public isCallerInRole(Identity identity) {    return isCallerInRole(identity.getName());  } 

EJB.15.2.5.1 Use of getCallerPrincipal()

The purpose of the getCallerPrincipal () method is to allow the enterprise bean methods to obtain the current caller principal's name. The methods might, for example, use the name as a key to information in a database.

An enterprise bean can invoke the getCallerPrincipal() method to obtain a java.security.Principal interface representing the current caller. The enterprise bean can then obtain the distinguished name of the caller principal using the getName() method of the java.security.Principal interface.

The meaning of the current caller , the Java class that implements the java.security.Principal interface, and the realm of the principals returned by the getCallerPrincipal() method depend on the operational environment and the configuration of the application.

An enterprise may have a complex security infrastructure that includes multiple security domains. The security infrastructure may perform one or more mappings of principals on the path from an EJB caller to the EJB object. For example, an employee accessing his company over the Internet may be identified by a user id and password (basic authentication), and the security infrastructure may authenticate the principal and then map the principal to a Kerberos principal that is used on the enterprise's intranet before delivering the method invocation to the EJB object. If the security infrastructure performs principal mapping, the getCallerPrincipal() method returns the principal that is the result of the mapping, not the original caller principal. (In the previous example, getCallerPrincipal() would return the Kerberos principal.) The management of the security infrastructure, such as principal mapping, is performed by the system administrator role; it is beyond the scope of the EJB specification.

The following code sample illustrates the use of the getCallerPrincipal() method.

 public class EmployeeServiceBean implements SessionBean {    EJBContext ejbContext;     public void changePhoneNumber(...) {       ...        // Obtain the default initial JNDI context.        Context initCtx = new InitialContext();        // Look up the home interface of the EmployeeRecord        // enterprise bean in the environment.        Object result = initCtx.lookup(          "java:comp/env/ejb/EmplRecord");        // Convert the result to the proper type.        EmployeeRecordHome emplRecordHome = (EmployeeRecordHome)           javax.rmi.PortableRemoteObject.narrow(result,                  EmployeeRecordHome.class);        // obtain the caller principal.        callerPrincipal = ejbContext.getCallerPrincipal();        // obtain the caller principal's name.        callerKey = callerPrincipal.getName();        // use callerKey as primary key to EmployeeRecord finder        EmployeeRecord myEmployeeRecord =           emplRecordHome.findByPrimaryKey(callerKey);        // update phone number        myEmployeeRecord.changePhoneNumber(...);        ...     }  } 

In the previous example, the enterprise bean obtains the principal name of the current caller and uses it as the primary key to locate an EmployeeRecord entity object. This example assumes that application has been deployed such that the current caller principal contains the primary key used for the identification of employees (e.g., employee number).

EJB.15.2.5.2 Use of isCallerInRole(String roleName)

The main purpose of the isCallerInRole(String roleName) method is to allow the bean provider to code the security checks that cannot be easily defined declaratively in the deployment descriptor using method permissions. Such a check might impose a role-based limit on a request, or it might depend on information stored in the database.

The enterprise bean code uses the isCallerInRole(String roleName) method to test whether the current caller has been assigned to a given security role. Security roles are defined by the application assembler in the deployment descriptor (see Section EJB.15.3.1) and are assigned to principals or principal groups that exist in the operational environment by the deployer.

The following code sample illustrates the use of the isCallerInRole(String roleName) method.

 public class PayrollBean ... {    EntityContext ejbContext;     public void updateEmployeeInfo(EmplInfo info) {       oldInfo = ... read from database;        // The salary field can be changed only by caller's        // who have the security role "payroll"        if (info.salary != oldInfo.salary &&           !ejbContext.isCallerInRole("payroll")) {             throw new SecurityException(...);        }        ...     }     ...  } 

EJB.15.2.5.3 Declaration of Security Roles Referenced from the Bean's Code

The bean provider is responsible for declaring in the security-role-ref elements of the deployment descriptor all the security role names used in the enterprise bean code. Declaring the security roles references in the code allows the application assembler or deployer to link the names of the security roles used in the code to the security roles defined for an assembled application through the security-role elements.

The bean provider must declare each security role referenced in the code using the security-role-ref element as follows:

• Declare the name of the security role using the role-name element. The name must be the security role name that is used as a parameter to the isCallerInRole(String roleName) method.

• Optional: Provide a description of the security role in the description element.

A security role reference, including the name defined by the role-name element, is scoped to the session or entity bean element whose declaration contains the security-role-ref element.

The following example illustrates how an enterprise bean's references to security roles are declared in the deployment descriptor.

 ...  <enterprise-beans>     ...     <entity>        <ejb-name>AardvarkPayroll</ejb-name>        <ejb-class>com.aardvark.payroll.PayrollBean</ejb-class>        ...        <security-role-ref>           <description>              This security role should be assigned to the              employees of the payroll department who are              allowed to update employees' salaries.           </description>           <role-name>payroll</role-name>        </security-role-ref>        ...     </entity>     ...  </enterprise-beans>  ... 

The deployment descriptor above indicates that the enterprise bean AardvarkPayroll makes the security check using isCallerInRole( " payroll " ) in its business method.