# Example for using security in JOnAS with Tomcat

In the JOnAS distribution, there is an example named `earsample`, showing how to use the security. This chapter describes in more details this example, in order to illustrate how the security capabilities of JOnAS should be used. The example is a session bean whose methods are protected. The user calling this bean must be authorized to access these methods.

Since there is at the present time no authentification in JOnAS, we rely on Tomcat to make the identification and authentification steps.

To run the `earsample` example, see in the More complex examples section in the "Getting Started" chapter of the JOnAS documentation.

## Example Description

This example shows how to access an EJB whose methods are protected.

1. The user must identify and authenticate herself.
   We rely on Tomcat to do these steps.
2. Once done, she has access to a servlet in Tomcat.
   This servlet calls some methods of the EJB with a security context in which the identity of the user approved by Tomcat is kept (this identity is called a principal).
3. The security service of JOnAS checks if the principal of the user is authorized to access the called method of the EJB.
4. If the access is allowed, the method is normally executed, else an exception is sent back to the servlet which informs the user.

## Setting up of the example

In order to make this example convenient to run, all the deployment phase is hidden. Now we will have a closer look of what is needed to set up a secured EJB in JOnAS.

### Setting up of Tomcat

To run this example, the first thing to do is to configure Tomcat since JOnAS relies on it to identify and authenticate the user of a servlet.

This is done in two steps:

1. The first one is to protect the access to the servlet so that the user has to identify and authenticate prior to access the servlet.
   In order to do that, we have to modify the web.xml file. This file contains information relative to the web application. Among it, there is the protected access to the servlets. What is interesting concerning security is the following one:

       ...
       <security-constraint>
          <web-resource-collection>
             <web-resource-name>Protected Area</web-resource-name>
             <url-pattern>/secured/*</url-pattern>
             ...
          </web-resource-collection>
          <auth-constraint>
             <role-name>tomcat</role-name>
             ...
          </auth-constraint>
       </security-constraint>
       <login-config>
          <auth-method>BASIC</auth-method>
          <realm-name>Example Basic Authentication Area</realm-name>
       </login-config>
       ...

   This means that:
   - All URLs of the form `http://<hostname>:<port>/earsample/secured/...` are protected.
   - Only the `tomcat` role can access these URLs.
   - The login configuration is `BASIC`, that is to say that a dialog box will be opened when you will access these URLs, asking you to enter an User ID and a password.
2. We have to define who is in the role `tomcat`.
   This is specified in the `tomcat-users.xml` file located in your `$CATALINA_HOME/conf/` directory for Tomcat 4.1.x.
   This file contains:

       <tomcat-users>
         <user name="tomcat" password="tomcat" roles="tomcat" />
         ...
       </tomcat-users>

   This means that the user with the name (or User ID) `tomcat` is in the role `tomcat` and is authentified thanks to the password `tomcat`.
3. Then, we must indicate to tomcat to use a JOnAS AccessInterceptor in order to make the propagation of security context mechanism available.
   - For Tomcat 4.1.x, this is done by updating the `$CATALINA_HOME/conf/server.xml` file.
     Replace the line:
     `<Realm className="org.apache.catalina.realm.UserDatabaseRealm" debug="0" resourceName="UserDatabase"/>`
     by
     `<Realm className="org.objectweb.security.catalina41.realm.UserDatabaseRealm" debug="0" resourceName="UserDatabase"/>` or `<Realm className="org.objectweb.security.catalina41.realm.MemoryRealm" debug="0"/>` or another `org.objectweb.security.catalina41.realm.*` class

### Setting up JOnAS

Now, let's take a look on how to configure the security in JOnAS (More details are provided in the Security Management section of the JOnAS documentation).
It is very similar to the setting up of Tomcat. It includes the following steps:

1. Define which methods of the EJB are protected and who can access them, this is done in the standard deployment descriptor of the EJB (the `ejb-jar.xml` file).

       <ejb-jar>
          ...
          <session>
             <ejb-name>Op</ejb-name>
             ...
          </session>
          ...
           <assembly-descriptor>
           <security-role>
             <role-name>tomcat</role-name>
           </security-role>
           <method-permission>
             <role-name>tomcat</role-name>
             <method>
       	<ejb-name>Op</ejb-name>
       	<method-name>*</method-name>
             </method>
           </method-permission>
           ...
          </assembly-descriptor>
       </ejb-jar>

   This means that:
   - a role `tomcat` is defined.
   - this role can access all the methods of the `Op` session bean (`*` is a shortcut to indicate all the methods of the EJB).
2. Now, we have to indicate to JOnAS who can be in the `tomcat` role.
   This is done in the jonas-users.properties file:

       tomcat = tomcat

   This file is very similar to the `tomcat-users.xml` file (even if it is a properties file and not an XML file). It stipulates that the tomcat `name` (on the left side of `=`) is in the tomcat `role` (on the right side).
   More generally, a name may be in several roles which are all on the right side separated by commas.
   However, there is only one name on the left side. That is to say if two users are in the same role, they have to be on two lines and not on one only.
   Conversely to the `tomcat-users.xml` file, there is no password since JOnAS is not currently able to authenticate user.

## Some warnings...

In this example, there are some notions to well understand:

- the `tomcat` role defined on the `tomcat-users.xml` file is local to Tomcat. It is used to authorize access to the servlet.
- the `tomcat` role defined on the `jonas-users.properties` file is local to JOnAS. It is used to authorize access to the methods of the bean.
  We have used the same name, `tomcat` for both, for convenience but it was not mandatory.
- the names defined in the `tomcat-users.xml` and `jonas-users.properties` files must be the same.
  Indeed the bean is considering the servlet as its client so that the name of the client in the servlet must be used to control access of the bean.

## Don't forget...

Using security differs depending on we use Jeremie or RMI (see Configuring Security)

- With Jeremie all we have to do is to provide a jonathan.xml file in which the properties relative to the security must be set
- With RMI the bean must be deployed in a special way, by using the `-secpropag` option of GenIC tool