GeezerVison

Declarative security enables the application developer to specify which users are authorized to access which methods of the enterprise beans and to authenticate these users with basic, or user name/password, authentication. Frequently, the person who is developing an enterprise application is not the same person who is responsible for deploying the application. An application developer who uses declarative security to define method permissions and authentication mechanisms is passing along to the deployer a security view of the enterprise beans contained in the EJB JAR. When a security view is passed on to the deployer, he or she uses this information to define method permissions for security roles. If you don’t define a security view, the deployer will have to determine what each business method does to determine which users are authorized to call each method.

A security view consists of a set of security roles, a semantic grouping of permissions that a given type of users of an application must have to successfully access the application. Security roles are meant to be logical roles, representing a type of user. You can define method permissions for each security role. A method permission is a permission to invoke a specified group of methods of an enterprise bean’s business interface, home interface, component interface, and/or web service endpoints. After method permissions are defined, user name/password authentication will be used to verify the identity of the user.

It is important to keep in mind that security roles are used to define the logical security view of an application. They should not be confused with the user groups, users, principals, and other concepts that exist in GlassFish Server. Note that the Java EE Security API requires that group principal names be mapped to roles of the same name by default, but that implementations of the standard may allow configuration of a different default. In GlassFish Server, you do not need to perform any additional steps to map the roles defined in the application to users, groups, and principals that are the components of the user database in the file realm. This mapping is set by default in the GlassFish Server Administration Console as described in Mapping Roles to Users and Groups.

The following sections show how an application developer uses declarative security to either secure an application or to create a security view to pass along to the deployer.

Specifying Authorized Users by Declaring Security Roles

@DeclareRoles("payroll")
@Stateless public class PayrollBean implements Payroll {
    @Resource SessionContext ctx;

    public void updateEmployeeInfo(EmplInfo info) {

        oldInfo = ... read from database;

        // The salary field can be changed only by callers
        // who have the security role "payroll"
        Principal callerPrincipal = ctx.getCallerPrincipal();
        if (info.salary != oldInfo.salary && !ctx.isCallerInRole("payroll")) {
            throw new SecurityException(...);
        }
        ...
    }
    ...
}

@RolesAllowed("admin")
public class SomeClass {
    public void aMethod () {...}
    public void bMethod () {...}
    ...
}

@Stateless public class MyBean extends SomeClass implements A  {

    @RolesAllowed("HR")
    public void aMethod () {...}

    public void cMethod () {...}
    ...
}

Specifying an Authentication Mechanism and Secure Connection

Programmatic security, code that is embedded in a business method, is used to access a caller’s identity programmatically and uses this information to make security decisions within the method itself.

In general, security management should be enforced by the container in a manner that is transparent to the enterprise bean’s business methods. This section describes the SecurityContext API and security-related methods of the EJBContext API. The newer SecurityContext API duplicates some functions of the EJBContext API because it is intended to provide a consistent API across containers. These security APIs should be used only in the less frequent situations in which the enterprise bean business methods need to access the security context information.

The SecurityContext interface, as specified in the Java EE Security API specification, defines three methods that allow the bean provider to access security information about the enterprise bean’s caller:

• getCallerPrincipal() retrieves the Principal that represents the name of the authenticated caller. This is the container-specific representation of the caller principal, and the type may differ from the type of the caller principal originally established by an HttpAuthenticationMechanism. This method returns null for an unauthenticated caller. Note that this behavior differs from the behavior of the EJBContext.getCallerPrincipal() method, which returns a (vendor-specific) special principal to represent an anonymous caller.

• getPrincipalsByType() retrieves all principals of the given type from the authenticated caller’s Subject. This method returns an empty Set if the caller is unauthenticated, or if the requested type is not found.

  Where both a container caller principal and an application caller principal are present, the value returned by getName() is the same for both principals.

• isCallerInRole() takes a String argument that represents the role to be tested. The specification does not define how the role determination is made, but the result must be the same as if the corresponding container-specific call had been made (for example EJBContext.isCallerInRole()), and must be consistent with the result implied by specifications that prescribe role-mapping behavior.

The javax.ejb.EJBContext interface provides two methods that allow the bean provider to access security information about the enterprise bean’s caller.

