The content of this Configuration Guide is the following:
As described in the Getting Started
chapter, JOnAS is pre-configured and ready to use directly with RMI/JRMP
for remote access, if visibility to classes other than those contained
in the JOnAS distribution in $JONAS_ROOT/lib
is not
required.
To use JEREMIE or RMI/IIOP for remote access or to work
with additional java classes (for example, JDBC driver classes),
additional configuration tasks must be performed, such as setting a
specific port number for the registry.
JOnAS distribution contains a number of configuration files in $JONAS_ROOT/conf
directory. These files can be edited to change the default
configuration. However, it is recommended that the configuration files
needed by a specific application running on JOnAS be placed in a
separate location. This is done by using an additional environment
variable called JONAS_BASE
.
The JONAS_BASE
environment variable has been introduced
in JOnAS version 3.1. Starting with this version, the previous
configuration rule is replaced with a very basic one:
JOnAS configuration files are
read from the $JONAS_BASE/conf
directory.
If JONAS_BASE
is
not defined, it is automatically initialized to $JONAS_ROOT
.
There are two ways to use JONAS_BASE
:
JONAS_BASE
with the path to this directory.$JONAS_BASE
:
$JONAS_ROOT/conf
into $JONAS_BASE/conf
. Then, modify the
configuration files according to the requirements of your
application, as explained in the following sections.$JONAS_BASE
with a path.$JONAS_ROOT
directory, enter: ant
create_jonasbase
. This will copy all the required files and
create all the directories.Note that the build.xml
files provided with the JOnAS
examples support JONAS_BASE
. If this environment variable
is defined prior to building and installing the examples, the generated
archives are installed under the appropriate sub-directory of $JONAS_BASE
.
For example, the ejb-jar files corresponding to the sample examples of $JONAS_ROOT/examples/src/
are installed in $JONAS_BASE/ejbjars
.
The JOnAS server is configured via a configuration file named jonas.properties
.
It contains a list of key/value pairs presented in the java properties
file format.
Default configuration is provided in $JONAS_ROOT/conf/jonas.properties
.
This file holds all possible properties with their default values. This
configuration file is mandatory. The JOnAS server looks for this file at
start time in the $JONAS_BASE/conf
directory ($JONAS_ROOT/conf
if $JONAS_BASE
is not defined).
Most of the properties are related to the JOnAS services that can be
launched in the JOnAS server. These properties are described in detail
in Configuring JOnAS services.
The property jonas.orb.port
is not related to any service.
It identifies the port number on which the remote objects receive calls.
Its default value is 0, which means that an anonymous port is
chosen. When the JOnAS server is behind a firewall, this property can
be set to a specific port number.
Note that starting with the JOnAS 3.1. version, the jonas.name
property no longer exists. The name of a server can be specified on the jonas
command line using a specific option (-n name
).
If the name is not specified, the default value is jonas.
When several JOnAS servers must run simultaneously, it is beneficial to set a different name for each JOnAS server in order to administrate these servers via the JOnAS administration tools.
Also note that it is possible to define configuration properties on
the command line: (java -D...
).
Use the jonas check
command to review the JOnAS configuration state.
$JONAS_ROOT/bin/unix/setenv
and $JONAS_ROOT/bin/unix/config_env
,
on Unix
This configuration script sets useful environment variables for
JAVA setup ($JAVA
and $JAVAC
). It adds $JONAS_BASE/conf
to the $CLASSPATH
if $JONAS_BASE
is set,
otherwise it adds $JONAS_ROOT/conf
. This script is called
by almost all other scripts (jclient
, jonas
,newbean
,registry
,GenIC
).
%JONAS_ROOT%\bin\nt\setenv.bat
and %JONAS_ROOT%\bin\nt\config_env.bat
,
on Windows
This script is used to add some required .jar
files
to the $CLASSPATH
. This script is called by the jonas
script.
Therefore, when requiring the visibility of specific .jar
files, the best practice is to update the config_env
file. For example, to see some of the JDBC driver classes, one or more
of the variables IDB_CLASSES
, ORACLE_CLASSES
, POSTGRE_CLASSES
,INTERBASE_CLASSES
must be updated.
Another way to place an additional .jar
in the
classpath of your JOnAS server is to insert it at the end of the config_env
file:
CLASSPATH=<The_Path_To_Your_Jar>$SPS$CLASSPATH
Note that an additional environment variable called XTRA_CLASSPATH
can be defined to load specific classes at JOnAS server start-up. Refer
to Bootstrap class loader.
Typically, access to JNDI is bound to a jndi.properties
file that must be accessible from the classpath. This is somewhat
different within JOnAS. Starting with JOnAS 3.1.2, multi-protocol
support is provided through the integration of the CAROL component. This
currently provides support for RMI/JRMP, RMI/IIOP, JEREMIE, and CMI
(clustered protocol) by changing the configuration. Other protocols may
be supported in the future. In versions prior to JOnAS 3.1.2, it was
necessary to rebuild JOnAS for switching (e.g., from RMI/JRMP to
JEREMIE), and to change the value of the OBJECTWEB_ORB environment
variable; OBJECTWEB_ORB is no longer used. This configuration is now
provided within the carol.properties
file
(that includes what was provided in the jndi.properties
file). This file is supplied with the JOnAS distribution in the $JONAS_ROOT/conf
directory.
Supported communication protocols are the following:
jonathan.xml
delivered in $JONAS_ROOT/conf
. Typically,
no modifications are necessary; just make sure it is copied under $JONAS_BASE/conf
if $JONAS_BASE
is defined.The contents of the carol.properties
file is:
# jonas rmi activation (jrmp, iiop, jeremie, or cmi)
carol.protocols=jrmp
#carol.protocols=cmi
#carol.protocols=iiop
#carol.protocols=jeremie
# RMI JRMP URL
carol.jrmp.url=rmi://localhost:1099
# RMI JEREMIE URL
carol.jeremie.url=jrmi://localhost:12340
# RMI IIOP URL
carol.iiop.url=iiop://localhost:2000
# CMI URL
carol.cmi.url=cmi://localhost:2001
# general rules for jndi
carol.jndi.java.naming.factory.url.pkgs=org.objectweb.jonas.naming
CAROL can be customized by editing the $JONAS_BASE/conf/carol.properties
file to 1) choose the protocol through the carol.protocols
property, 2) change localhost
to the hostname where
registry will be run, 3) change the standard port number. If the
standard port number is changed, registry must be run with this port
number as the argument, registry <Your_Portnumber>
,
when the registry is not launched inside the JOnAS server.
Due to an incompatibility between Jeremie and rmi/iiop, a restriction
currently exists; there is no configuration option that provides a
choice between these two protocols when building a JOnAS server. By
default, JOnAS only allows a choice between rmi/jrmp
, Jeremie,
or cmi
. To use rmi/iiop
, it is necessary to
run an "ant installiiop
" command under the $JONAS_ROOT
directory. This will result in a choice between rmi/jrmp
, rmi/iiop
or cmi
.
For implementing EJB security and transactions, JOnAS typically
relies on the communication layer for propagating the security and
transaction contexts across the method calls. By default, the
communication protocol is configured for context propagation. However,
this configuration can be changed by disabling the context propagation
for security and/or transaction; this is done primarily to increase
performance. The context propagation can be configured in the jonas.properties
file by setting the jonas.security.propagation
and jonas.transaction.propagation
properties to true
or false
:
# Enable the Security context propagation
jonas.security.propagation true
# Enable the Transaction context propagation
jonas.transaction.propagation true
Note that the secpropag
attribute of the JOnAS ejbjar ANT task and the -secpropag
option of GenIC are no longer used. They were
used in JOnAS versions prior to 3.1.2 to specify that the security
context should be propagated.
The JOnAS deployment tool (GenIC) must be notified for which
protocols stubs (for remote invocation) are to be generated. Choosing
several protocols will eliminate the need to redeploy the EJBs when
switching from one protocol to another. The default is that GenIC
generates stubs for rmi/jrmp
and Jeremie
. To
change this configuration, call GenIC with the -protocols
option specifying a comma-separated list of protocols (chosen within
jeremie, jrmp, iiop, cmi), e.g.:
GenIC -protocols jrmp,jeremie,iiop
This list of protocols can also be specified for the JOnAS ejbjar ANT task:
<jonas destdir="${dist.ejbjars.dir}"
jonasroot="${jonas.root}"
protocols="jrmp,jeremie,iiop"
keepgenerated="true"
verbose="${verbose}"
mappernames="${mapper.names}"
additionalargs="${genicargs}">
</jonas>
Starting with JOnAS 2.5, the logging system is based on Monolog, the new standard API for Objectweb projects. Configuring trace messages inside Jonas can be done in two ways:
Note the SQL requests sent to a Database can be easily traced using the JOnAS Logging system and the integrated P6Spy tool. The configuration steps are described in the "Configuring JDBC Datasources" section.
A standard file is provided in $JONAS_ROOT/conf/trace.properties
.
Use the CLASSPATH to retrieve this file.
The the
monolog documentation provides more details about how to configure
logging. Monolog is built over a standard log API (currently, log4j).
Loggers can be defined, each one being backed on a handler.
A handler represents an output, is identified by its name, has a type,
and has some additional properties. Two handlers have been defined in
the trace.properties file:
Each handler can define the header it will use, the type of logging (console, file, rolling file), and the file name.
Note that if the tag "automatic" is specified as the output
filename, JOnAS will replace this tag with a file pointing to $JONAS_BASE/logs/<jonas_name_server>-<timestamp>.log
.
The logf handler, which is bundled with JOnAS, uses this "automatic"
tag.
Loggers are identified by names that are structured as a tree. The root of the tree is named root.
Each logger is a topical logger, i.e. is associated with a topic. Topic names are usually based on the package name. Each logger can define the handler it will use and the trace level among the following four values:
If nothing has been defined for a logger, it will use the properties defined for its parent.
JOnAS code is written using the monolog API and it can use the tty handler.
Example of setting DEBUG level for the logger used in the jonas_ejb module:
logger.org.objectweb.jonas_ejb.level DEBUG
Example for setting the output of JOnAS traces to both the console
and a file /tmp/jonas/log
:
handler.logf.output /tmp/jonas.log
logger.org.objectweb.jonas.handler.0 tty
logger.org.objectweb.jonas.handler.1 logf
Example for setting the output of JOnAS traces to a file in the $JONAS_BASE/logs/
directory:
handler.logf.output automatic
logger.org.objectweb.jonas.handler.0 logf
JOnAS may be viewed as a number of manageable built-in services started at server launching time. JOnAS is also able to launch external services, which can be defined as explained in the JOnAS service chapter.
The following is a list of the JOnAS built-in services:
These services can be managed using the Jadmin
administration console, which is a Servlet-based application using the JMX technology.
Note that Jadmin can only manage available services (currently, it is
not possible to launch a service via Jadmin).
The services available in a JOnAS server are those specified in the
JOnAS configuration file. The jonas.services
property in
the jonas.properties
file must contain a list of the
required service names. Currently, these services will be started in
the order in which they appear in the list. Therefore, the following
constraints should be considered:
Example:
jonas.services registry,jmx,jtm,dbm,security,resource,jms,mail,ejb,ws,web,ear
The registry can be omitted from the list because this
service is automatically launched if it is not already activated by
another previously started server. This is also true for jmx,
since, beginning with JOnAS 3.1, this service is automatically launched
after the registry.
The dbm, resource, and jms services are listed
after the jtm.
The application components deployed on this server can use Java
Messaging and Java Mail because jms and mail are listed
before ejb.
Configuration parameters for services are located in the jonas.properties
file, adhering to a strict naming convention: a service XX will
be configured via a set of properties:
jonas.service.XX.foo
something
jonas.service.XX.bar
else
This service is used for accessing the RMI registry, Jeremie
registry, CMI registry, or the CosNaming (iiop), depending on the
configuration of communication protocols specified in carol.properties
,
refer to the section "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 the jonas.service.registry.mode
property are:
collocated
: the Registry is launched in the same JVM
as the JOnAS Server,remote
: the Registry must be launched before the
JOnAS Server in a separate JVM,automatic
: the Registry is launched in the same JVM
as JOnAS Server, if not already started. This is the default value.The port number on which the Registry is launched is defined in the carol.properties
file.
This is the primary JOnAS service, providing EJB containers for EJB components.
An EJB container can be created from an ejb-jar
file
using one of the following possibilities:
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 name, it
should be located in the $JONAS_BASE/ejbjars/
directory. The container is created when the JOnAS server starts. jonas.service.ejb.descriptors Bank.jar
ejb-jar
file named Bank.jar
. This
file will be searched for in the $JONAS_BASE/ejbjars/
directory.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.ejb-jar
files using the Jadmin
tool.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 (see Bootstrap class
loader).
This service provides WEB containers for the WEB components used in
the J2EE applications.
JOnAS provides two implementations of this service: one for Jetty
4.2.x, one for Tomcat 4.1.x.
It is necessary to run this service to use the Jadmin
tool.
If the environment variable $JETTY_HOME
or $CATALINA_HOME
is not set, the web container service cannot be loaded at JOnAS startup
and a warning is displayed.
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 will create a
container from the war
file named Bank.war
.
It will search for this file in the $JONAS_BASE/webapps/
directory.
Using webapp directories instead of packaging a new war file each
time can improve the development process. You can replace the classes
with the new compiled classes and 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
web container (Jetty or Tomcat) for the production time.
Example of using the jonasAdmin/ webapp directory
instead of jonasAdmin.war
JONAS_BASE/webapps/autoload
directoryJONAS_BASE/webapps/autoload/jonasAdmin
jonasAdmin.war
file to this directoryWEB containers can be also dynamically created from war
files using the Jadmin
tool.
At this time, only 1 implementation for WebServices is available : the Axis implementation. But in the future, a Glue implementation can be made easily.
jonas.properties :
#...
|
#... jonas.service.ws. file1.type file jonas.service.ws. file1.location
/path/to/directory/where/store/wsdls |
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.
The Jadmin
tool can be
used to dynamically deploy the J2EE application components from an ear
file.
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.
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
The description of the new JDBC Resource Adapters as a replacement for the Database service is located in Configuring JDBC Resource Adapters.
To allow access to one or more relational databases (e.g. Oracle, InstantDB, PostgreSQL, ...), 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 is provided in the "Configuring JDBC DataSources" section of the Bean Programmer's Guide.
The following subsections briefly explain how to configure a DataSource object for your database, to be able to run the Entity Bean example delivered with your specific platform.
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 the "Configuring JDBC Datasources" section.
A template Oracle1.properties
file is supplied in the installation directory. This file is used to
define a DataSource object, named Oracle1
. This
template must be updated with values appropriate to your installation.
The fields are the following:
datasource.name | JNDI name of the DataSource: The name used in the example is jdbc_1 . |
datasource.url | The JDBC database URL: for the Oracle JDBC "Thin" driver it
is jdbc:oracle:thin:@hostname:sql*net_port_number:ORACLE_SID If using an Oracle OCI JDBC driver, the URL is jdbc:oracle:oci7: or jdbc:oracle:oci8: |
datasource.classname | Name of the class implementing the Oracle JDBC driver:oracle.jdbc.driver.OracleDriver |
datasource.mapper | Adapter, mandatory for CMP2.0 only (more details in Configuring JDBC DataSources): rdb.oracle8
for Oracle 8 and prior versions |
datasource.username | Database user name |
datasource.password | Database user password |
For the EJB platform to create the corresponding DataSource object,
its name (Oracle1, not the JNDI name) must be in the jonas.properties
file, on the jonas.service.dbm.datasources line:
jonas.service.dbm.datasources Oracle1
There may be several DataSource objects defined for an EJB server, in which case there will be several dataSourceName.properties files and a list of the DataSource names on the jonas.service.dbm.datasources line of the jonas.properties file:
jonas.service.dbm.datasources Oracle1, Oracle2, InstantDB1
To create the table used in the example with the SQL script provided
in examples/src/eb/Account.sql
, the Oracle server must be
running with a JDBC driver installed (Oracle JDBC drivers may be
downloaded at their Web
site).
For example:
sqlplus user/passwd SQL> @Account.sql SQL> quit
The JDBC driver classes must be accessible from the classpath. To do
this, update the config_env file; ($JONAS_ROOT/bin/unix/config_env
on Unix, or %JONAS_ROOT%\bin\nt\config_env.bat
on Windows).
A template InstantDB1.properties file is supplied in the installation directory. This file is used to define a Datasource object named InstantDB1. This template must be updated with values appropriate to your installation. The fields are the following:
datasource.name | JNDI name of the DataSource: The name used in the example is jdbc_1 . |
datasource.url | The JDBC database URL: for InstantDB it is jdbc:idb=db1.prp. |
datasource.classname | Name of the class implementing the JDBC driver: org.enhydra.instantdb.jdbc.idbDriver |
To have the EJB platform create the corresponding DataSource object,
its name (InstantDB1, not the JNDI name) must be in the jonas.properties
file, on the jonas.service.dbm.datasources line.
jonas.service.dbm.datasources InstantDB1
InstantDB must have been properly installed and configured, using a version higher than 3.14. (examples have been tested with 3.25).
The JDBC driver classes must be accessible from the classpath. To do
this, update the config_env file; ($JONAS_ROOT/bin/unix/config_env
on Unix, or %JONAS_ROOT%\bin\nt\config_env.bat
on Windows).
Create the Account database using the utility provided with InstantDB:
cd examples/src/eb
. $JONAS_ROOT/bin/unix/config_env
java org.enhydra.instantdb.ScriptTool Account.idb
The same type of process can be used for other databases. A template of datasource for PostgreSQL and for InterBase is supplied with JOnAS. Although many other databases are currently used by the JOnAS users (e.g. Informix, Sybase, SQL Server), not all JDBC drivers have been tested against JOnAS.
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 exploits security roles and method permissions located in the EJB deployment descriptor.
Note that:
$JONAS_ROOT/conf/jonas-realm.xml
:
<jonas-memoryrealm>.
<jonas-dsrealm>.
<jonas-ldaprealm>.
providerUrl
element is not set, the default
value is ldap://localhost:389.
jonas-realm_1_0.dtd
DTD file to see the default
values.org.objectweb.jonas.security.realm.JRealmCatalina41.
org.objectweb.jonas.security.realm.JRealmJetty42.
jonas-realm.xml
file.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 propagation across method calls.
Refer also to the "Security and Transaction Context
Propagation" section.
With Tomcat 4.1.x, in the $JONAS_ROOT/conf/server.xml
file,
or $JONAS_BASE/conf/server.xml
file,
or $CATALINA_HOME/conf/server.xml
file,
or $CATALINA_BASE/conf/server.xml
replace the following
line:
<Realm className="org.apache.catalina.realm.UserDatabaseRealm" debug="0" resourceName="UserDatabase" />
By the line:
<Realm className="org.objectweb.jonas.security.realm.JRealmCatalina41" debug="0" resourceName="memrlm_1" />
A memory, Datasource, or LDAP resource can be used for the authentication, with the correct name of the specified resource as resourceName, that is: memrlm_1, memrlm_2, dsrlm_1, ldaprlm_1, etc.
To use Jetty interceptors in a web application, provide a web-jetty.xml
file under the WEB-INF
directory in the .war
file,
in which it is specified that the security interceptor org.objectweb.jonas.security.realm.JRealmJetty42
for JOnAS be used instead of the default one. Such as, for the earsample
example:
<Call name="setRealmName">
<Arg>Example Basic Authentication Area</Arg>
</Call>
<Call name="setRealm">
<Arg>
<New class="org.objectweb.jonas.security.realm.JRealmJetty42">
<Arg>Example Basic Authentication Area</Arg>
<Arg>memrlm_1</Arg>
</New>
</Arg>
</Call>
Several web-jetty.xml examples are located in the earsample
example and alarm
demo.
JOnAS relies on the jonas-realm.xml
file for access control to the methods of EJB components.
Example of a secured bean with the role jonas.
<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>
The following subsections describe how to configure the different
resources for performing authentication if it is necessary to add a user
that has the specified role (jonas) and is authorized to call methods,
etc.
jonas-realm.xml
fileTo add the role 'jonas
', place this example role in the <roles>
section:
<roles>Then, add a user with the specified role.
<role name="jonas" description="Role used in the sample security howto" />
</roles>
jonas
' role in the <users>
section: <users>
<user name="jonas_user" password="jonas_password" roles="jonas" />
</users>
The <groups> section permits grouping roles.
Add the memory resource in the jonas-realm.xml
file:
<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-realm.xml
fileFirst, build the tables in which the users and roles will be stored.
Example of tables :
realm_users : Add a user jonas_user
with the
password jonas_password
user_name | user_pass |
... | ... |
jonas_user | jonas_password |
... | ... |
Note that the table can contain more than two columns.
jonas
to the user jonas_user
user_name | role_name |
... | ... |
jonas_user | jonas |
... | ... |
Now, declare the resource in the jonas-realm.xml
file.
The dsName
element describes the JNDI name of the
datasource to use.
Thus, a Datasource configuration with the right JNDI name for the dbm
service must be set in the jonas.properties
file.
The datasource resource to add in the jonas-realm.xml
file
is:
<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-realm.xml
fileThe user is added in the LDAP server.
In this case, all the users are on the ou=people,dc=jonas,dc=objectweb,dc=org
DN.
For example, the unique name will be: DN
uid=jonas_user,ou=people,dc=jonas,dc=objectweb,dc=org
for the
user 'jonas_user'
.
The role jonas will be added on the ou=groups,dc=jonas,dc=objectweb,dc=org
DN.
In this case: DN cn=jaas,ou=groups,dc=jonas,dc=objectweb,dc=org
The user is added to the role by adding a field uniquemember to the
role. uniquemember =
uid=jonas,ou=people,dc=jonas,dc=objectweb,dc=org
LDIF format for the user:
# 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
LDIF format for the role:
# 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
Now the jonas-realm.xml
file can be customized by
adding a LDAP resource.
There are two methods for the authentication: the bind or the compare
method.
By default, the bind method is used.
All the elements of the configuration for the ldap resource can be
found on the jonas-realm_1_0.dtd
DTD file.
For this sample, it is assumed that the LDAP server is on the same
computer and is on the default port (389). It takes all the default
values of the DTD.
The datasource resource to add in the jonas-realm.xml
file
is:
<jonas-ldaprealm>
[...]
<ldaprealm name="howto_ldap_realm1"
baseDN="dc=jonas,dc=objectweb,dc=org" />
[...]
</jonas-ldaprealm>
In order to set up the client authentication based on client certificate in a Web container, do the following:
Configure the Realm the Web container will have to use.
Configure an SSL listener on the Web container.
Configure the Web application to make it ask a client certificate.
Configure the JAAS LoginModules.
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.
If the JOnAS-Tomcat package is installed, skip this paragraph.
With Tomcat 4.1.x, in the $JONAS_ROOT/conf/server.xml
file,
or $JONAS_BASE/conf/server.xml
file,
or $CATALINA_HOME/conf/server.xml
file,
or $CATALINA_BASE/conf/server.xml
replace the current
Realm by the following :
<Realm className="org.objectweb.jonas.security.realm.JRealmJAASCatalina41" />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.
Edit the web-jetty.xml
file under WEB-INF
directory in the .war
file to declare a Realm name and a
Realm:
<Configure class="org.mortbay.jetty.servlet.WebApplicationContext">
...
!-- Set the same realm name as the one specified in <realm-name> in <login-config> in the web.xml file of your web application -->
<Call name="setRealmName">
<Arg>Example Authentication Area</Arg>
</Call>
<!-- Set the class Jetty has to use to authenticate the user and a title name for the pop-up window -->
<Call name="setRealm">
<Arg>
<New class="org.objectweb.jonas.security.realm.JRealmJAASJetty42">
<Arg>JAAS on Jetty</Arg>
</New>
</Arg>
</Call>
...
</Configure>
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.
Uncomment the following section in the server.xml
file:
<Connector className="org.apache.catalina.connector.http.HttpConnector" port="8443"
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-4.1-doc/ssl-howto.html.
In the global deployment descriptor of Jetty (the jetty.xml
file), that is in the $JETTY_HOME/conf
or $JONAS_BASE/conf
directory (depending on whether using Jetty is being used in standalone
or not), set:
<Configure class="org.mortbay.jetty.Server">
...
<Call name="addListener">
<Arg>
<New class="org.mortbay.http.SunJsseListener">
<Set name="Port">8443</Set>
<Set name="Keystore">
<SystemProperty name="jonas.base" default="."/>/conf/keystore</Set>
<Set name="Password">changeit</Set>
<Set name="KeyPassword">jettykeypassword</Set>
<Set name="NeedClientAuth">true</Set>
</New>
</Arg>
</Call>
...
</configure>
The Jetty certificate is stored in a repository called the keystore. This is the certificate that will present Jetty when a connection is about to be established.
For more information, refer to http://jetty.mortbay.org/jetty/doc/SslListener.html.
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:
For both Tomcat and Jetty, ensure that the restricted Web
application area is configured in the web.xml
file in the .war
file with a security-constraint
declaration.
For both Tomcat and Jetty, 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.
For both Tomcat and Jetty, when authentication is enabled on client certificate, the user's Web browser receives the list of the trusted (by your Web application) Certification Authorities. A connection will be established with the client only if it has a certificate issued by a trusted Certification Authorities, otherwise its certificate will be rejected.
In Jetty, the certificates of all the trusted Certification Authorities must be imported inside the keystore specified in the SSL listener.
In Tomcat, 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).
For Jetty, if the parameter NeedClientAuth
in the jetty.xml
file is set to true, all Web
applications accessed with SSL will ask the user to present a
certificate. Use different SSL listeners on different ports to have
both Web applications that require client certificate and those that
do not.
For Jetty, remember to set the same realm-name
as
the one in the web-jetty.xml
file.
For Jetty, refer to http://jetty.mortbay.org/jetty/doc/ClientCert.htmlfor
more information.
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 LoginModule
s to use in your Web
container to authenticate the users.
"org.objectweb.jonas.security.auth.spi.JResourceLoginModule"
This 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.
It requires only one parameter :
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.
certCallback
: Specify this optional
parameter if you want this login module to ask for a certificate
callback. By default it is set to false. It should be set to true
when using JAAS realms with certificates.
"org.objectweb.jonas.security.auth.spi.CRLLoginModule"
CRLsResourceName
: this parameter specifies
how the CRLs are stored:
"Directory"
: if the CRL files are stored in a
directory on the machine; another parameter pointing to that
directory must be specified:
CRLsDirectoryName
: the directory
containing the CRL files (the extension for these files must be
.crl).
"LDAP"
: if your CRL files are stored in a LDAP
repository; this functionality is experimental; 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.
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.configThe contents of the JAAS configuration file follows that structure:
Application_1 {Sample of a configuration file with CRL directory:
LoginModuleClassA Flag Options;
LoginModuleClassB Flag Options;
LoginModuleClassC Flag Options;
};
Application_2 {
LoginModuleClassB Flag Options;
LoginModuleClassC Flag Options;
};
Other {
LoginModuleClassC Flag Options;
LoginModuleClassA Flag Options;
};
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. There are two requirements: the entry
dedicated to Tomcat must be named tomcat
, and the entry
for Jetty, jetty
. Note that everything in this file is
case-sensitive.
There is a flag associated with all the LoginModules to configure their
behaviour in case of success or fail:
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.
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 his 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 looks like the following:
CN=Someone Unknown, OU=ObjectWeb, O=JOnAS, C=ORGE : Email Address
Subject
in a certificate contains the main attributes
and may include additional ones, such as Title, Street Address, Postal
Code, Phone Number.jonas-realm.xml
, a memory realm might
contain:
<user name="jps_admin" password="admin" roles="administrator"/>
To enter a certificate-based user access, now the user's DN preceded
by the String: ##DN##
must be entered, as shown in the
following example:
<user name="##DN##CN=whale, OU=ObjectWeb, O=JOnAS, L=JOnAS, ST=JOnAS, C=ORG" password="" roles="jadmin" />
JOnAS uses a third party JMS implementation; currently the Joram opensource is
integrated and delivered with JOnAS. The SwiftMQ product as well as other JMS
provider implementations can easily be integrated. JMS service is used
to contact (or launch) the corresponding MOM (Message Oriented
Middleware) or JMS server. The JMS-administered objects
used by the EJB components, such as the connection factories and the
destinations, should be created prior to the EJB execution, using the
proprietary JMS implementation administration facilities. JOnAS provides
"wrappers" on such JMS administration APIs, allowing simple
administration operations to be achieved automatically by the EJB server
itself.
jms service is an optional service that must be started before
the ejb container service.
Following are the properties that can be set in jonas.properties
file for 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 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.
For the SwiftMQ product, obtain a com.swiftmq.appserver.jonas.JmsAdminForSwiftMQ
class from the SwiftMQ site.
Some additional information about JMS configuration (in particular, several JORAM advanced configuration aspects) is provided in the " JMS Administration" and "Running an EJB performing JMS operations" sections of the Using JMS in application components chapter.
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 Resource Adapter.
The role of the Resource service is to deploy the Resource Adapters in the JOnAS server, i.e configure it in the operational environment and register in JNDI name space 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:
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. jonas.service.resource.resources MyEIS
$JONAS_BASE/rars/
directory. This property is a comma-separated list of resource
adapter file names ('.rar' suffix is optional).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 Using a Connector Architecture Resource Adapter with JOnAS for additional information.
The JMX service must be started in order to administrate or
instrument the JOnAS server via Jadmin
.
This 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 RIorg.objectweb.jonas.jmx.mx4j.Mx4jJmxServiceImpl
, for
MX4JThe Mail service is an optional service that may be used to
send email.
It is based on JavaMailTM and on JavaBeansTM Activation Framework (JAF) API.
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.
The template MailSession1.properties
file supplied in the installation directory defines a mail factory of Session
type. The JNDI name of the mail factory object is mailSession_1
.
This template must be updated with values appropriate to your
installation.
See the section "Configuring a mail factory" for the list of available
properties.
The template MailMimePartDS1.properties
file supplied in the installation directory defines a mail factory of MimePartDSMailer
type. The JNDI name of the mail factory object is mailMimePartDS_1
.
This template must be updated with values appropriate to your
installation.
The section "Configuring a mail factory" contains a list of the
available properties.
The following subsection provides information about configuring JOnAS in order to create the required mail factory objects.
Mail factory objects created by JOnAS must be given a name. In the
mailsb example, two factories called MailSession1 and MailMimePartDS1
are defined.
Each factory must have a configuration file whose name is the name of
the factory with the .properties
extension (MailSession1.properties
for the MailSession1 factory).
Additionally, the jonas.properties
file must define the jonas.service.mail.factories
property. For this example, it is:
jonas.service.mail.factories MailSession1,MailMimePartDS1
The fields are the following:
Required properties | |
mail.factory.name | JNDI name of the mail factory |
mail.factory.type | The type of the factory. This property can be javax.mail.Session
or javax.mail.internet.MimePartDataSource . |
Optional properties | |
Authentication properties | |
mail.authentication.username | Set the username for the authentication. |
mail.authentication.password | Set the password for the authentication. |
javax.mail.Session.properties (refer to JavaMail documentation for more information) | |
mail.authentication.username | Set the username for the authentication. |
mail.authentication.password | Set the password for the authentication. |
mail.debug | The initial debug mode. Default is false. |
mail.from | The return email address of the current user, used by the InternetAddress
method getLocalAddress. |
mail.mime.address.strict | The MimeMessage class uses the InternetAddress
method parseHeader to parse headers in messages. This
property controls the strict flag passed to the parseHeader
method. The default is true. |
mail.host | The default host name of the mail server for both Stores and
Transports. Used if the mail.protocol.host property
is not set. |
mail.store.protocol | Specifies the default message access protocol. The Session
method getStore() returns a Store object that
implements this protocol. By default the first Store provider
in the configuration files is returned. |
mail.transport.protocol | Specifies the default message access protocol. The Session
method getTransport() returns a Transport object
that implements this protocol. By default, the first Transport
provider in the configuration files is returned. |
mail.user | The default user name to use when connecting to the mail
server. Used if the mail.protocol.user property is
not set. |
mail.<protocol>.class | Specifies the fully- qualified class name of the provider for the specified protocol. Used in cases where more than one provider for a given protocol exists; this property can be used to specify which provider to use by default. The provider must still be listed in a configuration file. |
mail.<protocol>.host | The host name of the mail server for the specified protocol.
Overrides the mail.host property. |
mail.<protocol>.port | The port number of the mail server for the specified protocol. If not specified, the protocol's default port number is used. |
mail.<protocol>.user | The user name to use when connecting to mail servers using
the specified protocol. Overrides the mail.user property. |
MimePartDataSource properties (Only used if mail.factory.type is javax.mail.internet.MimePartDataSource) | |
mail.to | Set the list of primary recipients ("to") of the message. |
mail.cc | Set the list of Carbon Copy recipients ("cc") of the message. |
mail.bcc | Set the list of Blind Carbon Copy recipients ("bcc") of the message. |
mail.subject | Set the subject of the message. |