3.5. Configuring JOnAS Services

3.5.1. Configuring the Registry Service

The registry service is used for accessing the RMI registry, CMI registry, or CosNaming (iiop), depending on the configuration of communication protocols specified in carol.properties. (refer to Section 3.3 Configuring the Communication Protocol and JNDI.)

There are several Registry-launching modes based on the value of the JOnAS property jonas.service.registry.mode. The possible values of this property are:

The port number on which the Registry is launched is defined in the carol.properties file.

3.5.2. Configuring the EJB Container Service

The EJB Container service is the primary JOnAS service. It provides EJB containers for EJB components.

You can create an EJB container from an EJB-JAR file in the following ways:

• The corresponding EJB-JAR file name is listed in the jonas.service.ejb.descriptors property in the jonas.properties file. If the file name does not contain an absolute path, it should be located in the $JONAS_BASE/ejbjars/ directory. The container is created when the JOnAS server starts.

  Example:

  jonas.service.ejb.descriptors Bank.jar

  In this example the Container service creates a container from the EJB-JAR file named Bank.jar. JOnAS will search for this file in the $JONAS_BASE/ejbjars/ directory.

• To automatically create an EJB container at server start-up time, place the EJB-JAR files in an autoload directory. The name of this directory is specified using the jonas.service.ejb.autoloaddir property in the jonas.properties file.

JOnAS also allows for loading unpacked EJB components. The name of the xml file containing the EJB's deployment descriptor must be listed in the jonas.service.ejb.descriptors property. Note that the JOnAS server must have access to the component's classes, which may be achieved using the XTRA_CLASSPATH environment variable (refer to Chapter 5 JOnAS Class Loader Hierarchy).

3.5.3. Configuring the WEB Container Service

The WEB Container service provides WEB containers for the WEB components used in the J2EE applications. JOnAS provides an implementation of the WEB Container service for Tomcat 5.0.x.

A WEB container is created from a WAR file. If the file name does not contain an absolute path name, it must be located in the $JONAS_BASE/webapps/ directory.

JOnAS can create WEB containers when the JOnAS server starts by providing the corresponding file names via the jonas.service.web.descriptors property in the jonas.properties file.

Example:

jonas.service.web.descriptors  Bank.war

In this example the WEB Container service creates a container from the WAR file named Bank.war. It searches for this file in the $JONAS_BASE/webapps/ directory.

By using webapp directories instead of packaging a new WAR file each time, you can improve the development process. You can replace the classes with the new compiled classes, reload the servlets in your browser, and immediately see the changes. This is also true for the JSPs. Note that these reload features can be disabled in the configuration of the Tomcat web container at production time.

Example of using the jonasAdmin/ webapp directory instead of jonasAdmin.war.

1. In the JONAS_BASE/webapps/autoload directory, create a directory (for example, jonasAdmin): JONAS_BASE/webapps/autoload/jonasAdmin

2. Move the jonasAdmin.war file to this directory.

3. Unpack the WAR file to the current directory, then remove the WAR file.

4. At the next JOnAS startup, the webapp directory is used instead of the WAR file. Change the JSP and see the changes at the same time.

3.5.4. Configuring the WebServices Service

#...
# the fully qualifier name of the service class
jonas.service.ws.class org.objectweb.jonas.ws.AxisWSServiceImpl
#...

#...
# a list of comma separated WSDL Handlers
    jonas.service.ws.wsdlhandlers file1
# Configuration of the file WSDL Handler
    jonas.service.ws.file1.type file
# Make sure users who run JOnAS have read/write access in this directory
    jonas.service.ws.file1.location /path/to/directory/where/store/wsdls
#...

3.5.5. Configuring the EAR Service

The EAR service allows deployment of complete J2EE applications (including both EJB-JAR and WAR files packed in an EAR file). This service is based on the WEB container service and the EJB container service. The WEB container service is used to deploy the WARs included in the J2EE application; the EJB container service is used to deploy the EJB containers for the EJB-JARs included in the J2EE application.

