Previous Contents Index Next |
Sun Java System Application Server Standard and Enterprise Edition 7 2004Q2 Developer's Guide to Enterprise JavaBeans Technology

> ## Chapter 7
> Developing Secure Enterprise Beans

> This section describes how security management works in the EJB architecture and provides guidelines for developing secure enterprise beans for the Sun Java System Application Server environment.

> Note | If you are unfamiliar with the EJB technology, refer to the Java Software tutorials: http://java.sun.com/j2ee/docs.html Extensive information on EJB security is contained in Chapter 21, “Security Management,” of the Enterprise JavaBeans Specification, v2.0. General information on application security is contained in the Sun Java System Application Server Developer’s Guide.

> This section addresses the following topics:

> - About Secure Enterprise Beans
> - Defining Security Roles
> - Declaring Method Permissions
> - Declaring Security Role References
> - Specifying Security Identities
> - Using Programmatic Security
> - Handling Unprotected EJB-Tier Resources

> General information on application security is contained in the Sun Java System Application Server Developer’s Guide.

> ##

> About Secure Enterprise Beans

> Your main role as an EJB developer is to declare the security requirements of your applications in such a way that these requirements can be satisfied during application deployment. In most cases, the EJB’s business methods should not contain any security-related logic.

> The following topics are addressed in this section:

> - Authorization and Authentication
> - Security Roles
> - Deployment

> ### Authorization and Authentication

> Authorization provides controlled access to protected resources; it is based on identification and authentication. Identification is the process that enables recognition of an entity by a system. Authentication is the process that verifies the identity of a user, device, or other entity in a computer system, usually as a prerequisite to allowing access to resources in a system.

> Enterprise beans can be configured to permit access only to users with the appropriate authorization level. This is done by using the Sun Java System Application Server Administration interface to generate the deployment descriptor for the application EAR and EJB JAR files.

> ### Security Roles

> A security role is an application-specific logical grouping of users, classified by common trait, such as a customer profile or job title. When an application is deployed, roles are mapped to security identities, such as principals (identities assigned to users as a result of authentication) or groups, in the operational environment. Based on this, a user with a certain security role has associated access rights to an enterprise bean. The link is the actual name of the security role that is being referenced.

> A group also represents a category of users, but its scope is different from the scope of a role.

> - A role is a J2EE application-specific abstraction.
> - A group is a set of environment-specific users from the current realm. Group membership is determined by the underlying realm implementation.

> Note | When defining method restrictions and role mappings, it is a common error to confuse realm groups and J2EE application roles. Such confusion can lead to unintended access consequences or inoperable application configurations. For information on realms, refer to the Sun Java System Application Server Developer’s Guide.

> ### Deployment

> The security role reference defines a mapping between the name of a role that is called from an enterprise bean using isCallerInRole (String name) and the name of a security role that has been defined for the application. This security role reference allows an enterprise bean to reference an existing security role.

> When an application is deployed, the deployer maps the roles to the security identities that exist in the operational environment. When you are developing enterprise beans, you should know the roles of your users, but you probably won't know exactly who the users will be. That's taken care of in the J2EE security architecture. After your component has been deployed, the system administrator maps the roles to the J2EE users (or groups) of the default realm (usually the file realm).

> ##

> Defining Security Roles

> To create a role for a J2EE application, you declare it for the EJB JAR file or for the WAR file that is contained in the application. The security roles defined by the security-role elements are scoped to the EJB JAR file level and apply to all enterprise beans in the EJB JAR files.

> ##### Example

> The following example of a security role definition in a deployment descriptor specifies two role-name elements, employee and admin.

> ...
> <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 to access only
> her/his information
> </desciption>
> <role-name>employee<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
> </desciption>
> <role-name>admin<role-name>
> </security-role>
> ...
> </assembly-descriptor>

> ##

> Declaring Method Permissions

