J2EE Declarative Security Overview

The security model that the J2EE specification advocates is a declarative model. It is declarative in that you describe the security roles and permissions by using a standard XML descriptor rather than embedding security into your business component. This isolates security from business-level code because security tends to be more a function of where the component is deployed than an inherent aspect of the component's business logic. For example, consider an ATM component that is to be used to access a bank account. The security requirements, roles, and permissions will vary, independently of how you access the bank account, based on what bank is managing the account, where the ATM is deployed, and so on.

Securing a J2EE application is based on the specification of the application security requirements via the standard J2EE deployment descriptors. You secure access to EJBs and web components in an enterprise application by using the ejb-jar.xml and web.xml deployment descriptors. The following sections look at the purpose and usage of the various security elements.

Security References

Both EJBs and servlets can declare one or more security-role-ref elements (see Figure 8.1). You use this element to declare that a component is using the role-name value as an argument to the isCallerInRole(String) method. By using the isCallerInRole method, a component can verify whether the caller is in a role that has been declared with a security-role-ref/role-name element. The role-name element value must link to a security-role element through the role-link element. The typical use of isCallerInRole is to perform a security check that cannot be defined by using the role-based method-permissions elements.

Figure 8.1. The security-role-ref element.

Listing 8.1 shows the use of security-role-ref in an ejb-jar.xml file.

Listing 8.1. An Example of an ejb-jar.xml Descriptor Fragment That Illustrates security-role-ref Element Usage

 <!-- A sample ejb-jar.xml fragment --> <ejb-jar>   <enterprise-beans>     <session>       <ejb-name>ASessionBean</ejb-name>       ...       <security-role-ref>           <role-name>TheRoleICheck</role-name>           <role-link>TheApplicationRole</role-link>       </security-role-ref>     </session>   </enterprise-beans>   ... </ejb-jar> 

Listing 8.2 shows the use of security-role-ref in a web.xml file.

Listing 8.2. An Example of a web.xml Descriptor Fragment That Illustrates security-role-ref Element Usage

 <web-app>     <servlet>         <servlet-name>AServlet</servlet-name>         ...         <security-role-ref>             <role-name>TheServletRole</role-name>             <role-link>TheApplicationRole</role-link>         </security-role-ref>     </servlet>     ... </web-app> 

Security Identity

An EJB has the capability to specify what identity an EJB should use when it invokes methods on other components, using the security-identity element (see Figure 8.2).

Figure 8.2. The security-identity element.

The invocation identity can be that of the current caller, or it can be a specific role. The application assembler uses the security-identity element with a use-caller-identity child element to indicate that the current caller's identity should be propagated as the security identity for method invocations made by the EJB. Propagation of the caller's identity is the default used in the absence of an explicit security-identity element declaration.

Alternatively, the application assembler can use the run-as/role-name child element to specify that a specific security role given by the role-name value should be used as the security identity for method invocations made by the EJB. Note that this does not change the caller's identity, as shown by EJBContext.getCallerPrincipal(). Rather, the caller's security roles are set to the single role specified by the run-as/role-name element value. One use case for the run-as element is to prevent external clients from accessing internal EJBs. You accomplish this by assigning the internal EJB method-permission elements that restrict access to a role never assigned to an external client. EJBs that need to use internal EJBs are then configured with a run-as/role-name equal to the restricted role. Listing 8.3 shows an example of a descriptor fragment that illustrates security-identity element usage.

Listing 8.3. An Example of an ejb-jar.xml Descriptor Fragment That Illustrates security-identity Element Usage

 <!-- A sample ejb-jar.xml fragment --> <ejb-jar>     <enterprise-beans>         <session>             <ejb-name>ASessionBean</ejb-name>             <!-- ... -->             <security-identity>                 <use-caller-identity/>             </security-identity>         </session>         <session>             <ejb-name>RunAsBean</ejb-name>             <!-- ... -->             <security-identity>                 <run-as>                     <description>A private internal role</description>                     <role-name>InternalRole</role-name>                 </run-as>             </security-identity>         </session>     </enterprise-beans>     <!-- ... --> </ejb-jar> 

Security Roles

The security role name referenced by either the security-role-ref or security-identity element needs to map to one of the application's declared roles. An application assembler defines logical security roles by declaring security-role elements (see Figure 8.3). The role-name value is a logical application role name, such as Administrator, Architect, or SalesManager.