This service may be configured by setting the jonas.service.ear.descriptors property in jonas.properties file. This property provides a list of ears that must be deployed when JOnAS is launched.

When using relative paths for EAR file names, the files should be located in the $JONAS_BASE/apps/ directory.

Example:

jonas.service.ear.descriptors  Bank.ear

In this example the EAR service will deploy the EAR file named Bank.ear. It will search for this file in the $JONAS_BASE/apps/ directory.

3.5.6. Configuring the Transaction Service

The Transaction service is used by the Container service in order to provide transaction management for EJB components as defined in the deployment descriptor. This is a mandatory service.

The Transaction service uses a Transaction manager that may be local or may be launched in another JVM (a remote Transaction manager). Typically, when there are several JOnAS servers working together, one Transaction service must be considered as the master and the others as slaves. The slaves must be configured as if they were working with a remote Transaction manager.

The following is an example of the configuration for two servers: one named TM in which a standalone Transaction service will be run, one named EJB that will be used to deploy an EJB container:

jonas.name                 TM
jonas.services             jtm
jonas.service.jtm.remote   false

and

jonas.name                      EJB
jonas.services                  jmx,security,jtm,dbm,ejb
jonas.service.jtm.remote        true
jonas.service.ejb.descriptors   foo.jar

Another possible configuration option is the value of the transaction time-out, in seconds, via the jonas.service.jtm.timeout property.

The following is the default configuration:

jonas.service.jtm.timeout   60

3.5.7. Configuring the Database Service

	Note
	The description of the new JDBC Resource Adapters as a replacement for the database service is located in Chapter 40 Configuring JDBC Resource Adapters.

To allow access to one or more relational databases (for example, Oracle, PostgreSQL, and so on), JOnAS will create and use DataSource objects. Such a DataSource object must be configured according to the database that will be used for the persistence of a bean. More details about DataSource objects and their configuration are provided in Chapter 4 Configuring JDBC DataSources.

The following subsections briefly explain how to configure a DataSource object for your database in order to be able to run the Entity Bean example.

Note that the SQL requests sent to the database can be easily traced using the JOnAS Logging system and the integrated P6Spy tool. The configuration steps are described in Section 4.4 Tracing SQL Requests Through P6Spy.

jonas.service.dbm.datasources      Oracle1

jonas.service.dbm.datasources      Oracle1, Oracle2

sqlplus user/passwd
    SQL> @Account.sql
    SQL> quit

3.5.8. Configuring the Security Service

The Security service is used by the Container service to provide security for EJB components. The Container service provides security in two forms: declarative security and programmatic security. The Security service uses security roles and method permissions located in the EJB deployment descriptor.

Note that:

