...

context.isCallerInRole(roleRefMe);

...

Since roles are defined at the module level, they are likely to be unknown at the time this component-level code is written. Therefore, the code uses a security role reference (roleRefMe) which is later mapped to an actual security role. You perform this mapping on the Edit Servlet dialog. Open this dialog by selecting a servlet that uses a role reference on the Servlet Property Editor and clicking Edit. FIGURE 8-4 shows this dialog, with the reference roleRefMe mapped to the role Me.

 FIGURE 8-4 Web Module's Edit Servlet Dialog Box

Notice that roles must be declared at the module level before you can perform this type of mapping.

---

EJB Module Security

Suppose you are a component provider. You have developed several enterprise beans that accesses human resources data and you are assembling them into an EJB module. You probably know which data should be available to all employees for maintenance of their personal information, and which data should be accessed only by human resources clerical roles, by human resources supervisory roles, by auditing roles, and so on.

As the component provider and initial module assembler, you can set up generic security roles that represent these roles and map them to the methods that access those data. These generic roles can later be mapped to the actual user and group names in the deployment environment. (This second mapping can be done at the application level, perhaps when the application is assembled, or perhaps later, when the application is deployed into the production environment.)

On another project, you are the component provider and the initial module assembler but you have no idea how security should be applied to your business logic. In these cases, you can defer setting up security to a later stage of the development process. For example, the application assembler can work with module-level security before assembling the modules into an application.

Setting up security for EJB modules consists of mapping security roles to enterprise bean methods. To do this you need to:

1. Declare generic security roles that represent the categories of users that can use the module's services.

2. Map these security roles to the module's enterprise bean methods. This determines which roles are allowed to access which methods.

3. If the module contains enterprise beans that use the programmatic security feature, map the security role references used in these enterprise beans to security roles.

The sections that follow explain how to perform these assembly tasks.

Declaring Security Roles

You declare security roles on the Edit Module Role dialog. (To open this dialog, right-click on the module node, and then choose the following sequence from the contextual menu: Properties Security Roles ellipsis (...) button. When the Security Roles Property Editor opens, click the Edit Module Roles button.)

FIGURE 8-5 shows the Edit Module Role dialog after two roles have been declared, Me and EveryoneElse.

 FIGURE 8-5 EJB Module's Security Roles Property Editor

Mapping Security Roles to Method Permissions

After declaring security roles for the module, you can give each role permission to execute a specific subset of the enterprise beans in the module. You do this on the Method Permissions Property editor. (To open this property editor, you work with the included EJB nodes. There are the subnodes of the EJB module.)

Right-click a node that represents an enterprise beans included in the module, and then choose the following sequence from the contextual menu: Properties Method Permissions ellipsis (...) button.) The property editor is a table, with a row for each of the enterprise bean's methods and a column for each security role that has been declared for the module. FIGURE 8-6 shows how the property editor looks with the two security roles declared in the preceding section.

 FIGURE 8-6 EJB Module's Method Permissions Property Editor

There are a number of ways to use this dialog.

• The buttons in the upper panel let you apply permissions globally. You can let anyone call any method, or deny all access.
• A finer focus of control is available if you choose Set Roles for Access to All Methods. You can use the small table below the button to choose among the roles declared for the module. If you put a check in a column, a role will be given permission to execute all of the enterprise bean's methods. In FIGURE 8-6, the EveryoneElse column was checked. As a result, users with this role can execute any of the enterprise bean's methods. The Me column was not checked, and users with this role cannot execute any of the enterprise bean's methods.
• The finest focus of control is available when you work in the lower table. Click in a row, and you can set permission for just one method. This setting is entirely independent of the settings for other methods. For example, you could click in the second row, for getAllItems, and set Access field to All Users. This lets any role execute this method. You could then move to another row, set the Access field to Set Role, and then select roles individually for that method.

This buttons below this table provide several shortcuts for editing in the table.

Programmatic Security

If any of the enterprise beans in your module use programmatic security, you need to map the security references used in the security-checking code to the security roles declared at the module level.

Enterprise beans that use the programmatic security feature contain code that accesses the user's credential directly and perform verification beyond that which is performed by the container's declarative security mechanism. For example:

... context.isCallerInRole(everyOne); ...

Since security roles are defined at the module level, they are likely to be unknown at the time this enterprise bean code is written. Therefore, the code uses a security role reference (everyOne) which is mapped to an actual security role when you add the enterprise bean to a module. The role must be declared as a property of the enterprise bean. FIGURE 8-7 shows a role declared on an enterprise bean's Security Role Reference property editor. The role is unlinked.

 FIGURE 8-7 Enterprise Bean's Security Role Reference Property Editor

In this case, this role reference is mapped to a role at the module level. You perform this mapping on the module's Security Roles Property Editor. When you open this editor is shows all security role references in the module and indicates whether they are linked or unlinked. FIGURE 8-8 shows the editor with the everyOne reference still unlinked.

 FIGURE 8-8 EJB Module's Security Role References Property Editor

[ D ]

To map a reference, click in Security Role Link field and select a role. FIGURE 8-9 shows the property editor after the everyOne link has been mapped.

 FIGURE 8-9 EJB Module's Security Role Reference Property Editor

[ D ]

---

J2EE Application Security

The application assembler can find a newly assembled application in one of several states:

• If security roles were not defined for one or more modules in your application, you need to define roles at the module level. See the preceding sections on web module and EJB module security.
• If security was set up at the module level with generic roles, similar roles may have been given different names in different modules. When this is true you need to map all equivalent roles to the same application-level role.
• If the component providers who set up security at the module level knew the deployment environment, and the module-level roles map to each other, you might not need to do any additional mapping.

If additional mapping is needed, you do it on the application's Security Roles property editor. (To open this editor, right-click on the application node, and then choose the following sequence from the contextual menu: Properties Security Roles ellipsis (...) button.) FIGURE 8-10 shows this editor with security roles defined at the module level.

 FIGURE 8-10 J2EE Application's Security Roles Property Editor

[ D ]

The security roles declared at the module level appear in the first two columns of the dialog. Each role is identified by its module and name. For each module-level role, the IDE creates a default application-level role, which has the same name as the module-level role. The application-level roles are displayed in the Equivalent To column.

There are two ways to resolve role discrepancies with this editor. The example in FIGURE 8-10 shows an application with two modules. Each module has two security roles. There is one discrepancy; the web module has a role named myself and the EJB module has a role named Me. These roles are equivalent, so you would like to have only one application-level role. In the figure, this discrepancy was resolved by remapping the role myself to the role Me. What is actually happening here is that both module-level roles, Me and myself, have been mapped to the same application-level role, Me.

You can also create an entirely new role at the application level and map several module-level roles to it. Suppose one of the modules in your applications has a role named sa, and the other has a role named sadmin. You decide to resolve this discrepancy by creating a new application-level role named sysadmin. To do this click the "Edit Application Roles" button. This opens a dialog in which you can declare application-level roles.

After declaring the sysadmin role, you return to the Security Roles Property Editor. Remap both of the module-level roles by clicking in their "Equivalent To" column. This will display the application-level roles. Select the sysadmin role.