Figure 8.3. The security-role element.

The J2EE specifications note that it is important to keep in mind that the security roles in the deployment descriptor are used to define the logical security view of an application. Roles defined in the J2EE deployment descriptors should not be confused with the user groups, users, principals, and other concepts that exist in the target enterprise's operational environment. The deployment descriptor roles are application constructs with application-domain-specific names. For example, a banking application might use role names such as BankManager, Teller, and Customer.

In JBoss, a security-role element is only used to map security-role-ref/role-name values to the logical role that the component role references. The user's assigned roles are a dynamic function of the application's security manager, as you will see when we discuss the JBossSX implementation details. JBoss does not require the definition of security-role elements in order to declare method permissions. However, the specification of security-role elements is still a recommended practice, to ensure portability across application servers and for deployment descriptor maintenance. Listing 8.4 shows the usage of the security-role element in an ejb-jar.xml file.

Listing 8.4. An Example of an ejb-jar.xml Descriptor Fragment That Illustrates security-role Element Usage

 <!-- A sample ejb-jar.xml fragment --> <ejb-jar>     <!-- ... -->     <assembly-descriptor>         <security-role>             <description>The single application role</description>             <role-name>TheApplicationRole</role-name>         </security-role>     </assembly-descriptor> </ejb-jar> 

Listing 8.5 shows the usage of the security-role element in a web.xml file.

Listing 8.5. An Example of a web.xml Descriptor Fragment That Illustrates security-role Element Usage

 <!-- A sample web.xml fragment --> <web-app>     <!-- ... -->     <security-role>         <description>The single application role</description>         <role-name>TheApplicationRole</role-name>     </security-role> </web-app> 

EJB Method Permissions

An application assembler can set the roles that are allowed to invoke an EJB's home and remote interface methods through method-permission element declarations (see Figure 8.4).

Figure 8.4. The method-permission element.

Each method-permission element contains one or more role-name child elements that define the logical roles that are allowed to access the EJB methods as identified by method child elements (see Figure 8.5). You can also specify an unchecked element instead of the role-name element to declare that any authenticated user can access the methods identified by method child elements. In addition, you can declare that no one should have access to a method that has the exclude-list element. If an EJB has methods that have not been declared as accessible by a role using a method-permission element, the EJB methods default to being excluded from use. This is equivalent to defaulting the methods into the exclude-list.

Figure 8.5. The method element.

There are three supported styles of method element declarations:

• The first style is used for referring to all the home and component interface methods of the named enterprise bean:

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

  
  

• The second style is used for referring to a specified method of the home or component interface of the named enterprise bean:

   <method>     <ejb-name>EJBNAME</ejb-name>     <method-name>METHOD</method-name> </method> 

  
  

  If there are multiple methods with the same overloaded name, this style refers to all the overloaded methods.

• The third style is used to refer to a specified method within a set of methods with an overloaded name:

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

  
  

  The method must be defined in the specified enterprise bean's home or remote interface. The method-param element values are the fully qualified name of the corresponding method parameter type. If there are multiple methods with the same overloaded signature, the permission applies to all the matching overloaded methods.

The optional method-intf element can be used to differentiate methods with the same name and signature that are defined in both the home and remote interfaces of an enterprise bean.

Listing 8.6 provides complete examples of the usage of the method-permission element.

Listing 8.6. An Example of an ejb-jar.xml Descriptor Fragment That Illustrates method-permission Element Usage

 <ejb-jar>     <assembly-descriptor>         <method-permission>             <description>The employee and temp-employee roles may access any                 method of the EmployeeService bean </description>             <role-name>employee</role-name>             <role-name>temp-employee</role-name>             <method>                 <ejb-name>EmployeeService</ejb-name>                 <method-name>*</method-name>             </method>         </method-permission>         <method-permission>             <description>The employee role may access the findByPrimaryKey,                 getEmployeeInfo, and the updateEmployeeInfo(String) method of                 the AardvarkPayroll bean </description>             <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-params>                     <method-param>java.lang.String</method-param>                 </method-params>             </method>         </method-permission>         <method-permission>             <description>The admin role may access any method of the                 EmployeeServiceAdmin bean </description>             <role-name>admin</role-name>             <method>                 <ejb-name>EmployeeServiceAdmin</ejb-name>                 <method-name>*</method-name>             </method>         </method-permission>         <method-permission>             <description>Any authenticated user may access any method of the                 EmployeeServiceHelp bean</description>             <unchecked/>             <method>                 <ejb-name>EmployeeServiceHelp</ejb-name>                 <method-name>*</method-name>             </method>         </method-permission>         <exclude-list>             <description>No fireTheCTO methods of the EmployeeFiring bean may be                 used in this deployment</description>             <method>                 <ejb-name>EmployeeFiring</ejb-name>                 <method-name>fireTheCTO</method-name>             </method>         </exclude-list>     </assembly-descriptor> </ejb-jar> 

