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 may 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 that a given
type of users of the application must have in order 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 of 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 the application's
security requirements 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 security roles defined in the security-role
elements
are scoped to the ejb-jar file level, and apply to all the enterprise
beans in the ejb-jar file.
... <assembly-descriptor> <security-role> <role-name>tomcat</role-name> </security-role> ... </assembly-descriptor>
After the Application Assembler has defined security roles for the enterprise beans in the ejb-jar file, she can also specify the methods of the remote and home interfaces that each security role is allowed to invoke.
Method permissions are defined in the deployment descriptor as a
binary relation 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 relation includes the
pair (R, M) if and only if the security role R is
allowed to invoke the method M.
The application Assembler defines the method permissions relation 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 may 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) ; ... }
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 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.
isCallerInRole(String roleName)
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 has to 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 above indicates that the enterprise bean
Op
makes the security checks
using isCallerInRole("role1")
in at least one of its
business method.
If the Application Assembler has defined the security-role
elements in the deployment descriptor, she has to link all the security
role references declared in the security-role-ref
elements
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> ...
To summarize, 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 by the way of the security-role-ref
elements included in the session
or entity
elements of the deployment descriptor. Then, the bean deployer or
application assembler will have to 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 is not currently available in JOnAS.