• JOnAS relies on Tomcat (http://jakarta.apache.org/tomcat) for the identification of the web clients. The Java clients use the JAAS login modules for the identification. JOnAS performs the user authentication.

  In the $JONAS_ROOT/conf/jonas-realm.xml file you can define three types of Realm for JOnAS:

  • Memory realm: users, groups, and roles are written in the file in the section <jonas-memoryrealm> of the $JONAS_ROOT/conf/jonas-realm.xml file.

  • Datasource realm: users, groups, and roles information is stored in a database; the configuration for accessing a specific datasource is described in the section <jonas-dsrealm> of the $JONAS_ROOT/conf/jonas-realm.xml file.

    The configuration requires the name of the datasource, the tables used, and the names of the columns.

  • LDAP realm: users, groups, and roles information is stored in an LDAP directory. This is described in the section <jonas-ldaprealm> of the $JONAS_ROOT/conf/jonas-realm.xml file.

    There are some optional parameters. If they are not specified, some of the parameters are set to a default value. That is, if the providerUrl element is not set, the default value is ldap://localhost:389.

    Edit the jonas-realm_1_0.dtd DTD file to see the default values.

  For Tomcat, use the realm: org.objectweb.jonas.security.realm.web.catalina50.JACC

  These realms require as an argument the name of the resource to be used for the authentication. This is the name that is in the jonas-realm.xml file.

• There is no mapping for the security between JOnAS and the target operational environment. More specifically, the roles defined for JOnAS cannot be mapped to roles of the target operational environment (for example, groups).

There is one property in the jonas.properties file for configuring the security service: the jonas.security.propagation property should be set to true (which is the default value) to allow the security context to propagate across method calls. Refer to Section 3.3.2 Security and Transaction Context Propagation.

<Realm className="org.objectweb.jonas.security.realm.web.catalina50.JACC"
        debug="99" resourceName="memrlm_1"/>
   

<Realm className="org.objectweb.jonas.security.realm.JRealmCatalina41" \
   debug="0" resourceName="memrlm_1" />

<assembly-descriptor>
    <security-role>
        <role-name>jonas</role-name>
    </security-role>
    <method-permission>
        <role-name>jonas</role-name>
        <method>
            <ejb-name>Bean</ejb-name>
            <method-name>*</method-name>
        </method>
    </method-permission>
    ...
    ...
</assembly-descriptor> 

<roles>
    <role name="jonas" description="Role used in
      the sample security howto" />
</roles>

<users>
    <user name="jonas_user" password="jonas_password" roles="jonas" />
</users>

<jonas-memoryrealm>
  [...]
  <memoryrealm name="howto_memory_1">
    <roles>
      <role name="jonas" description="Role used in
        the sample security howto" />
    </roles>
    <users>
      <user name="jonas_user" password="jonas_password" roles="jonas" />
    </users>
  </memoryrealm>
  [...]
</jonas-memoryrealm>

...          ...
jonas_user   jonas_password
...          ...

...          ...
jonas_user   jonas
...          ...

<jonas-dsrealm>
    [...]
    <dsrealm name="howto_datasource_realm1"
        dsName="jdbc_1"
        userTable="realm_users" userTableUsernameCol="user_name" 
            userTablePasswordCol="user_pass"
        roleTable="realm_roles" roleTableUsernameCol="user_name" 
            roleTableRolenameCol="role_name"
      />
    [...]
</jonas-dsrealm>

# jonas_user, people, jonas, objectweb, org
dn: uid=jonas_user,ou=people,dc=jonas,dc=objectweb,dc=org
objectClass: inetOrgPerson
uid: jonas_user
sn: jonas_user
cn: JOnAS user
userPassword:: jonas_password

# jonas, groups, jonas, objectweb, org
dn: cn=jonas,ou=groups,dc=jonas,dc=objectweb,dc=org
objectClass: groupOfUniqueNames
uniqueMember: uid=jonas_user,ou=people,dc=jonas,dc=objectweb,dc=org
cn: jonas

<jonas-ldaprealm>
  [...]
  <ldaprealm name="howto_ldap_realm1"
                 baseDN="dc=jonas,dc=objectweb,dc=org" />
  [...]
</jonas-ldaprealm>

3.5.8.3. Configuring Client Authentication Based on the Client Certificate in the Web Container

3.5.8.3.1. Introduction

In order to set up the client authentication based on client certificate in a Web container, do the following:

1. Configure the Realm the Web container will have to use.

2. Configure an SSL listener on the Web container.

3. Configure the Web application to make it ask a client certificate.

4. Configure the JAAS LoginModules.

5. Populate the Realm access list.

It is mandatory to possess a X.509 certificate for your Web container on each external interface (IP address) that accepts secure connections. This one can be digitally signed by a Certification Authority or can be autosigned.

3.5.8.3.2. Step 1: Configure the Realm the Web Container Uses

With Tomcat 5.0.x, in the $JONAS_ROOT/conf/server.xml file, the $JONAS_BASE/conf/server.xml file, the $CATALINA_HOME/conf/server.xml file, or the $CATALINA_BASE/conf/server.xml file, replace the current Realm by the following:

<Realm className="org.objectweb.jonas.security.realm.web.catalina50.JAAS" />

The class specified uses the JAAS model to authenticate the users. Thus, to choose the resource in which to look for authentication data, configure JAAS.

3.5.8.3.3. Step 2: Configure an SSL Listener on the Web Container

Uncomment the following section in the server.xml file:

<Connector className="org.apache.catalina.connector.http.HttpConnector" port="9043" minProcessors="5" maxProcessors="75" enableLookups="true" acceptCount="10" debug="0" scheme="https" secure="true"> <Factory className="org.apache.catalina.net.SSLServerSocketFactory" clientAuth="false" protocol="TLS"/> </Connector>

	Important
	Set the clientAuth parameter to false, otherwise all Web applications will request a client certificate if they need SSL. The client authentication will be configured later in the web.xml file in the specific WAR files.

For more information, refer to http://jakarta.apache.org/tomcat/tomcat-5.0-doc/ssl-howto.html.

3.5.8.3.4. Step 3: Configure your Web Application to Request a Client Certificate

Add the following lines to the web.xml file of the WAR file of the Web application:

<login-config> <auth-method>CLIENT-CERT</auth-method> <realm-name>Example Authentication Area</realm-name> </login-config>

Important

Ensure that the restricted Web application area is configured in the web.xml file in the WAR file with a security-constraint declaration. Ensure that the Web application is always accessed with SSL, unless the Web container will not get a certificate and will not be able to authenticate the user. When authentication is enabled on client certificate, the user's Web browser receives the list of the Certification Authorities trusted by your Web application. A connection will be established with the client only if it has a certificate issued by a trusted Certification Authority, otherwise its certificate will be rejected. The certificates of all the trusted Certification Authorities must be imported in the $JAVA_HOME/jre/lib/security/cacerts keystore file (customize the SSL listener to modify this location).

3.5.8.3.5. Step 4: Configure the JAAS LoginModules

This authentication process is built on the JAAS technology. This means that authentication is performed in a pluggable way and the desired authentication technology is specified at runtime. Therefore, you must choose the LoginModules to use in your Web container to authenticate the users.

3.5.8.3.5.1. Choose the LoginModules

org.objectweb.jonas.security.auth.spi.JResourceLoginModule is the main LoginModule. It is highly recommended that this be used in every authentication, as it verifies the user authentication information in the specified resource.

org.objectweb.jonas.security.auth.spi.JResourceLoginModule accepts the following parameters:

• resourceName: the name of the entry in the jonas-realm.xml file being used; this entry represents how and where the authentication information is stored. This is the only required parameter.

• certCallback: Specify this optional parameter if you want this login module to ask for a certificate callback. By default it is set to false. When using JAAS realms with certificates, set it to true.

org.objectweb.jonas.security.auth.spi.CRLLoginModule is the LoginModule that contains authentication based on certificates. However, when enabled, it will also permit non-certificate based accesses. It verifies that the certificate presented by the user has not been revoked by the Certification Authority that signed it. To use it, the directory in which to store the revocation lists (CRLs) files or a LDAP repository must exist.

org.objectweb.jonas.security.auth.spi.CRLLoginModule can take the following parameters:

• CRLsResourceName: this parameter specifies how the CRLs are stored:

  • Directory: if the CRL files are stored in a directory on the machine, you must specify another parameter pointing to that directory:

    • CRLsDirectoryName: the directory containing the CRL files (the extension for these files must be .crl).

  • LDAP: This functionality is experimental if your CRL files are stored in a LDAP repository, two additional parameters must be specified:

    • address: the address of the server that hosts the LDAP repository

    • port: the port used by the LDAP repository; CRLs are retrieved from an LDAP directory using the LDAP schema defined in RFC 2587 (refer to http://www.ietf.org/rfc/rfc2587.txt).

3.5.8.3.5.2. Specify the Configuration Parameters

The JAAS configuration sits on a file in which the login module to use for authentication is described. This file is located in $JONAS_BASE/conf and named jaas.config. To change its location and name, edit the $JOANS_BASE/bin/jonas.sh script and modify the following line:

-Djava.security.auth.login.config=$JONAS_BASE/conf/jaas.config

The contents of the JAAS configuration file follow this structure:

Application_1 { LoginModuleClassA Flag Options; LoginModuleClassB Flag Options; LoginModuleClassC Flag Options; }; Application_2 { LoginModuleClassB Flag Options; LoginModuleClassC Flag Options; }; Other { LoginModuleClassC Flag Options; LoginModuleClassA Flag Options; };

Sample of a configuration file with a CRL directory:

tomcat { org.objectweb.jonas.security.auth.spi.CRLLoginModule required CRLsResourceName="Directory" CRLsDirectoryName="path_to/CRLs"; org.objectweb.jonas.security.auth.spi.JResourceLoginModule required resourceName="memrlm_1"; };

There can be multiple entries in this file, specifying different configurations that JOnAS can use. The entry dedicated to Tomcat must be named tomcat. Note that everything in this file is case-sensitive.

There is a flag associated with all the LoginModules to configure their behavior in case of success or failure:

• required: The LoginModule is required to succeed. If it succeeds or fails, authentication still proceeds through the LoginModule list.

• requisite: The LoginModule is required to succeed. If it succeeds, authentication continues through the LoginModule list. If it fails, control immediately returns to the application (authentication does not proceed through the LoginModule list).

• sufficient: The LoginModule is not required to succeed. If it does succeed, control immediately returns to the application (authentication does not proceed through the LoginModule list). If it fails, authentication continues through the LoginModule list.

• optimal: The LoginModule is not required to succeed. If it succeeds or fails, authentication still proceeds through the LoginModule list.

3.5.8.3.6. Step 5: Populate the Realm Access List

Now, users will not have to enter a login/password. They will just present their certificates and authentication is performed transparently by the browser (after the user has imported the certificate into it). Therefore, the identity presented to the server is not a login, but a Distinguished Name: that is the name identifying the person to whom the certificate belongs.

This name has the following structure:

CN=Someone Unknown, OU=ObjectWeb, O=JOnAS, C=ORG E : Email Address CN : Common Name OU : Organizational Unit O : Organization L : Locality ST : State or Province Name C : Country Name

The Subject in a certificate contains the main attributes and may include additional ones, such as Title, Street Address, Postal Code, Phone Number.

Previously in the jonas-realm.xml file a memory realm might contain:

<user name="jps_admin" password="admin" roles="administrator"/>

To enter a certificate-based user access, you must now enter the user's DN preceded by the String: ##DN##, as shown in the following example:

<user name="##DN##CN=whale, OU=ObjectWeb, O=JOnAS, L=JOnAS, ST=JOnAS, C=ORG" password="" roles="jadmin" />

3.5.9. Configuring the JMS Service

Until JOnAS release 4.1, the only way to provide the JMS facilities was by setting a JMS service when configuring JOnAS. The JMS service is a default setting in the jonas.properties config file; however, this JMS service will not allow you to deploy 2.1 MDBs (Message Driven Beans), and will eventually become deprecated in later JOnAS versions.

The new way to integrate a JMS platform is by deploying a J2EE 1.4 compliant resource adapter. How you do this is described in Section 3.7 Configuring JMS Resource Adapters.

JOnAS integrates a third-party JMS implementation, JORAM (http://www.objectweb.org/joram/), which is the default JMS service. Other JMS providers, such as SwiftMQ (http://www.swiftmq.com/ and WebSphere MQ (http://www-3.ibm.com/software/integration/mqfamily/), can easily be integrated as JMS services.

The JMS service is used to contact (or launch) the corresponding MOM (Message Oriented Middleware) or JMS server. You should create the JMS-administered objects used by the EJB components, such as the connection factories and the destinations, prior to the EJB execution, using the proprietary JMS implementation administration facilities. JOnAS provides "wrappers" on such JMS administration APIs, which enable the EJB server itself to perform simple administration operations automatically.

The JMS service is an optional service that must be started before the EJB container service.

The following are the properties that can be set in jonas.properties file for the JMS service:

• jonas.service.jms.collocated for setting the JMS server launching mode. If set to true, it is launched in the same JVM as the JOnAS Server (this is the default value). If set to false, it is launched in a separate JVM, in which case the jonas.service.jms.url must be set with the connection URL to the JMS server.

• jonas.service.ejb.mdbthreadpoolsize is used for setting the default thread pool used for Message Driven Beans (10 is the default value).

• jonas.service.jms.queues and jonas.service.jms.topics are used for setting lists of administered objects queues or topics at launching time.

• jonas.service.jms.mom is used to indicate which class must be used to perform administrative operations. This class is the wrapper to the actual JMS provider implementation. The default class is org.objectweb.jonas_jms.JmsAdminForJoram, which is required for JORAM (refer to http://joram.objectweb.org//). For the SwiftMQ product, obtain a com.swiftmq.appserver.jonas.JmsAdminForSwiftMQ class from the SwiftMQ site (http://www.swiftmq.com/).

Some additional information about JMS configuration (in particular, several JORAM advanced configuration aspects) is provided in Section 26.4 JMS Administration and Section 26.5 Running an EJB Performing JMS Operations.

3.5.10. Configuring the Resource Service

The Resource service is an optional service that must be started as soon as EJB components require access to an external Enterprise Information Systems. The standard way to do this is to use a third-party software component called a Resource Adapter.

The role of the Resource service is to deploy the Resource Adapters in the JOnAS server, (that is, configure it in the operational environment and, in JNDI name space, register a connection factory instance that can be looked up by the EJB components).

The Resource service can be configured in one of the following ways:

• The corresponding RAR file name is listed in the jonas.service.resource.resources property in jonas.properties file. If the file name does not contain an absolute path name, then it should be located in the $JONAS_BASE/rars/ directory.

  Example:

  jonas.service.resource.resources MyEIS

  This file will be searched for in the $JONAS_BASE/rars/ directory. This property is a comma-separated list of resource adapter file names (the .rar suffix is optional).

• Another way to automatically deploy resource adapter files at the server start-up is to place the RAR files in an autoload directory. The name of this directory is specified using the jonas.service.resource.autoloaddir property in jonas.properties file. This directory is relative to the $JONAS_BASE/rars/ directory.

A jonas-specific, resource-adapter configuration xml file must be included in each resource adapter. This file replicates the values of all configuration properties declared in the deployment descriptor for the resource adapter. Refer to Section 25.2 Defining the JOnAS Connector Deployment Descriptor for additional information.

3.5.11. Configuring the JMX (Java Management Extension) Service

The JMX service is mandatory and will be started even if it is not present in the list of services. It is configured by choosing one of the two supported JMX implementations, SUN RI or MX4J. The choice is made based on the value of the jonas.service.jmx.class property in the JOnAS configuration file. The two possible values are:

• org.objectweb.jonas.jmx.sunri.JmxServiceImpl, for SUN RI

• org.objectweb.jonas.jmx.mx4j.Mx4jJmxServiceImpl, for MX4J

3.5.12. Configuring the Mail Service

The Mail service is an optional service that can be used to send email. It is based on JavaMail and on the JavaBeans Activation Framework (JAF) API (refer to http://java.sun.com/products/javamail/ and http://java.sun.com/products/beans/glasgow/jaf.html respectively).

A mail factory is required in order to send or receive mail. JOnAS provides two types of mail factories: javax.mail.Session and javax.mail.internet.MimePartDataSource.

MimePartDataSource factories allow mail to be sent with a subject and the recipients already set.

Mail factory objects must be configured accordingly to their type. The subsections that follow briefly describe how to configure Session and MimePartDataSource mail factory objects, in order to run the SessionMailer SessionBean and the MimePartDSMailer SessionBean delivered with the platform.

jonas.service.mail.factories MailSession1,MailMimePartDS1