Web Content Security Constraints

In a web application, security is defined by the roles that are allowed access to content by a URL pattern that identifies the protected content. This set of information is declared by using the web.xml security-constraint element (see Figure 8.6).

Figure 8.6. The security-constraint element.

The content to be secured is declared by using one or more web-resource-collection elements. Each web-resource-collection element contains an optional series of url-pattern elements, followed by an optional series of http-method elements. The url-pattern element value specifies a URL pattern against which a request URL must match for the request to correspond to an attempt to access secured content. The http-method element value specifies a type of HTTP request to allow.

The optional user-data-constraint element specifies the requirements for the transport layer of the client-to-server connection. The requirement may be for content integrity (preventing data tampering in the communication process) or for confidentiality (preventing reading while in transit). The TRansport-guarantee element value specifies the degree to which communication between the client and server should be protected. Its values are NONE, INTEGRAL, and CONFIDENTIAL. A value of NONE means that the application does not require any transport guarantees. A value of INTEGRAL means that the application requires the data sent between the client and server to be sent in such a way that it can't be changed in transit. A value of CONFIDENTIAL means that the application requires the data to be transmitted in a fashion that prevents other entities from observing the contents of the transmission. In most cases, the presence of the INTEGRAL or CONFIDENTIAL flag indicates that the use of SSL is required.

The optional login-config element is used to configure the authentication method that should be used, the realm name that should be used for the application, and the attributes that are needed by the form login mechanism (see Figure 8.7).

Figure 8.7. The login-config element.

The auth-method child element specifies the authentication mechanism for the web application. As a prerequisite to gaining access to any web resources that are protected by an authorization constraint, a user must have authenticated using the configured mechanism. Legal values for auth-method element are BASIC, DIGEST, FORM, and CLIENT-CERT. The realm-name child element specifies the realm name to use in HTTP basic and digest authorization. The form-login-config child element specifies the login as well as error pages that should be used in form-based login. If the auth-method value is not FORM, then form-login-config and its child elements are ignored. For example, the web.xml descriptor fragment given in Listing 8.7 indicates that any URL lying under the web application's /restricted path requires an AuthorizedUser role. There is no required transport guarantee, and the authentication method used for obtaining the user identity is basic HTTP authentication.

Listing 8.7. A web.xml Descriptor Fragment That Illustrates the Use of security-constraint and Related Elements

 <web-app>     <!-- ... -->     <security-constraint>         <web-resource-collection>             <web-resource-name>Secure Content</web-resource-name>             <url-pattern>/restricted/*</url-pattern>         </web-resource-collection>         <auth-constraint>             <role-name>AuthorizedUser</role-name>         </auth-constraint>         <user-data-constraint>             <transport-guarantee>NONE</transport-guarantee>         </user-data-constraint>     </security-constraint>     <!-- ... -->     <login-config>         <auth-method>BASIC</auth-method>         <realm-name>The Restricted Zone</realm-name>     </login-config>     <!-- ... -->     <security-role>         <description>The role required to access restricted content </description>         <role-name>AuthorizedUser</role-name>     </security-role> </web-app> 

Enabling Declarative Security in JBoss

The J2EE security elements that have been covered so far describe the security requirements only from the application's perspective. Because J2EE security elements declare logical roles, the application deployer maps the roles from the application domain onto the deployment environment. The J2EE specifications omit these application-server specific details. In JBoss, mapping the application roles onto the deployment environment entails specifying a security manager that implements the J2EE security model, using JBoss server-specific deployment descriptors. The details behind the security configuration are discussed later in this chapter, in the section "The JBoss Security Model."