Develop secured enterprise bean applications

Programmatic security is used by security-aware applications when declarative security alone is not sufficient to express the security model of the application. Programmatic security consists of these steps:

1. Add the required security methods in the EJB module code.
2. Create the security-role-ref element with the role-name field for all the role-names used in the isCallerInRole() method.

For an example, see Example: Enterprise bean applications code.

Add the required security methods

The javax.ejb.EJBContext interface provides these methods that allow the Bean Provider to access security information about the enterprise bean's caller:

• IsCallerInRole(String rolename)
  This method returns true if the bean's caller is granted the specified security role (which is specified by role name). If caller is not granted the specified role or if caller is not authenticated, the method returns false. If the specified role is granted access to everyone, it always returns true.

• getCallerPrincipal()
  This method returns a java.security.Principal object that contains the bean's caller name. If caller is not authenticated, it returns an a principal that contains an unauthenticated name.

Programmatic enterprise bean component security methods, isCallerInRole() and getCallerPrincipal(), can be added inside the business methods of an enterprise bean. The following code snippet is an example of using the programmatic security APIs. A session bean is used in the example:

  public class aSessionBean implements SessionBean {
  ...

    // SessionContext extends EJBContext. If it is entity bean use EntityContext
    javax.ejb.SessionContext context;

    // The following method will be called by the EJB container automatically
    public void setSessionContext(javax.ejb.SessionContext ctx) {
      context = ctx; // save the session bean's context
    }

    ...

    private void aBusinessMethod()  {
      ...

      // to get  bean's caller using getCallerPrincipal()
      java.security.Principal principal = context.getCallerPrincipal();     
      String  callerId= principal.getName();

      // to check if  bean's caller is granted Mgr role
      boolean isMgr = context.isCallerInRole("Mgr");

      // use the above information in any way as needed by the application 
      ...
    }
    ...
  }

Create the security-role-ref element

This step is required to programmatically secure an application. If security-role-ref is not created during development, make sure it is created during assembly stage.

When the isCallerInRole() method is used, a security-role-ref element should be declared in the deployment descriptor with a role-name element that contains the role name that is passed to this method. Since actual roles are created during assembly stage of the application, you can use the logical role as the role name and provide enough hints to the assembly tool in the description of the security-role-ref element to link that role to actual role. During assembly, the assembly tool creates a role-link sub element to link the role-name to actual role. Creation of security-role-ref element is possible if developing tools such as WebSphere Studio Application Developer is used. The security-role-ref element can also be created during assembly stage using assembly tool.

It is strongly recommended that you do not hard code security policies into your applications. You are encouraged to use the J2EE security APIs and declaratively specify your security policies whenever possible. These APIs can be used to develop security-aware enterprise bean applications.

An example where declarative security is useful is when you want an enterprise bean application to access external resources and to control the access to these resources with its own authorization table (external-resource to user mapping). In this case, getCallerPrincipal() can be used to get the caller's identity, and then the application can consult its own authorization table to perform the authorization. The caller identification can also be used to retrieve the corresponding user's information from an external source such as database or from another enterprise bean. The isCallerInRole() method can be used in a similar way.

After you develop the application, you can define a security-role-ref element for the deployment descriptor. Here is an example:

  <security-role-ref>
    <description>Provide hints to assembler for
     linking this role-name to actual role here<\description>
    <role-name>Mgr<\role-name>
  </security-role-ref>

During assembly, the assembly tool creates the role-link element, as shown below:

  <security-role-ref>
    <description>Hints provided by developer to map role-name to role-link</description>
    <role-name>Mgr</role-name>
    <role-link>Manager</role-link>
  </security-role-ref>