Roles are defined within an application in one of two ways: using the @DeclareRoles annotation and the @RolesAllowed annotation. In this recipe we will detail the @DeclareRoles annotation while the @RolesAllowed annotation will be introduced but developed further in the Controlling security using declarations recipe.
The two basic steps used to configure roles involve:
- Using the @DeclareRoles annotation to specify the roles used by the class
- Adding the @RolesAllowed annotation to restrict access to methods
The @DeclareRoles annotation, as its name implies, declares the roles used by the application and is applied at the class level. That is, these are the roles to be used with the annotated EJB. The annotation can only be used once per class.
The @RolesAllowed annotation is used to specify which methods are accessible by the roles declared within the annotation. If the roles listed in this annotation are not found in the @DeclareRoles annotation, the roles are automatically declared.
The @DeclareRoles annotation simply declares roles to be used by the EJB. This annotation can only be used at the class level. It does not specify any permission granted for the class or methods within the class.
The annotation takes either a single string argument or an array of string arguments. The following first example declares a single role while the second specifies two roles for a class.
@DeclareRoles ("employee")
@DeclareRoles ({"employee", "manager"})
Add the second @DeclareRoles annotation example to the VoucherManager class.
@Stateful
@DeclareRoles ({"employee", "manager"})
public class VoucherManager {
...
}
Execute the application. You should not see any difference in its behavior.
Next, add a @RolesAllowed("employee") annotation to the VoucherManager's submit method.
@Stateful
@DeclareRoles ({"employee", "manager"})
public class VoucherManager {
...
@RolesAllowed("employee")
public void submit() {
System.out.println("Voucher submitted");
}
...
}
This annotation will be elaborated upon in the next recipe. However, the use of the annotation restricts use of the method to only those users who are members of the employee role.
Execute the application. Since we are using basic authentication (see Configuring the server to handle security recipe) you should be prompted to log on. Use "sally" as the username and "password" as the password. The following screenshot illustrates the dialog box used by GlassFish.
The output of the application should appear as shown in the following screenshot:
The @RolesAllowed annotation restricted access to the submit method to only those users belonging to the employee role. An exception was thrown otherwise. Since we were using basic authentication, the server-provided login dialog box was used.
Note, if you resubmit the request, the user is not prompted for a name or password. If you want to force the use of the login again, the HttpSession's invalidate method or HttpServletRequest's logout method can be used to close a session. However, this does not always work in a testing environment and frequently it is necessary to close the browser and open it up again to force the authentication of a user.