<?xml version="1.0" encoding="UTF-8"?>
<section version="5.0" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:html="http://www.w3.org/1999/xhtml" xmlns:db="http://docbook.org/ns/docbook" xml:lang="en" xml:id="ejb2.security"><info><title>Security Management</title></info>
  
  <section xml:id="ejb2.security.introduction"><info><title>Introduction</title></info>
    
    <para>
      The EJB architecture encourages the Bean programmer to implement the enterprise bean class without hard-coding the security policies and mechanisms into the business methods.
    </para>
  </section>
  <section xml:id="ejb2.security.declarative"><info><title>Declarative Security Management</title></info>
    
    <para>
      The application assembler can define a 
      security view
       of the enterprise beans contained in the ejb-jar file.
       The security view consists of a set of 
      security roles
      . A security role is a semantic grouping of permissions for a given type of application user that allows that user to successfully use the application.
       The application assembler can define (declaratively in the deployment descriptor) 
      method permissions
       for each security role. A method permission is a permission to invoke a specified group of methods for the enterprise beans' home and remote interfaces.
       The security roles defined by the application assembler present this simplified security view of the enterprise beans application to the deployer; the deployer's view of security requirements for the application is the small set of security roles, rather than a large number of individual methods.
    </para>
    <section><info><title>Security roles</title></info>
      
      <para>
        The application assembler can define one or more 
        security roles
         in the deployment descriptor. The application assembler then assigns groups of methods of the enterprise beans' home and remote interfaces to the security roles in order to define the security view of the application.
      </para>
      <para>
        The scope of the security roles defined in the 
        <code>
          security-role
        </code>
         elements is the ejb-jar file level, and this includes all the enterprise beans in the ejb-jar file.
      </para>
      <screen>
   ...
   &lt;assembly-descriptor&gt;
      &lt;security-role&gt;
         &lt;role-name&gt;tomcat&lt;/role-name&gt;
      &lt;/security-role&gt;
      ...
   &lt;/assembly-descriptor&gt;
          </screen>
    </section>
    <section><info><title>Method permissions</title></info>
      
      <para>
        After defining security roles for the enterprise beans in the ejb-jar file, the application assembler can also specify the methods of the remote and home interfaces that each security role is allowed to invoke.
      </para>
      <para>
        Method permissions are defined as a binary relationship in the deployment descriptor from the set of security roles to the set of methods of the home and remote interfaces of the enterprise beans, including all their super interfaces (including the methods of the 
        <code>
          javax.ejb.EJBHome
        </code>
         and 
        <code>
          javax.ejb.EJBObject
        </code>
         interfaces). The method permissions relationship includes the pair 
        (R, M)
         only if the security role 
        R
         is allowed to invoke the method 
        M
        .
      </para>
      <para>
        The application assembler defines the method permissions relationship in the deployment descriptor using the 
        <code>
          method-permission
        </code>
         element as follows:
      </para>
      <itemizedlist>
        <listitem><para>
          Each 
          <code>
            method-permission
          </code>
           element includes a list of one or     more security roles and a list of one or more methods. All the listed     security roles are allowed to invoke all the listed methods. Each     security role in the list is identified by the 
          <code>
            role-name
          </code>
               element, and each method is identified by the 
          <code>
            method
          </code>
             element.
        </para></listitem>
        <listitem><para>
          The method permissions relationship is defined as the union of all the     method permissions defined in the individual     
          <code>
            method-permission
          </code>
           elements.
        </para></listitem>
        <listitem><para>
          A security role or a method can appear in multiple     
          <code>
            method-permission
          </code>
           elements.
        </para></listitem>
      </itemizedlist>
      <para>
        It is possible that some methods are not assigned to any security roles. This means that these methods can be accessed by anyone.
      </para>
      <para>
        The following example illustrates how security roles are assigned to methods' permissions in the deployment descriptor:
      </para>
      <screen>
   ...
   &lt;method-permission&gt;
      &lt;role-name&gt;tomcat&lt;/role-name&gt;
      &lt;method&gt;
         &lt;ejb-name&gt;Op&lt;/ejb-name&gt;
         &lt;method-name&gt;*&lt;/method-name&gt;
      &lt;/method&gt;
   &lt;/method-permission&gt;
   ...
          </screen>
    </section>
  </section>
  <section xml:id="ejb2.security.programmatic"><info><title>Programmatic Security Management</title></info>
    
    <para>
      Because not all security policies can be expressed declaratively, the EJB architecture also provides a simple programmatic interface that the Bean programmer can use to access the security context from the business methods.
    </para>
    <para>
      The 
      <code>
        javax.ejb.EJBContext
      </code>
       interface provides two methods that allow the Bean programmer to access security information about the enterprise bean's caller.
    </para>
    <screen>
