Securing Enterprise Beans

Securing Enterprise Beans

Enterprise beans are the Java EE components that implement Enterprise JavaBeans (EJB) technology. Enterprise beans run in the EJB container, a runtime environment within the Application Server, as shown in Figure 29-1.

Figure 29-1 Java EE Server and Containers

Although transparent to the application developer, the EJB container provides system-level services such as transactions and security to its enterprise beans. These services enable you to quickly build and deploy enterprise beans, which form the core of transactional Java EE applications.

The following sections describe declarative and programmatic security mechanisms that can be used to protect enterprise bean resources. The protected resources include methods of enterprise beans that are called from application clients, web components, or other enterprise beans. This section assumes that you have read Chapter 20, "Enterprise Beans" and Chapter 21, "Getting Started with Enterprise Beans".

You can protect enterprise beans by doing the following:

Accessing an Enterprise Bean Caller's Security Context

Declaring Security Role Names Referenced from Enterprise Bean Code

Defining a Security View of Enterprise Beans

Using Enterprise Bean Security Annotations

Using Enterprise Bean Security Deployment Descriptor Elements

Configuring IOR Security

Deploying Secure Enterprise Beans

Example: Securing an Enterprise Bean demonstrates adding security to enterprise beans.

You should also read JSR-220: Enterprise JavaBeans 3.0 for more information on this topic. This document can be downloaded from the following URL:
http://jcp.org/en/jsr/detail?id=220. Chapter 16 of this specification, Security Management, discusses security management for enterprise beans.

Accessing an Enterprise Bean Caller's Security Context

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 that allow the bean provider to access security information about the enterprise bean's caller.

java.security.Principal 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.

boolean isCallerInRole(String roleName);

The purpose of the isCallerInRole(String roleName) method is to test whether the current caller has been assigned to a given security role. Security roles are defined by the bean provider or the application assembler, and are assigned to principals or principals groups that exist in the operational environment by the deployer.

