49.2.1.1 Specifying Authorized Users by Declaring Security Roles

This section discusses how to use annotations to specify the method permissions for the methods of a bean class. For more information on these annotations, refer to the Common Annotations for the Java Platform specification at http://jcp.org/en/jsr/detail?id=250.

Method permissions can be specified on the class, the business methods of the class, or both. Method permissions can be specified on a method of the bean class to override the method permissions value specified on the entire bean class. The following annotations are used to specify method permissions.

• @DeclareRoles: Specifies all the roles that the application will use, including roles not specifically named in a @RolesAllowed annotation. The set of security roles the application uses is the total of the security roles defined in the @DeclareRoles and @RolesAllowed annotations.

  The @DeclareRoles annotation is specified on a bean class, where it serves to declare roles that can be tested (for example, by calling isCallerInRole) from within the methods of the annotated class. When declaring the name of a role used as a parameter to the isCallerInRole(String roleName) method, the declared name must be the same as the parameter value.

  The following example code demonstrates the use of the @DeclareRoles annotation:

  @DeclareRoles("BusinessAdmin")
  public class Calculator {
      ...
  }
  

  The syntax for declaring more than one role is as shown in the following example:

  @DeclareRoles({"Administrator", "Manager", "Employee"})
  

• @RolesAllowed("list-of-roles"): Specifies the security roles permitted to access methods in an application. This annotation can be specified on a class or on one or more methods. When specified at the class level, the annotation applies to all methods in the class. When specified on a method, the annotation applies to that method only and overrides any values specified at the class level.

  To specify that no roles are authorized to access methods in an application, use the @DenyAll annotation. To specify that a user in any role is authorized to access the application, use the @PermitAll annotation.

  When used in conjunction with the @DeclareRoles annotation, the combined set of security roles is used by the application.

  The following example code demonstrates the use of the @RolesAllowed annotation:

  @DeclareRoles({"Administrator", "Manager", "Employee"})
  public class Calculator {
  
      @RolesAllowed("Administrator")
      public void setNewRate(int rate) {
          ...
      }
  }
  

• @PermitAll: Specifies that all security roles are permitted to execute the specified method or methods. The user is not checked against a database to ensure that he or she is authorized to access this application.

  This annotation can be specified on a class or on one or more methods. Specifying this annotation on the class means that it applies to all methods of the class. Specifying it at the method level means that it applies to only that method.

  The following example code demonstrates the use of the @PermitAll annotation:

  import javax.annotation.security.*;
  @RolesAllowed("RestrictedUsers")
  public class Calculator {
  
      @RolesAllowed("Administrator")
      public void setNewRate(int rate) {
          //...
      }
      @PermitAll
      public long convertCurrency(long amount) {
          //...
      }
  }
  

• @DenyAll: Specifies that no security roles are permitted to execute the specified method or methods. This means that these methods are excluded from execution in the Java EE container.

  The following example code demonstrates the use of the @DenyAll annotation:

  import javax.annotation.security.*;
  @RolesAllowed("Users")
  public class Calculator {
      @RolesAllowed("Administrator")
      public void setNewRate(int rate) {
          //...
      }
      @DenyAll
      public long convertCurrency(long amount) {
          //...
      }
  }
  

The following code snippet demonstrates the use of the @DeclareRoles annotation with the isCallerInRole method. In this example, the @DeclareRoles annotation declares a role that the enterprise bean PayrollBean uses to make the security check by using isCallerInRole("payroll") to verify that the caller is authorized to change salary data:

@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(...);
        }
        ...
    }
    ...
}

The following example code illustrates the use of the @RolesAllowed annotation:

@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 () {...}
    ...
}

In this example, assuming that aMethod, bMethod, and cMethod are methods of business interface A, the method permissions values of methods aMethod and bMethod are @RolesAllowed("HR") and @RolesAllowed("admin"), respectively. The method permissions for method cMethod have not been specified.

To clarify, the annotations are not inherited by the subclass itself. Instead, the annotations apply to methods of the superclass that are inherited by the subclass.

49.2.1.2 Specifying an Authentication Mechanism and Secure Connection

When method permissions are specified, basic user name/password authentication will be invoked by GlassFish Server.

To use a different type of authentication or to require a secure connection using SSL, specify this information in an application deployment descriptor.

49.2.2.1 Accessing an Enterprise Bean Caller's Security Context

In general, security management should be enforced by the container in a manner that is transparent to the enterprise bean's business methods. The security API described in this section should be used only in the less frequent situations in which the enterprise bean business methods need to access the security context information, such as when you want to restrict access to a particular time of day.

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.

  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.

49.2.3.1 Configuring a Component's Propagated Security Identity

You can configure an enterprise bean's run-as, or propagated, security identity by using the @RunAs annotation, which defines the role of the application during execution in a Java EE container. The annotation can be specified on a class, allowing developers to execute an application under a particular role. The role must map to the user/group information in the container's security realm. The @RunAs annotation specifies the name of a security role as its parameter.

The following code demonstrates the use of the @RunAs annotation:

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

You will have to map the run-as role name to a given principal defined in GlassFish Server if the given roles are associated with more than one user principal.

49.2.3.2 Trust between Containers

When an enterprise bean is designed so that either the original caller identity or a designated identity is used to call a target bean, the target bean will receive the propagated identity only. The target bean will not receive any authentication data.

There is no way for the target container to authenticate the propagated security identity. However, because the security identity is used in authorization checks (for example, method permissions or with the isCallerInRole method), it is vitally important that the security identity be authentic. Because no authentication data is available to authenticate the propagated identity, the target must trust that the calling container has propagated an authenticated security identity.

By default, GlassFish Server is configured to trust identities that are propagated from different containers. Therefore, you do not need to take any special steps to set up a trust relationship.