Specifying Method Permissions Using Deployment Descriptors (The Java EE 5 Tutorial)

The Java EE 5 Tutorial

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