The following code sample illustrates the use of the getCallerPrincipal() method:
@Stateless public class EmployeeServiceBean
          implements EmployeeService{
     @Resource SessionContext ctx;
     @PersistenceContext EntityManager em;

     public void changePhoneNumber(...) {
          ...
          // obtain the caller principal.
          callerPrincipal = ctx.getCallerPrincipal();

          // obtain the caller principal's name.
          callerKey = callerPrincipal.getName();

          // use callerKey as primary key to find EmployeeRecord
          EmployeeRecord myEmployeeRecord =
               em.findByPrimaryKey(EmployeeRecord.class, callerKey);

          // update phone number
          myEmployeeRecord.setPhoneNumber(...);

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

The following code sample illustrates the use of the isCallerInRole(String roleName) method:
@DeclareRoles("payroll")
@Stateless public class PayrollBean implements Payroll { 
     @Resource SessionContext ctx; 

     public void updateEmployeeInfo(EmplInfo info) { 

          oldInfo = ... read from database; 

          // The salary field can be changed only by callers 
          // who have the security role "payroll" 
          if (info.salary != oldInfo.salary && 
               !ctx.isCallerInRole("payroll")) { 
                    throw new SecurityException(...); 
          } 
          ... 
     } 
     ... 
} 
Declaring Security Role Names Referenced from Enterprise Bean Code

You can declare security role names used in enterprise bean code using either the @DeclareRoles annotation (preferred) or the security-role-ref elements of the deployment descriptor. Declaring security role names in this way enables you link these security role names used in the code to the security roles defined for an assembled application. In the absence of this linking step, any security role name used in the code will be assumed to correspond to a security role of the same name in the assembled application.

A security role reference, including the name defined by the reference, is scoped to the component whose bean class contains the @DeclareRoles annotation or whose deployment descriptor element contains the security-role-ref deployment descriptor element.

You can also use the security-role-ref elements for those references that were declared in annotations and you want to have linked to a security-role whose name differs from the reference value. If a security role reference is not linked to a security role in this way, the container must map the reference name to the security role of the same name. See Linking Security Role References to Security Roles for a description of how security role references are linked to security roles.

For an example using each of these methods, read the following sections:

Declaring Security Roles Using Annotations

Declaring Security Roles Using Deployment Descriptor Elements

Declaring Security Roles Using Annotations

The @DeclareRoles annotation is specified on a bean class, where it serves to declare roles that can be tested by calling isCallerInRole from within the methods of the annotated class.

You declare the security roles referenced in the code using the @DeclareRoles annotation. When declaring the name of a role used as a parameter to the isCallerInRole(String roleName) method, the declared name must be the same as the parameter value. You can optionally provide a description of the named security roles in the description element of the @DeclareRoles annotation.

The following code snippet demonstrates the use of the @DeclareRoles annotation. In this example, the @DeclareRoles annotation indicates that the enterprise bean AardvarkPayroll makes the security check using isCallerInRole("payroll") to verify that the caller is authorized to change salary data. The security role reference is scoped to the session or entity bean whose declaration contains the @DeclareRoles annotation.
@DeclareRoles("payroll")
@Stateless public class PayrollBean implements Payroll {
     @Resource SessionContext ctx;

     public void updateEmployeeInfo(EmplInfo info) {

          oldInfo = ... read from database;

          // The salary field can be changed only by callers
          // who have the security role "payroll"
          if (info.salary != oldInfo.salary &&
               !ctx.isCallerInRole("payroll")) {
                    throw new SecurityException(...);
          }
          ...
     }
     ...
} 
The syntax for declaring more than one role is as shown in the following example:
@DeclareRoles({"Administrator", "Manager", "Employee"}) 
Declaring Security Roles Using Deployment Descriptor Elements

Note: Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.

If the @DeclareRoles annotation is not used, you can use the security-role-ref elements of the deployment descriptor to declare the security roles referenced in the code, as follows:

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

Optionally provide a description of the security role in the description element.

The following example illustrates how an enterprise bean's references to security roles are declared in the deployment descriptor. In this example, the deployment descriptor indicates that the enterprise bean AardvarkPayroll makes the security check using isCallerInRole("payroll") in its business method. The security role reference is scoped to the session or entity bean whose declaration contains the security-role-ref element.
...
<enterprise-beans>
     ...
     <session>
          <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>
          ...
     </session>
     ...
</enterprise-beans>
... 
Defining a Security View of Enterprise Beans

You can define a security view of the enterprise beans contained in the ejb-jar file and pass this information along to the deployer. When a security view is passed on to the deployer, the deployer uses this information to define method permissions for security roles. If you don't define a security view, the deployer will have to determine what each business method does in order to determine which users are authorized to call each method.

A security view consists of a set of security roles -- a semantic grouping of permissions that a given type of users of an application must have in order to successfully access the application. Security roles are meant to be logical roles, representing a type of user. You can define method permissions for each security role. A method permission is a permission to invoke a specified group of methods of the enterprise beans' business interface, home interface, component interface, and/or web service endpoints. You can specify an authentication mechanism that will be used to verify the identity of a user.

It is important to keep in mind that security roles are used to define the logical security view of an application. They should not be confused with the user groups, users, principals, and other concepts that exist in the Application Server.

The following sections discuss setting up security roles, authentication mechanisms, and method permissions that define a security view:

Defining Security Roles

Specifying an Authentication Mechanism

Specifying Method Permissions

Defining Security Roles

Use the @DeclareRoles and @RolesAllowed annotations to define security roles using Java language annotations. The set of security roles used by the application is the total of the security roles defined by the security role names used in the @DeclareRoles and @RolesAllowed annotations.

You can augment the set of security roles defined for the application by annotations using the security-role deployment descriptor element to define security roles, where you use the role-name element to define the name of the security role.

The following example illustrates how to define security roles in a deployment descriptor:
     ...
<assembly-descriptor>
     <security-role>
          <description>
               This role includes the employees of the
               enterprise who are allowed to access the
               employee self-service application. This role
               is allowed only to access his/her own
               information.
          </description>
          <role-name>employee</role-name>
     </security-role>

     <security-role>
          <description>
               This role includes the employees of the human
               resources department. The role is allowed to
               view and update all employee records.
          </description>
          <role-name>hr-department</role-name>
     </security-role>

     <security-role>
          <description>
               This role includes the employees of the payroll
               department. The role is allowed to view and
               update the payroll entry for any employee.
          </description>
          <role-name>payroll-department</role-name>
     </security-role>

     <security-role>
          <description>
               This role should be assigned to the personnel
               authorized to perform administrative functions
               for the employee self-service application.
               This role does not have direct access to
               sensitive employee and payroll information.
          </description>
          <role-name>admin</role-name>
     </security-role>
     ...
</assembly-descriptor> 
Linking Security Role References to Security Roles

The security role references used in the components of the application are linked to the security roles defined for the application. In the absence of any explicit linking, a security role reference will be linked to a security role having the same name.

You can explicitly link all the security role references declared in the @DeclareRoles annotation or security-role-ref elements for a component to the security roles defined by the use of annotations (as discussed in Defining Security Roles) and/or in the security-role elements.

You use the role-link element to link each security role reference to a security role. The value of the role-link element must be the name of one of the security roles defined in a security-role element, or by the @DeclareRoles or @RolesAllowed annotations (as discussed in Defining Security Roles). You do not need to use the role-link element to link security role references to security roles when the role-name used in the code is the same as the name of the security-role to which you would be linking.

The following example illustrates how to link the security role reference name payroll to the security role named payroll-department:
... 
<enterprise-beans> 
     ... 
     <session> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <ejb-class>com.aardvark.payroll.PayrollBean</ejb-class> 
          ... 
          <security-role-ref> 
               <description> 
                    This role should be assigned to the 
                    employees of the payroll department. 
                    Members of this role have access to 
                    anyone's payroll record. 
                    The role has been linked to the 
                    payroll-department role. 
               </description> 
               <role-name>payroll</role-name> 
               <role-link>payroll-department</role-link> 
          </security-role-ref> 
          ... 
     </session> 
     ... 
</enterprise-beans> 
... 
Specifying an Authentication Mechanism

Authentications mechanisms are specified in the runtime deployment descriptor. When annotations, such as the @RolesAllowed annotation, are used to protect methods in the enterprise bean, you can configure the Interoperable Object Reference (IOR) to enable authentication for an enterprise application. This is accomplished by adding the <login-config> element to the runtime deployment descriptor, sun-ejb-jar.xml.

You can use the USERNAME-PASSWORD authentication method for an enterprise bean. You can use either the BASIC or CLIENT-CERT authentication methods for web service endpoints.

For more information on specifying an authentication mechanism, read Configuring IOR Security or Example: Securing an Enterprise Bean.

Specifying Method Permissions

If you have defined security roles for the enterprise beans in the ejb-jar file, you can also specify the methods of the business interface, home interface, component interface, and/or web service endpoints that each security role is allowed to invoke.

You can use annotations and/or the deployment descriptor for this purpose. Refer to the following sections for more information on specifying method permissions:

Specifying Method Permissions Using Annotations

Specifying Method Permissions Using Deployment Descriptors

Specifying Method Permissions Using Annotations

The method permissions for the methods of a bean class can be specified on the class, the business methods of the class, or both. Method permissions can be specified on a method of the bean class to override the method permissions value specified on the entire bean class. The following annotations are used to specify method permissions:

@RolesAllowed(list of roles)

The value of the @RolesAllowed annotation is a list of security role names to be mapped to the security roles that are permitted to execute the specified method(s). Specifying this annotation on the bean class means that it applies to all applicable business methods of the class.

@PermitAll

The @PermitAll annotation specifies that all security roles are permitted to execute the specified method(s). Specifying this annotation on the bean class means that it applies to all applicable business methods of the class.

@DenyAll

The @DenyAll annotation specifies that no security roles are permitted to execute the specified method(s).

The following example code illustrates the use of these annotations:
@RolesAllowed("admin")
public class SomeClass {
    public void aMethod () {...}
    public void bMethod () {...}
    ...
}

@Stateless public class MyBean implements A extends SomeClass {

    @RolesAllowed("HR")
    public void aMethod () {...}

    public void cMethod () {...}
    ...
} 
In this example, assuming aMethod, bMethod, and cMethod are methods of business interface A, the method permissions values of methods aMethod and bMethod are @RolesAllowed("HR") and @RolesAllowed("admin") respectively. The method permissions for method cMethod have not been specified.

To clarify, the annotations are not "inherited" by the subclass per se, they apply to methods of the superclass which are inherited by the subclass. Also, annotations do not apply to CMP entity beans.

An example that uses annotations to specify method permissions is described in Example: Securing an Enterprise Bean.

Specifying Method Permissions Using Deployment Descriptors

Note: Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.

You define the method permissions in the deployment descriptor using the method-permission elements, as discussed below:

Each 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. Each method (or set of methods) is identified by the method element.

The method permissions relation is defined as the union of all the method permissions defined in the individual method-permission elements.

A security role or a method can appear in multiple method-permission elements.

Here is some other useful information about setting method permissions using deployment descriptors:
You can specify that all roles are permitted to execute one or more specified methods, which, in effect, indicates that the methods should not be checked for authorization prior to invocation by the container. To specify that all roles are permitted, use the unchecked element instead of a role name in a method permission.

If a method permission specifies both the unchecked element for a given method and one or more security roles, all roles are permitted for the specified methods.

The exclude-list element can be used to indicate the set of methods that should not be called. At deployment time, the deployer will know that no access is permitted to any method contained in this list.

If a given method is specified in both the exclude-list element and in a method permission, the deployer should exclude access to this method.

It is possible that some methods are not assigned to any security roles nor contained in the exclude-list element. In this case, the deployer should assign method permissions for all of the unspecified methods, either by assigning them to security roles, or by marking them as unchecked. If the deployer does not assign method permissions to the unspecified methods, those methods must be treated by the container as unchecked.

The method element uses the ejb-name, method-name, and method-params elements to denote one or more methods of an enterprise bean's business interface, home interface, component interface, and/or web service endpoints.

There are three legal styles for composing the method element:
The first style is used for referring to all of the business interface, home interface, component interface, and web service endpoints methods of a specified bean.
    <method>
      <ejb-name>EJB_NAME</ejb-name>
      <method-name>*</method-name>
    </method> 
The second style is used for referring to a specified method of the business interface, home interface, component interface, or web service endpoints methods of the specified enterprise bean. If the enterprise bean contains multiple methods with the same overloaded name, the element of this style refers to all of the methods with the overloaded name.
    <method>
      <ejb-name>EJB_NAME</ejb-name>
      <method-name>METHOD</method-name>
    </method> 
The third style is used for referring to a specified method within a set of methods with an overloaded name. The method must be defined in the business interface, home interface, component interface, or web service endpoints methods of the specified enterprise bean. If there are multiple methods with the same overloaded name, however, this style refers to all of the overloaded methods. All of the parameters are the fully-qualified Java types, for example, java.lang.String.
    <method>
      <ejb-name>EJB_NAME</ejb-name>
      <method-name>METHOD</method-name>
      <method-params>
        <method-param>PARAMETER_1</method-param>
        <method-param>PARAMETER_2</method-param>
      </method-params>
    </method> 
The following example illustrates how security roles are assigned method permissions in the deployment descriptor:
... 
<method-permission> 
     <role-name>employee</role-name> 
     <method> 
          <ejb-name>EmployeeService</ejb-name> 
          <method-name>*</method-name> 
     </method> 
</method-permission> 

<method-permission> 
     <role-name>employee</role-name> 
     <method> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <method-name>findByPrimaryKey</method-name> 
     </method> 
     <method> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <method-name>getEmployeeInfo</method-name> 
     </method> 
     <method> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <method-name>updateEmployeeInfo</method-name> 
     </method> 
</method-permission> 

<method-permission> 
     <role-name>payroll-department</role-name> 
     <method> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <method-name>findByPrimaryKey</method-name> 
     </method> 
     <method> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <method-name>getEmployeeInfo</method-name> 
     </method> 
     <method> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <method-name>updateEmployeeInfo</method-name> 
     </method> 
     <method> 
          <ejb-name>AardvarkPayroll</ejb-name> 
          <method-name>updateSalary</method-name> 
     </method> 
</method-permission> 

<method-permission> 
     <role-name>admin</role-name> 
     <method> 
          <ejb-name>EmployeeServiceAdmin</ejb-name> 
          <method-name>*</method-name> 
     </method> 
</method-permission> 
... 
Mapping Security Roles to Application Server Groups

The Application Server assigns users to groups, rather than to security roles. Adding and modifying users in the Application Server is discussed in Managing Users and Groups on the Application Server (page 875).

When you are developing a Java EE application, you don't need to know what categories of users have been defined for the realm in which the application will be run. In the Java EE platform, the security architecture provides a mechanism for mapping the roles defined in the application to the users or groups defined in the runtime realm. To map a role name permitted by the application or module to principals (users) and groups defined on the server, use the security-role-mapping element in the runtime deployment descriptor (sun-application.xml, sun-web.xml, or sun-ejb-jar.xml) file. The entry needs to declare a mapping between a security role used in the application and one or more groups or principals defined for the applicable realm of the Application Server. An example for the sun-application.xml file is shown below:
<sun-application>
     <security-role-mapping>
          <role-name>CEO</role-name>
          <principal-name>smcneely</principal-name>
     </security-role-mapping>
     <security-role-mapping>
          <role-name>ADMIN</role-name>
          <group-name>directors</group-name>
     </security-role-mapping>
</sun-application> 
The role name can be mapped to either a specific principal (user), a group, or both. The principal or group names referenced must be valid principals or groups in the current default realm of the Application Server. The role-name in this example must exactly match the role-name in the security-role element of the corresponding web.xml file or the role name defined in the @DeclareRoles or @RolesAllowed annotations.

Sometimes the role names used in the application are the same as the group names defined on the Application Server. Under these circumstances, you can enable a default principal-to-role mapping on the Application Server using the Admin Console, following these steps:

Start the Application Server, then the Admin Console.

Expand the Configuration node.

Select the Security node.

On the Security page, check the enable box beside Default Principal to Role Mapping.

For an enterprise application, you can specify the security role mapping at the application layer, in sun-application.xml, or at the module layer, in sun-ejb-jar.xml. When specified at the application layer, the role mapping applies to all contained modules and overrides same-named role mappings at the module layer. The assembler is responsible for reconciling the module-specific role mappings in order to yield one effective mapping for the application.

Propagating Security Identity

You can specify whether a caller's security identity should be used for the execution of specified methods of an enterprise bean, or whether a specific run-as identity should be used.

For example, an application client is making a call to an enterprise bean method in one EJB container. This enterprise bean method, in turn, makes a call to an enterprise bean method in another container. The security identity during the first call is the identity of the caller. The security identity during the second call can be any of the following options:

By default, the identity of the caller of the intermediate component is propagated to the target enterprise bean. This technique is used when the target container trusts the intermediate container.

A specific identity is propagated to the target enterprise bean. This technique is used when the target container expects access via a specific identity.

To propagate an identity to the target enterprise bean, configure a run-as identity for the bean as discussed in either Configuring a Component's Propagated Security Identity.

Establishing a run-as identity for an enterprise bean does not affect the identities of its callers, which are the identities tested for permission to access the methods of the enterprise bean. The run-as identity establishes the identity the enterprise bean will use when it makes calls.

The run-as identity applies to the enterprise bean as a whole, including all the methods of the enterprise bean's business interface, home interface, component interface, and web service endpoint interfaces, the message listener methods of a message-driven bean, the time-out callback method of an enterprise bean, and all internal methods of the bean that might be called in turn.

Configuring a Component's Propagated Security Identity

You can configure an enterprise bean's Run-as, or propagated, security identity using either of the following:

The RunAs annotation

The following example illustrates the definition of a run-as identity using annotations:

  @RunAs("admin")   @Stateless public class EmployeeServiceBean       implements EmployeeService{   ...   }

The role-name element of the run-as application deployment descriptor element (web.xml, ejb-jar.xml)

The following example illustrates the definition of a run-as identity using deployment descriptor elements:

  ...   <enterprise-beans>     ...     <session>       <ejb-name>EmployeeService</ejb-name>       ...       <security-identity>         <run-as>           <role-name>admin</role-name>         </run-as>       </security-identity>       ...     </session>     ...   </enterprise-beans>   ...

Alternately, you can use the use-caller-identity element to indicate that you want to use the identity of the original caller, as shown in the code below:

<security-identity>   <use-caller-identity /> </security-identity>

More detail about the elements contained in deployment descriptors is available in the Application Server's Application Deployment Guide, a link to which can be found in Further Information.

In either case, you will have to map the run-as role name to a given principal defined on the Application Server if the given roles associate to more than one user principal. Mapping roles to principals is described in Mapping Security Roles to Application Server Groups.

Trust between Containers

When an enterprise bean is designed so that either the original caller identity or a designated identity is used to call a target bean, the target bean will receive the propagated identity only; it will not receive any authentication data.

There is no way for the target container to authenticate the propagated security identity. However, because the security identity is used in authorization checks (for example, method permissions or with the isCallerInRole() method), it is vitally important that the security identity be authentic. Because there is no authentication data available to authenticate the propagated identity, the target must trust that the calling container has propagated an authenticated security identity.

By default, the Application Server is configured to trust identities that are propagated from different containers. Therefore, there are no special steps that you need to take to set up a trust relationship.

Using Enterprise Bean Security Annotations

Annotations are used in code to relay information to the deployer about security and other aspects of the application. Specifying this information in annotations or in the deployment descriptor helps the deployer set up the appropriate security policy for the enterprise bean application.

Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.

The following is a listing of annotations that address security, can be used in an enterprise bean, and are discussed in this tutorial:

The @DeclareRoles annotation declares each security role referenced in the code. Use of this annotation is discussed in Declaring Security Roles Using Annotations.

The @RolesAllowed, @PermitAll, and @DenyAll annotations are used to specify method permissions. Use of these annotations is discussed in Specifying Method Permissions Using Annotations.

The @RunAs metatdata annotation is used to configure a component's propagated security identity. Use of this annotation is discussed in Configuring a Component's Propagated Security Identity.

Using Enterprise Bean Security Deployment Descriptor Elements

Enterprise JavaBeans components use an EJB deployment descriptor that must be named META-INF/ejb-jar.xml and must be contained in the EJB's jar file. The role of the deployment descriptor is to relay information to the deployer about security and other aspects of the application. Specifying this information in annotations or in the deployment descriptor helps the deployer set up the appropriate security policy for the enterprise bean application. More detail about the elements contained in deployment descriptors is available in the Application Server's Application Deployment Guide, a link to which can be found in Further Information.

Note: Using annotations is the recommended method for adding security to enterprise bean applications.

Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not been specified in the deployment descriptor, and a value has been specified for that method by means of the use of annotations, the value specified in annotations will apply. The granularity of overriding is on the per-method basis.

The following is a listing of deployment descriptor elements that address security, can be used in an enterprise bean, and are discussed in this tutorial:

The security-role-ref element declares each security role referenced in the code. Use of this element is discussed in Declaring Security Roles Using Deployment Descriptor Elements.

The security-role element defines broad categories of users, and is used to provide access to protected methods. Use of this element is discussed in Defining Security Roles.

The <method-permission> element is used to specify method permissions. Use of these elements is discussed in Specifying Method Permissions Using Deployment Descriptors.

The run-as element is used to configure a component's propagated security identity. Use of this element is discussed in Configuring a Component's Propagated Security Identity.

The schema for ejb-jar deployment descriptors can be found in section 18.5, Deployment Descriptor XML Schema, in the EJB 3.0 Specification (JSR-220) at http://jcp.org/en/jsr/detail?id=220.

Configuring IOR Security

The EJB interoperability protocol is based on Internet Inter-ORB Protocol (IIOP/GIOP 1.2) and the Common Secure Interoperability version 2 (CSIv2) CORBA Secure Interoperability specification.

Enterprise beans that are deployed in one vendor's server product are often accessed from Java EE client components that are deployed in another vendor's product. CSIv2, a CORBA/IIOP-based standard interoperability protocol, addresses this situation by providing authentication, protection of integrity and confidentiality, and principal propagation for invocations on enterprise beans, where the invocations take place over an enterprise's intranet. CSIv2 configuration settings are specified in the Interoperable Object Reference (IOR) of the target enterprise bean. IOR configurations are defined in Chapter 24 of the CORBA/IIOP specification, Secure Interoperability. This chapter can be downloaded from the following URL:
http://www.omg.org/cgi-bin/doc?formal/02-06-60

The EJB interoperability protocol is defined in Chapter 14, Support for Distribution and Interoperability, of the EJB specification, which can be downloaded from http://jcp.org/en/jsr/detail?id=220.

Based on application requirements, IORs are configured in vendor-specific XML files, such as sun-ejb-jar.xml, instead of in standard application deployment descriptor files, such as ejb-jar.xml.

For a Java EE application, IOR configurations are specified in Sun-specific xml files, for example, sun-ejb-jar_2_1-1.dtd. The ior-security-config element describes the security configuration information for the IOR. A description of some of the major sub-elements is provided below.

transport-config

This is the root element for security between the end points. It contains the following elements:

integrity: specifies whether the target supports integrity-protected messages for transport. The values are NONE, SUPPORTED or REQUIRED.

confidentiality: specifies whether the target supports privacy-protected messages (SSL) for transport. The values are NONE, SUPPORTED or REQUIRED.

establish-trust-in-target: specifies whether or not the target component is capable of authenticating to a client for transport. It is used for mutual authentication (to validate the server's identity). The values are NONE, SUPPORTED or REQUIRED.

establish-trust-in-client: specifies whether or not the target component is capable of authenticating a client for transport (target asks the client to authenticate itself). The values are NONE, SUPPORTED or REQUIRED.

as-context

This is the element that describes the authentication mechanism (CSIv2 authentication service) that will be used to authenticate the client. If specified it will be the username-password mechanism. It contains the following elements:

required: specifies whether the authentication method specified is required to be used for client authentication. Setting this field to true indicates that the authentication method specified is required. Setting this field to false indicates that the method authentication is not required. The element value is either true or false.

auth-method: describes the authentication method. The only supported value is USERNAME_PASSWORD

realm: describes the realm in which the user is authenticated. Must be a valid realm that is registered in a server configuration.

In the Duke's Bank example, the as-context setting is used to require client authentication (with user name and password) when access to protected methods in the AccountControllerBean and CustomerControllerBean components is attempted.

sas-context

This element is related to the CSIv2 security attribute service. It describes the sas-context fields. It contains the following elements:

caller-propagation: indicates if the target will accept propagated caller identities. The values are NONE or SUPPORTED.

In the Duke's Bank example, the sas-context setting is set to Supported for the AccountBean, CustomerBean, and TxBean components, indicating that these target components will accept propagated caller identities.

The following is an example that defines security for an IOR in the sun-ejb-jar.xml file in the sample application (assuming you installed the samples server) at <AS_INSTALL>\samples\webservices\security\ejb\apps\basicAuth\basicAuth-ejb\src\conf\sun-ejb-jar.xml:
<sun-ejb-jar>
  <enterprise-beans>
    <unique-id>1</unique-id>
    <ejb>
      <ejb-name>HelloWorld</ejb-name>
      <jndi-name>HelloWorld</jndi-name>
      <ior-security-config>
        <transport-config>
          <integrity>NONE</integrity>
          <confidentiality>NONE</confidentiality>
          <establish-trust-in-target>NONE</establish-trust-in-target>
          <establish-trust-in-client>NONE</establish-trust-in-client>
        </transport-config>
        <as-context>
          <auth-method>USERNAME_PASSWORD</auth-method>
          <realm>default</realm>
          <required>true</required>
        </as-context>
        <sas-context>
          <caller-propagation>NONE</caller-propagation>
        </sas-context>
      </ior-security-config>
      <webservice-endpoint>
        <port-component-name>HelloIF</port-component-name>
        <endpoint-address-uri>service/HelloWorld</endpoint-address-uri>
        <login-config>
          <auth-method>BASIC</auth-method>
        </login-config>
      </webservice-endpoint>
    </ejb>
  </enterprise-beans>
</sun-ejb-jar> 
Deploying Secure Enterprise Beans

The deployer is responsible for ensuring that an assembled application is secure after it has been deployed in the target operational environment. If a security view (security annotations and/or a deployment descriptor) has been provided to the deployer, the security view is mapped to the mechanisms and policies used by the security domain in the target operational environment, which in this case is the Application Server. If no security view is provided, the deployer must set up the appropriate security policy for the enterprise bean application.

Deployment information is specific to a web or application server. Please read the Sun Java System Application Server Application Deployment Guide for more information on deploying enterprise beans. A link to this document is provided in Further Information.

Accepting Unauthenticated Users

Web applications accept unauthenticated web clients and allow these clients to make calls to the EJB container. The EJB specification requires a security credential for accessing EJB methods. Typically, the credential will be that of a generic unauthenticated user. The way you specify this credential is implementation-specific.

In the Application Server, you must specify the name and password that unauthenticated user will use to login by modifying the Application Server using the Admin Console:

Start the Application Server, then the Admin Console.

Expand the Configuration node.

Select the Security node.

On the Security page, set the Default Principal and Default Principal Password values.

Accessing Unprotected Enterprise Beans

If the deployer has granted full access to a method, any user or group can invoke the method. Conversely, the deployer can deny access to a method.

To modify which role can be used in applications to grant authorization to anyone, specify a value for Anonymous Role. To set the Anonymous Role field, follow these steps:

Start the Application Server, then the Admin Console.

Expand the Configuration node.

Select the Security node.

On the Security page, specify the Anonymous Role value.