• getCallerPrincipal allows the enterprise bean methods to obtain the current caller principal’s name. The methods might, for example, use the name as a key to information in a database. This method never returns null. Instead, it returns a (vendor-specific) principal with a special username to indicate an anonymous/unauthenticated caller. Note that this behavior differs from the behavior of the SecurityContext.getCallerPrincipal() method, which returns null for an unauthenticated caller.

  The following code sample illustrates the use of the getCallerPrincipal method:

  @Stateless public class EmployeeServiceBean implements EmployeeService {
      @Resource SessionContext ctx;
      @PersistenceContext EntityManager em;
  
      public void changePhoneNumber(...) {
          ...
          // obtain the caller principal
          callerPrincipal = ctx.getCallerPrincipal();
  
          // obtain the caller principal's name
          callerKey = callerPrincipal.getName();
  
          // use callerKey as primary key to find EmployeeRecord
          EmployeeRecord myEmployeeRecord =
              em.find(EmployeeRecord.class, callerKey);
  
          // update phone number
          myEmployeeRecord.setPhoneNumber(...);
  
          ...
      }
  }

  In this example, the enterprise bean obtains the principal name of the current caller and uses it as the primary key to locate an EmployeeRecord entity. This example assumes that application has been deployed such that the current caller principal contains the primary key used for the identification of employees (for example, employee number).

• isCallerInRole allows the developer to code the security checks that cannot be easily defined using method permissions. Such a check might impose a role-based limit on a request, or it might depend on information stored in the database.

  The enterprise bean code can use the isCallerInRole method to test whether the current caller has been assigned to a given security role. Security roles are defined by the bean provider or the application assembler and are assigned by the deployer to principals or principal groups that exist in the operational environment.

  The following code sample illustrates the use of the isCallerInRole method:

  @Stateless public class PayrollBean implements Payroll {
       @Resource SessionContext ctx;
  
       public void updateEmployeeInfo(EmplInfo info) {
  
           oldInfo = ... read from database;
  
           // The salary field can be changed only by callers
           // who have the security role "payroll"
           if (info.salary != oldInfo.salary &&
               !ctx.isCallerInRole("payroll")) {
                   throw new SecurityException(...);
           }
           ...
       }
       ...
   }

You would use programmatic security in this way to dynamically control access to a method, for example, when you want to deny access except during a particular time of day. An example application that uses the getCallerPrincipal and isCallerInRole methods is described in The converter-secure Example: Securing an Enterprise Bean with Programmatic Security.

You can specify whether a caller’s security identity should be used for the execution of specified methods of an enterprise bean or whether a specific run-as identity should be used. Figure 52-1 illustrates this concept.

In this illustration, an application client is making a call to an enterprise bean method in one EJB container. This enterprise bean method, in turn, makes a call to an enterprise bean method in another container. The security identity during the first call is the identity of the caller. The security identity during the second call can be any of the following options.

• By default, the identity of the caller of the intermediate component is propagated to the target enterprise bean. This technique is used when the target container trusts the intermediate container.

• A specific identity is propagated to the target enterprise bean. This technique is used when the target container expects access using a specific identity.

To propagate an identity to the target enterprise bean, configure a run-as identity for the bean, as described in Configuring a Component’s Propagated Security Identity. 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 that the enterprise bean will use when it makes calls.

The run-as identity applies to the enterprise bean as a whole, including all the methods of the enterprise bean’s business interface, local and remote interfaces, component interface, and web service endpoint interfaces, the message listener methods of a message-driven bean, the timeout method of an enterprise bean, and all internal methods of the bean that might be called in turn.

Configuring a Component’s Propagated Security Identity

@RunAs("Admin")
public class Calculator {
    //....
}

Trust between Containers

The deployer is responsible for ensuring that an assembled application is secure after it has been deployed in the target operational environment. If a security view has been provided to the deployer through the use of security annotations and/or a deployment descriptor, the security view is mapped to the mechanisms and policies used by the security domain in the target operational environment, which in this case is GlassFish Server. If no security view is provided, the deployer must set up the appropriate security policy for the enterprise bean application.

Deployment information is specific to a web or application server.