Given a security-related deployment descriptor tag or annotation, identify correct and incorrect statements and/or code related to that tag.

Given a security-related deployment descriptor tag or annotation, identify correct and incorrect statements and/or code related to that tag.
Prev	Chapter 11. Security Management	Next


	[EJB_3.0_SIMPLIFIED] 10.9; 10.9.1; 10.9.2; 10.9.3; 10.9.4; 10.9.5 [EJB_3.0_CORE] 17.3.2.1 ; 17.3.2.2 ; 17.3.4; 17.3.4.1

Security and Method Permissions Metadata Annotations

The following security-related annotations are in the package javax.annotation.security.

Security Role References

The DeclareRoles annotation is used to declare the references to security roles in the enterprise bean code:

package javax.annotation.security;

@Target({TYPE}) @Retention(RUNTIME)
public @interface DeclareRoles {
	String[] value();
}

Method Permissions
The RolesAllowed annotation specifies the security roles that are allowed to invoke the methods of the bean. The value of the RolesAllowed annotation is a list of security role names.
This annotation can be specified on the bean class and/or it can be specified on methods of the class that are methods of the business interface. Specifying the RolesAllowed annotation on the bean class means that it applies to ALL applicable interface methods of the class. Specifying the annotation on a method applies it to that method ONLY. If the annotation is applied at both the class and the method level, the method value OVERRIDES if the two disagree. If the PermitAll annotation is applied to the bean class, and RolesAllowed is specified on an individual method, the value of the RolesAllowed annotation OVERRIDES for the given method.
```
package javax.annotation.security;

@Target({TYPE, METHOD}) @Retention(RUNTIME)
public @interface RolesAllowed {
	String[] value();
}					
								
```
PermitAll
The PermitAll annotation specifies that all security roles are allowed to invoke the specified method(s) - i.e., that the specified method(s) are "unchecked". This annotation can be specified on the bean class and/or it can be specified on the business methods of the class. Specifying the PermitAll annotation on the bean class means that it applies to ALL applicable business methods of the class. Specifying the annotation on a method applies it to that method ONLY, overriding any class-level setting for the particular method.
```
package javax.annotation.security;

@Target ({TYPE, METHOD}) @Retention(RUNTIME)
public @interface PermitAll {}
								
```
DenyAll
The DenyAll annotation specifies that no security roles are allowed to invoke the specified method - i.e. that the specified method is to be EXCLUDED from execution.
```
package javax.annotation.security;

@Target (METHOD) @Retention(RUNTIME)
public @interface DenyAll {}
								
```
RunAs
The RunAs annotation is used to specify the bean's run-as property. This annotation is applied to the bean class. Its value is the name of a security role.
```
package javax.annotation.security;

@Target(TYPE) @Retention(RUNTIME)
public @interface RunAs {
	String value();
}
								
```

Specification of Method Permissions with Metadata Annotations

The following is the description of the rules for the specification of method permissions using Java language metadata annotations.

The method permissions for the methods of a bean class may be specified on the class, the business methods of the class, or both.

The RolesAllowed, PermitAll, and DenyAll annotations are used to specify method permissions. 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). The PermitAll annotation specifies that all security roles are permitted to execute the specified method(s). The DenyAll annotation specifies that no security roles are permitted to execute the specified method(s).

Specifying the RolesAllowed or PermitAll annotation on the bean class means that it applies to all applicable business methods of the class.

Method permissions may be specified on a method of the bean class to OVERRIDE the method permissions value specified on the bean class.

If the bean class has superclasses, the following additional rules apply:

A method permissions value specified on a superclass S applies to the business methods defined by S.
A method permissions value may be specified on a business method M defined by class S to override for method M the method permissions value explicitly or implicitly specified on the class S.
If a method M of class S overrides a business method defined by a superclass of S, the method permissions value of M is determined by the above rules as applied to class S.

Example:

@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 () {...}
	...
}

Assuming aMethod, bMethod, 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.

Specification of Method Permissions in the Deployment Descriptor

The Bean Provider may use the deployment descriptor as an alternative to metadata annotations to specify the method permissions (or as a means to supplement or override metadata annotations for method permission values). The application assembler is permitted to override the method permission values using the bean's deployment descriptor.

Any values explicitly specified in the deployment descriptor override any values specified in annotations. If a value for a method has not be 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 Bean Provider or Application Assembler defines the method permissions relation in the deployment descriptor using the method-permission elements as follows:

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, and each method (or a set of methods, as described below) is identified by the method element. An optional description can be associated with a method-permission element using the description 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 may appear in multiple method-permission elements.

