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.

The user must identify and authenticate herself.
We rely on Tomcat to do these steps.
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).
The security service of JOnAS checks if the principal of the user is authorized to access the called method of the EJB.
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:

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.
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.
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:

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).

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