TechFAQ

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 security roles defined by the Application Assembler present a 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 component interfaces to the security roles to define the security view of the application.

<!--
The security-role element contains the definition of a security role.
The definition consists of an optional description of the security
role, and the security role name.
Used in: assembly-descriptor
Example:

<security-role>
	<description>
		This role includes all employees who are authorized
		to access the employee service application.
	</description>
	<role-name>employee</role-name>
</security-role>
-->

<!ELEMENT security-role (description?, role-name)>

					

Because the Application Assembler does not, in general, know the security environment of the operational environment, the security roles are meant to be LOGICAL roles (or actors), each representing a type of user that should have the same access rights to the application.

The SECURITY ROLES defined by the security-role elements are scoped to the ejb-jar file level, and apply to ALL the enterprise beans in the ejb-jar file.

Security role references

The Bean Provider is responsible for DECLARING 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 security roles DEFINED for an assembled application through the security-role elements.

<!--
The security-role-ref element contains the declaration of a security
role reference in the enterprise bean's code. The declaration consists
of an optional description, the security role name used in the
code, and an optional link to a defined security role.
The value of the role-name element must be the String used as the
parameter to the EJBContext.isCallerInRole(String roleName) method.
The value of the role-link element must be the name of one of the
security roles defined in the security-role elements.
Used in: entity and session
-->

<!ELEMENT security-role-ref (description?, role-name, role-link?)>

					

The Bean Provider must declare each security role referenced in the code using the security-role-ref element as follows:

A security role reference, including the name defined by the role-name element, is scoped to the session or entity bean element whose declaration contains the security-role-ref element.

If the Application Assembler defines the security-role elements in the deployment descriptor, he or she is also responsible for linking all the security role references declared in the security-role-ref elements to the security roles defined in the security-role elements.

The Application Assembler LINKS each security role reference to a security role using the role-link element. The value of the role-link element must be the name of one of the security roles defined in a security-role element.

A role-link element must be used even if the value of role-name is the same as the value of the role-link reference.

Method permissions

The Applications 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 component interfaces. If the Application Assembler has defined security roles for the enterprise beans in the ejb-jar file, he or she can also specify the methods of the home and component interfaces that each security role is allowed to invoke.

<!--
The method-permission element specifies that one or more security
roles are allowed to invoke one or more enterprise bean methods. The
method-permission element consists of an optional description, a list
of security role names or an indicator to specify that the methods are
not to be checked for authorization, and a list of method elements.
The security roles used in the method-permission element must be
defined in the security-role elements of the deployment descriptor,
and the methods must be methods defined in the enterprise bean's component
and/or home interfaces.
Used in: assembly-descriptor
-->

<!ELEMENT method-permission (description?, (role-name+|unchecked), method+)>

					

The Application Assembler defines the method permissions relation in the deployment descriptor using the method-permission elements as follows:

The Application Assembler can indicate that some methods should not be checked for authorization prior to invocation by the Container. The Application Assembler uses the unchecked element instead of a role name in the method-permission element to indicate that a method should not be checked for authorization.

Bean's security identity

In addition to specifying the security roles (or principals) that have access to an enterprise bean, the Application Assembler can also specify the run-as role for the entire enterprise bean. 'Run-as' defines the identity that a bean runs with when it calls other beans. This does not change the identity of the caller of the bean. The IDENTITY is configured using the security-identity element in the deployment descriptor. Because this is a per-bean setting, it must be declared for every EJB.

<!--
The security-identity element specifies whether the caller's security
identity is to be used for the execution of the methods of the enterprise
bean or whether a specific run-as identity is to be used. It
contains an optional description and a specification of the security
identity to be used.
Used in: session, entity, message-driven
-->

<!ELEMENT security-identity (description?, (use-caller-identity|
		run-as))>