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. If you'd like more information on these annotations, refer to JSR-250 Common Annotations for the Java Platform.

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

  This annotation is used to specify all of the roles that will be used by the application, including roles not specifically named in a RolesAllowed annotation. The set of security roles used by the application 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.

  Here is some example code that demonstrates the use of the DeclareRoles annotation.

  @DeclareRoles("BusinessAdmin")
  public class Calculator {
  	public void convertCurrency() {
  		if(x.isUserInRole("BusinessAdmin")) {
  			//....
  		}
  	}
  	//...
  }

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

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

• @RolesAllowed("list-of-roles")

  The @RolesAllowed annotation specifies the security roles permitted to access method(s) in an application. This annotation can be specified on a class or on method(s). When specified at the class level, it applies to all methods in the class. When specified on a method, it applies to that method only, and overrides any values specified at the class level.

  To specify that no roles are authorized to access method(s) 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 are used by the application.

  Here is some example code that demonstrates the use of the RolesAllowed annotation.

  @RolesAllowed("AllUsers")
  public class Calculator {
  	@RolesAllowed("Administrator")
  	public void setNewRate(int rate) {
  	//..
  }

• @PermitAll

  The @PermitAll annotation specifies that all security roles are permitted to execute the specified method(s). The user is not checked against a database to ensure that this user is authorized to access this application.

  This annotation can be specified on a class or on method(s). 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.

  Here is some example code that 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

  The @DenyAll annotation specifies that no security roles are permitted to execute the specified method(s). This means that these methods are excluded from execution in the Java EE container.

  Here is some example code that 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) {
  		//...
  	}
  }

Example 24–1 Declaring Roles using @DeclareRoles

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 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"
        if (info.salary != oldInfo.salary &&
            !ctx.isCallerInRole("payroll")) {
                throw new SecurityException(...);
        }
        ...
    }
    ...
}

Example 24–2 Declaring Roles using @RolesAllowed

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 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 per se, they apply to methods of the superclass which are inherited by the subclass.

Mapping Security Roles to Enterprise Server Groups

The Enterprise Server assigns users to principals or groups, rather than to security roles. When you are developing a Java EE application, you don’t need to know what categories of users have been defined for the realm in which the application will be run. In the Java EE platform, the security architecture provides a mechanism for mapping the security roles defined in the application to the users, principals, or groups defined in the runtime realm. The deployer will work with the security view provided by the application developer to implement this mapping.

One way to declare a mapping between a security role used in the application and one or more groups and/or principals defined for the applicable realm of the Enterprise Server is to use the security-role-mapping element in the runtime deployment descriptor (sun-application.xml, sun-web.xml, or sun-ejb-jar.xml.) This is the method to use when the role name defined in the application does not match the group or principal name defined for the Enterprise Server. An example of this role mapping can be found in Part VII, Security, in The Java EE 6 Tutorial, Volume II.

In the tutorial, the role names used in the application are the same as the group names defined on the Enterprise Server. Under these circumstances, you can enable a default principal-to-role mapping on the Enterprise Server using the Admin Console. To enable the default principal-to-role-mapping, follow these steps:

1. Start the Enterprise Server, then the Admin Console.

2. Expand the Configuration node.

3. Select the Security node.

4. On the Security page, check the Enabled box beside Default Principal to Role Mapping.