public interface javax.ejb.EJBContext {
   ...
   //
   // The following two methods allow the EJB class
   // to access security information
   //
   java.security.Principal getCallerPrincipal() ;
   boolean isCallerInRole (String roleName) ;
   ...
}
        </screen>
    <section><info><title>Use of getCallerPrincipal()</title></info>
      
      <para>
        The purpose of the 
        <code>
          getCallerPrincipal()
        </code>
         method is to allow the enterprise bean methods to obtain the current caller principal's name. The methods might, for example, use the name as a key to access information in a database.
      </para>
      <para>
        An enterprise bean can invoke the 
        <code>
          getCallerPrincipal()
        </code>
         method to obtain a 
        <code>
          java.security.Principal
        </code>
         interface representing the current caller. The enterprise bean can then obtain the distinguished name of the caller principal using the 
        <code>
          getName()
        </code>
         method of the 
        <code>
          java.security.Principal
        </code>
         interface.
      </para>
    </section>
    <section><info><title>Use of isCallerInRole(String roleName)</title></info>
      
      <para>
        The main purpose of the 
        <code>
          isCallerInRole(String roleName)
        </code>
         method is to allow the Bean programmer to code the security checks that cannot be easily defined declaratively in the deployment descriptor 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.
      </para>
      <para>
        The enterprise bean code uses the 
        <code>
          isCallerInRole(String roleName)
        </code>
         method to test whether the current caller has been assigned to a given security role or not. Security roles are defined by the application assembler in the deployment descriptor and are assigned to principals by the deployer.
      </para>
    </section>
    <section><info><title>Declaration of security roles referenced from the bean's code</title></info>
      
      <para>
        The Bean programmer must declare in the 
        <code>
          security-role-ref
        </code>
         elements of the deployment descriptor all the security role names used in the enterprise bean code. Declaring the security roles' references in the code allows the application assembler or deployer to link the names of the security roles used in the code to the actual security roles defined for an assembled application through the 
        <code>
          security-role
        </code>
         elements.
      </para>
      <screen>
   ...
   &lt;enterprise-beans&gt;
      ...
      &lt;session&gt;
         &lt;ejb-nameOp&lt;/ejb-name&gt;
         &lt;ejb-class&gt;sb.OpBean&lt;/ejb-class&gt;
         ...
         &lt;security-role-ref&gt;
            &lt;role-name&gt;role1&lt;/role-name&gt;
         &lt;/security-role-ref&gt;
         ...
      &lt;/session&gt;
      ...
   &lt;/enterprise-beans&gt;
   ...
          </screen>
      <para>
        The deployment descriptor in this example indicates that the enterprise bean 
        <code>
          Op
        </code>
         makes the security checks using 
        <code>
          isCallerInRole("role1")
        </code>
         in at least one of its business methods.
      </para>
    </section>
    <section><info><title>Linking security role references and security roles</title></info>
      
      <para>
        If the 
        <code>
          security-role
        </code>
         elements have been defined in the deployment descriptor, all the security role references declared in the 
        <code>
          security-role-ref
        </code>
         elements must be linked to the security roles defined in the 
        <code>
          security-role
        </code>
         elements.
      </para>
      <para>
        The following deployment descriptor example shows how to link the security role references named 
        <code>
          role1
        </code>
         to the security role named 
        <code>
          tomcat
        </code>
        .
      </para>
      <screen>
   ...
   &lt;enterprise-beans&gt;
      ...
      &lt;session&gt;
         &lt;ejb-name&gt;Op&lt;/ejb-name&gt;
         &lt;ejb-class&gt;sb.OpBean&lt;/ejb-class&gt;
         ...
         &lt;security-role-ref&gt;
            &lt;role-name&gt;role1&lt;/role-name&gt;
            &lt;role-link&gt;tomcat&lt;/role-link&gt;
         &lt;/security-role-ref&gt;
         ...
      &lt;/session&gt;
      ...
   &lt;/enterprise-beans&gt;
   ...
          </screen>
      <para>
        In summary, the role names used in the EJB code (in the isCallerInRole method) are, in fact, references to actual security roles, which makes the EJB code independent of the security configuration described in the deployment descriptor. The programmer makes these role references available to the Bean deployer or application assembler via the 
        <code>
          security-role-ref
        </code>
         elements included in the 
        <code>
          session
        </code>
         or 
        <code>
          entity
        </code>
         elements of the deployment descriptor. Then, the Bean deployer or application assembler must map the security roles defined in the deployment descriptor to the "specific" roles of the target operational environment (e.g. groups on Unix systems). However, this last mapping step is not currently available in JOnAS.
      </para>
    </section>
  </section>
</section>