> Method permissions indicate which roles are allowed to invoke which methods. The application assembler declares the method permission relationships 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 listed security roles are allowed to invoke all listed methods. Each security role in the list is identified by the role-name element, and each method (or 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 relationship is defined as the union of all method permissions defined in the individual method permission elements.
> - A security role or a method may appear in multiple method-permission elements.

> ##### Example

> The following deployment descriptor example illustrates how security roles are assigned method permissions in the deployment descriptor. These are converted into security elements at deployment.

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

> ##

> Declaring Security Role References

> As the EJB developer, you are responsible for declaring all security role names used in the enterprise bean in the security-role-ref elements of the deployment descriptor for roles which are used programmatically from within the respective enterprise beans.

> - The application assembler is responsible for linking all 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.

>   Note | The role-link element value must be one of the security role names defined in a security-role element.

> ##### Example

> The following deployment descriptor example shows how to link the security role reference named payroll to the security role named payroll-department.

> <enterprise-beans>
> ...
> <entity>
> <ejb-name>AardvarkPayroll</ejb-name>
> <ejb-class>com.aardvark.payroll.PayrollBean</ejb-class>
> ...
> <security-role-ref>
> <description> This role should be assigned to the payroll
> department's employees. 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>
> ....
> </entity>
> ...
> </enterprise-beans>

> This role should be assigned to the payroll department’s employees. Members of this role have access to anyone's payroll record. The role has been linked to the payroll-department role.

> Further information on security roles can be found in the Sun Java System Application Server Developer’s Guide. More information on EJB access control configuration can be found in the Enterprise JavaBeans Specification, v2.0.

> ##

> Specifying Security Identities

> Optionally, the EJB assembler can specify whether the caller’s identity should be used for executing the EJB methods or whether a specific run-as identity should be used. The security-identity element in the deployment descriptor is used for this purpose. The value of the security-identity element is use-caller-identity or run-as.

> Unless specified, the caller identity is used by default.

> ### The run-as Identity

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

> The EJB assembler can use the run-as 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 EJB’s home and component interface, or to the onMessage method of a message-driven bean, and all internal methods of the enterprise bean that might, in turn, be called.

> Because the assembler does not generally 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 in the deployment descriptor. The deployer must then assign a security principal (defined in the operational environment) to be used as the principal for the run-as identity. The security principal should be a principal that has been assigned to the security role as specified by the role-name element.

> ##

> Using Programmatic Security

> In general, security management should be enforced by the container in a manner that is transparent to the EJB’s business methods.

> Note | Enterprise beans can use programmatic login just as servlets do. For more information, see the Sun Java System Application Server Developer’s Guide.

> Programmatic security in the EJB tier consists of the getCallerPrincipal and the isCallerInRole methods. You can use the getCallerPrincipal method to determine the caller of the enterprise bean, and the isCallerInRole method to determine the caller's role.

> The getCallerPrincipal method of the EJBContext interface returns the java.security.Principal object that identifies the caller of the enterprise bean. (In this case, a principal is the same as a user.) In the following example, the getUser method of an enterprise bean returns the name of the J2EE user that invoked it:

> public String getUser()
> {
> return context.getCallerPrincipal().getName();
> }

> You can determine whether an EJB's caller belongs to a particular role by invoking the isCallerInRole method:

> boolean result = context.isCallerInRole("Customer");

> For details on how to implement programmatic security, refer to Chapter 21, Security Management,” of the Enterprise JavaBeans Specification, v2.0.

> ##

> Handling Unprotected EJB-Tier Resources

> All users have the anonymous role. By default, the value of the anonymous role is ANYONE, which is configurable in the server.xml file. So, if a method permission specifies that the role required is ANYONE (or whatever the anonymous role is set to), then any user can access this method.

> Note | If a method permission covering a method does not exist, the method is accessible to all.

> If a method permission exists, it is always enforced. For example, if a method permission is set so that the updateEmployeeInfo method can only be accessed by the employee role, then it is never possible to access this method without role employee. If the employee role is not mapped to any user or group, no one will be able to invoke the updateEmployeeInfo method.

> Previous Contents Index Next

> Copyright 2004 Sun Microsystems, Inc. All rights reserved.