The Bean Provider or Application Assembler can indicate that all roles are permitted to execute one or more specified methods (i.e., the methods should not be "checked" for authorization prior to invocation by the container). The unchecked element is used instead of a role name in the method-permission element to indicate that all roles are permitted.

If the method permission relation 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. The Deployer should configure the enterprise bean's security such that no access is permitted to any method contained in the exclude-list.

If a given method is specified both in the exclude-list element and in the method permission relation, the Deployer should configure the enterprise bean's security such that NO access is permitted to the method.

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 , home, and component interface, and/or web service endpoint. There are three legal styles for composing the method element:

```
<method>
	<ejb-name>EJBNAME</ejb-name>
	<method-name>*</method-name>
</method>

								
```
This style is used for referring to ALL of the methods of the business, home, and component interfaces, and web service endpoint of a specified enterprise bean.
```
<method>
	<ejb-name>EJBNAME</ejb-name>
	<method-name>METHOD</method-name>
</method>

								
```
This style is used for referring to a specified method of the business, home, or component interface, or web service endpoint of the specified enterprise bean. If there are multiple methods with the same overloaded name, this style refers to ALL of the overloaded methods.
```
<method>
	<ejb-name>EJBNAME</ejb-name>
	<method-name>METHOD</method-name>
	<method-params>
		<method-param>PARAMETER_1</method-param>
		...
		<method-param>PARAMETER_N</method-param>
	</method-params>
</method>

								
```
This style is used to refer to a specified method within a set of methods with an overloaded name. The method must be defined in the specified enterprise bean's business, home, or component interface, or web service endpoint. If there are multiple methods with the same overloaded name, however, this style refers to ALL of the overloaded methods.

The optional method-intf element can be used to differentiate between methods with the same name and signature that are multiply defined across the business, component, or home interfaces, and/or web service endpoint. If the same method is a method of both the local business interface and local component interface, the same method permission values apply to the method for BOTH interfaces. Likewise, if the same method is a method of both the remote business interface and remote component interface, the same method permission values apply to the method for BOTH interfaces.

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>

Specification of Security Identities in the Deployment Descriptor

The Bean Provider or Application Assembler typically specifies whether the caller's security identity should be used for the execution of the methods of an enterprise bean OR whether a specific run-as identity should be used.

By default the caller's security identity is used. The Bean Provider can use the RunAs metadata annotation to specify a run-as identity for the execution of the bean's methods. If the deployment descriptor is used, the Bean Provider or the Application Assembler can use the security-identity deployment descriptor element for this purpose OR to override a security identity specified in metadata. The value of the security-identity element is either use-caller-identity or run-as.

Defining the security identities in the deployment descriptor is optional for the Application Assembler. Their omission in the deployment descriptor means that the Application Assembler chose not to pass any instructions related to security identities to the Deployer in the deployment descriptor.

If a run-as security identity is not specified by the Deployer, the container should use the caller's security identity for the execution of the bean's methods.

Run-as

The Bean Provider can use the RunAs metadata annotation or the Bean Provider or Application Assembler can use the run-as deployment descriptor element to define a run-as identity for an enterprise bean in the deployment descriptor. The run-as identity applies to the enterprise bean as a WHOLE, that is, to ALL methods of the enterprise bean's business, home, and component interfaces, and/or web service endpoint; to the message listener methods of a message-driven bean; and to the timeout callback method of an enterprise bean; and all internal methods of the bean that they might in turn call.

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.

Because the Bean Provider and Application Assembler do not, in general, know the security environment of the operational environment, the run-as identity is designated by a logical role-name, which corresponds to one of the security roles defined by the Bean Provider or Application Assembler in the metadata annotations or deployment descriptor.

The Deployer then ASSIGNS a security principal defined in the operational environment to be used as the principal for the run-as identity. The security principal assigned by the Deployer should be a principal that has been assigned to the security role specified by RunAs annotation or by the role-name element of the run-as deployment descriptor element.

The Bean Provider and/or Application Assembler is responsible for the following in the specification of run-as identities:

Use the RunAs metadata annotation or role-name element of the run-as deployment descriptor element to define the name of the security role.
Optionally, use the description element to provide a description of the principal that is expected to be bound to the run-as identity in terms of its security role.

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

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

Using the deployment descriptor, this can be specified as follows:


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

Prev	Up	Next
Identify correct and incorrect statements or examples about use of the isCallerInRole and getCallerPrincipal EJB programmatic security APIs.	Home	Part II. Appendices