Declarative Security for EJBs

We learned how a bean method can determine whether the user associated with the calling program has a particular role or not by invoking the method isCallerInRole(String roleName) on the javax.ejb.EJBContext object. The bean gets reference to EJBContext object when the container calls the method setSessionContext() of the bean during initialization, passing the reference as the method argument.

Note that it is the bean provider who selects this role name and associates certain implicit privileges by taking actions based on the role of the caller. This is done at the individual bean level and not at the application level. An application may use beans from many different sources and may need to have different role names defined at the application level, with their own semantics. This aspect of the application assembly is known as the security view and is designed by the application assembler. However, to be able to do this, the application assembler must know the different role names that are used within the different beans and be able to map these names to the role names of the application security view.

The deployment descriptor of an EJB application allows specification of different role names used by a bean within the section devoted to describing that bean. It also allows this role name to be linked or mapped with a role name defined by the application assembler at the application level. This is how two different role names used in two different beans could be linked to a single application-level role.

We talked about checking whether the caller belongs to a particular role or not. This assumes the fact that the caller code is perhaps running on behalf of a particular user. If so, on whose behalf does the called bean method run?

EJB technology allows the called method to run either with the identity of the user associated with the caller, propagating the security context, or on behalf of a role specified in the descriptor, delegating the security context. There are times when delegation of security context makes sense. For example, a Web application with thousands of users may want to map all the users to a handful of database users. In this case, the bean methods accessing the database would run under the delegated identity and not under the identity of the users who logged in to the Web application and are running the servlets that call the bean methods.

Let us talk about the specific elements of the deployment descriptor responsible for this behavior. The element security-role-ref within the session and entity elements of the deployment descriptor is used to indicate what role names are used within the code of a particular bean to check whether the caller identity belongs to a role or not. Similarly, the element security-identity determines whether a particular bean runs with the identity of a caller or a role specified within this element. The element security-identity can occur in the descriptor of any of the three types of beans: session, entity and message-driven, whereas the element security-role-ref can occur only within a session or entity bean descriptor. This is understandable as the only method onMessage() of a message-driven bean gets called on receipt of a message and has no caller associated with this invocation. So, method isCallerInRole() wouldn't make sense within a message driven bean.

The structure of these elements and their positional relationship with other children of session or entity elements is shown below, using a simplified regular expression like notation. In this notation (X)* means zero or more occurrence of X and (X)? implies that X is optional:

...
(<ejb-local-ref> ... </ejb-local-ref>)*
(<security-role-ref>
  (<description>descriptive text</description>)?
  <role-name> bean_rolename </role-name>
  (<role-link>application_rolename</role-link>)?
</security-role-ref>)*
(<security-identity>
  (<description>descriptive text</description>)?
  (<use-caller-identity/>|
    (<run-as>
      (<description>descriptive text</description>)?
      <role-name>role</role-name>
    </run-as>))
</security-identity>)?
(<resource-ref> ... </resource-ref>)*
...

An application assembler would typically place additional descriptor elements within assembly-descriptor element. The structure of this element is shown below:

<assembly-descriptor>
  (<security-role>
    (<description>descriptive text</description>)?
    <role-name>rolename</role-name>
  </security-role>)*
  (<method-permission>
    (<description>descriptive text</description>)?
    ((<role-name>role</role-name>)+ | <unchecked/>)
    (<method>
      (<description>descriptive text</description>)?
      <ejb-name>ejbname</ejb-name>
      (<method-intf>method_interface</method-intf>)?
      <method-name>method_name</method-name>
      (<method-params>
        (<method-param>param_type</method-param>)*
      </method-params>)?
    </method>)+
  <method-permission>)*
  (<container-transaction> ... </container-transaction>)*
  (<exclude-list>
    (<description>descriptive text</description>)?
    (<method> ... </method>)+
  <exclude-list>)?
</assembly-descriptor>

Let us go over each of the children of the assembly-descriptor:

• security-role: There must be a security-role element corresponding to each role in the security view of the application. A role name used within role-link element of the element security-role-ref or run-as must be specified within a security-role element. It is important to keep in mind that the name specified here is just a string and need not map directly to a user or a user group within any particular environment. In fact, it is the deployer's job to map an application role to user names or user group names in an environment-dependent manner.

• method-permission: This element specifies the access rules for one or more beans. An access rule could imply access to a particular role (if the role-name is specified) or no access control (if <unchecked/> is specified). The bean itself is identified by the name assigned to the bean in the bean descriptor through ejb-name element and is most likely different from the name of the beans' implementation class. Optional element method-intf can take one of the following text values: Home, Remote, LocalHome or Local; and it can be used to differentiate among methods with the same signature that are defined in both the home and component interfaces. The method-name itself could be *, implying all methods of the bean, or the name of a specific method. If the method is overloaded and there exists more than one method with the same name but different signatures, types of the method parameters can be used to uniquely identify a method. The fully qualified Java type names, such as java.lang.String, are specified as a value of method-param elements.

• container-transaction: This element specifies transactional properties of the application. It is not related to security aspects, and hence is not covered here.

• exclude-list: This element is used to disallow access of certain bean methods to everyone. The specification of beans and their methods is done in the same way as in the method-permission element.

With this background, we are ready to see the declarative security concepts in action.