The target audience for this guide is the Enterprise Bean provider, i.e. the person in charge of developing the software components on the server side. It explains how security behavior should be defined.
The content of this guide is the following:
The EJB architecture encourages the Bean programmer to implement the enterprise bean class without hard-coding the security policies and mechanisms into the business methods.
The application assembler can define a security view of the
enterprise beans contained in the ejb-jar file.
The security view consists of a set of security roles. A security
role is a semantic grouping of permissions for a given type of application
user that allows that user to successfully use the application.
The application assembler can define (declaratively in the deployment
descriptor) method permissions for each security role. A method
permission is a permission to invoke a specified group of methods for the
enterprise beans' home and remote interfaces.
The security roles defined by the application assembler present this
simplified security view of the enterprise beans application to the deployer;
the deployer's view of security requirements for the application is the small
set of security roles, rather than a large number of individual methods.
The application assembler can define one or more security roles in the deployment descriptor. The application assembler then assigns groups of methods of the enterprise beans' home and remote interfaces to the security roles in order to define the security view of the application.
The scope of the security roles defined in the security-role
elements is the ejb-jar file level, and this includes all the enterprise
beans in the ejb-jar file.
...
<assembly-descriptor>
<security-role>
<role-name>tomcat</role-name>
</security-role>
...
</assembly-descriptor>
After defining security roles for the enterprise beans in the ejb-jar file, the application assembler can also specify the methods of the remote and home interfaces that each security role is allowed to invoke.
Method permissions are defined as a binary relationship in the deployment
descriptor from the set of security roles to the set of methods of the home
and remote interfaces of the enterprise beans, including all their super
interfaces (including the methods of the javax.ejb.EJBHome and
javax.ejb.EJBObject interfaces). The method permissions
relationship includes the pair (R, M) only if the security role
R is allowed to invoke the method M.
The application assembler defines the method permissions relationship in
the deployment descriptor using the method-permission element as
follows:
method-permission element includes a list of one or
more security roles and a list of one or more methods. All the listed
security roles are allowed to invoke all the listed methods. Each
security role in the list is identified by the role-name
element, and each method is identified by the method
element.method-permission elements.method-permission elements.It is possible that some methods are not assigned to any security roles. This means that these methods can be accessed by anyone.
The following example illustrates how security roles are assigned to methods' permissions in the deployment descriptor:
...
<method-permission>
<role-name>tomcat</role-name>
<method>
<ejb-name>Op</ejb-name>
<method-name>*</method-name>
</method>
</method-permission>
...
Because not all security policies can be expressed declaratively, the EJB architecture also provides a simple programmatic interface that the Bean programmer can use to access the security context from the business methods.
The javax.ejb.EJBContext interface provides two methods that
allow the Bean programmer 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 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 access 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 main purpose of the isCallerInRole(String roleName)
method is to allow the Bean programmer 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 or not. Security roles are defined by the
application assembler in the deployment descriptor and are assigned to
principals by the deployer.
The Bean programmer must declare 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 actual security roles defined for an
assembled application through the security-role elements.
...
<enterprise-beans>
...
<session>
<ejb-nameOp</ejb-name>
<ejb-class>sb.OpBean</ejb-class>
...
<security-role-ref>
<role-name>role1</role-name>
</security-role-ref>
...
</session>
...
</enterprise-beans>
...
The deployment descriptor in this example indicates that the enterprise
bean Op makes the security checks using
isCallerInRole("role1") in at least one of its business
methods.
If the security-role elements have been defined in the
deployment descriptor, all the security role references declared in the
security-role-ref elements must be linked to the security roles
defined in the security-role elements.
The following deployment descriptor example shows how to link the security
role references named role1 to the security role named
tomcat.
...
<enterprise-beans>
...
<session>
<ejb-name>Op</ejb-name>
<ejb-class>sb.OpBean</ejb-class>
...
<security-role-ref>
<role-name>role1</role-name>
<role-link>tomcat</role-link>
</security-role-ref>
...
</session>
...
</enterprise-beans>
...
In summary, the role names used in the EJB code (in the isCallerInRole
method) are, in fact, references to actual security roles, which makes the
EJB code independent of the security configuration described in the
deployment descriptor. The programmer makes these role references available
to the Bean deployer or application assembler via the
security-role-ref elements included in the session
or entity elements of the deployment descriptor. Then, the Bean
deployer or application assembler must map the security roles defined in the
deployment descriptor to the "specific" roles of the target operational
environment (e.g. groups on Unix systems). However, this last mapping step is
not currently available in JOnAS.