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:
Declare the name of the security role using the role-name element. 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.
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.
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:
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.
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))>