Sun Microsystems Inc.

20.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 2 on page 68, Table 3 on page 78, Table 4 on page 151, and Table 7 on page 229 . 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 were deprecated in EJB 1.1. The Bean Provider must use the getCallerPrincipal() and isCallerInRole(String roleName) methods for new enterprise beans.

An EJB 2.0 or 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.

Sun Microsystems Inc

•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());

}

20.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.

Note that getCallerPrincipal() returns the principal that represents the caller of the enterprise bean, not the principal that corresponds to the runAs security identity for the bean, if any.

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 mapping 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 userid 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 EJB specification.

Sun Microsystems Inc.

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).

20.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 Subsection 20.3.1), and are assigned to principals or principal groups that exist in the operational environment by the Deployer.

Sun Microsystems Inc

Note that isCallerInRole(String roleName) tests the principal that represents the caller of the enterprise bean, not the principal that corresponds to the runAs security identity for the bean, if any.

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

}

...

}

...

}

20.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 secu- rity-role elements.

The Bean Provider must declare each security role referenced in the code using the secu- rity-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.