As previously seen in the Getting Started chapter, JOnAS
is pre-configured and can be directly used if you want to work with RMI/JRMP for
remote access, and if you don't need the visibility of other classes than those that are
contained in the JOnAS distribution in $JONAS_ROOT/lib
.
If you need to use JEREMIE or RMI/IIOP for remote access, or if you
need to work with additional java classes (JDBC driver classes for example), you have to
perform specific configuration tasks. Setting a specific port number for the registry is
another configuration example.
JOnAS distribution contains a number of configuration files in
$JONAS_ROOT/conf
directory.
You can edit these files to change default configuration, but we recommend you to use a
different location for the configuration files needed by a specific application running
on JOnAS. This is achieved by using an additional environment variable called
JONAS_BASE
.
The JONAS_BASE
environment variable has been introduced in JOnAS
version 3.1.
From this version, the previous configuration rule is replaced with a very simple 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
the following sub-directories:
$JONAS_BASE/conf
the configuration files located in
$JONAS_ROOT/conf
.
Now you can modify the configuration files according to your application's
needs as explained in the following sections.$JONAS_BASE
with a path.$JONAS_ROOT
directory, do : ant create_jonasbase
.
This will copy all the required files and create all the directories.
Please note that the build.xml
files provided with the JOnAS examples
supports JONAS_BASE
.
If you have defined this environment variable before building and installing the examples,
the generated archives are installed under the right sub-directory of
$JONAS_BASE
.
For instance, 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. JOnAS server looks for it 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. The meaning of such properties is detailed in
Configuring JOnAS services.
There is one property that is not relative to any service:
jonas.orb.port
. It indicates the
port number on which the remote objects receive calls. Its default value is 0,
which means that an anonymous port is chosen.
Setting this property to a specific port number may be used when JOnAS server is
behind a firewall.
Note that since JOnAS 3.1. version, the jonas.name
property does no
longer exist !
You can specify the name of a server on the
jonas
command line using a specific option (-n name
).
If the name is not specified, the default value is jonas.
When you need to have several JOnAS servers running simultaneously it is valuable to set a different name for each JOnAS server and so it will be possible 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...
).
Do not hesitate to 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%JONAS_ROOT%\bin\nt\setenv.bat
and %JONAS_ROOT%\bin\nt\config_env.bat
, on Windows
The former configuration script sets useful environment variables for JAVA setup ($JAVA
and
$JAVAC
),
and adds $JONAS_BASE/conf
to the $CLASSPATH
, if $JONAS_BASE
is set,
or $JONAS_ROOT/conf
, otherwise.
This script is called by almost all other scripts (jclient
, jonas
,
newbean
, registry
, GenIC
).
The latter is used to add some necessary .jar
files to the $CLASSPATH
. This script
is called by the jonas
script.
Therefore, when you need to have the visibility of specific .jar
files,
the best practice consists in updating the config_env
file.
For example, to see some JDBC driver classes you need to update in this file
one or several of the variables IDB_CLASSES
, ORACLE_CLASSES
, POSTGRE_CLASSES
,
INTERBASE_CLASSES
.
Another way to put 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 you may define an additional environment variable called
XTRA_CLASSPATH
to load specific classes at JOnAS server start-up.
See Bootstrap class loader
Usually, access to JNDI is bound to a jndi.properties
file
that must be accessible from the classpath. This is slightly different within JOnAS.
Since JOnAS 3.1.2, multi-protocol support is provided through the integration of the
CAROL component. This currently allows to
support RMI/JRMP, RMI/IIOP, JEREMIE, and CMI (clustered protocol) by just changing the
configuration. Other protocols may be supported in the future. Previously, in JOnAS
versions earlier than 3.1.2, it was neccessary to rebuild JOnAS for switching e.g. from
RMI/JRMP to JEREMIE, and to change the value of the OBJECTWEB_ORB environment variable
value ; OBJECTWEB_ORB is of no more use now. This configuration is provided within the
carol.properties
file (that includes what was provided in
the jndi.properties
file).
Such a file is supplied with the JOnAS distribution in the
$JONAS_ROOT/conf
directory.
The supported communication protocols are the following:
jonathan.xml
delivered
in $JONAS_ROOT/conf
. In general you can easily ignore
it, just make sure it was copied under
$JONAS_BASE/conf
if $JONAS_BASE
defined.
The carol.properties
file contents 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
Customization of CAROL consists in editing the
$JONAS_BASE/conf/carol.properties
file to choose the protocol through the carol.protocols
property.
You may change localhost
to the hostname where registry will be run.
You may also change the standard port number. In this case, don't forget to run
registry with this port number as argument: registry <Your_Portnumber>
,
when the registry is not launched inside the JOnAS server.
There is a current restriction due to an uncompatibility between Jeremie
and rmi/iiop.
It is therefore impossible to build a JOnAS server that allows to choose between these
two protocols through a simple configuration action. So, by default, JOnAS allows to choose
between rmi/jrmp
, Jeremie
and cmi
. If you want
to be able to use rmi/iiop
, you have to run an "ant installiiop
"
command under the $JONAS_ROOT directory. Then you will be able to choose between
rmi/jrmp
, rmi/iiop
and cmi
.
For implementing EJB security and transactions, JOnAS should rely 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 you
may change this configuration, by disabling the context propagation for security and/or
transaction; the reason for doing that is mainly to increase performance. You may configure
the context propagation 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 do not exist anymore.
They were used in JOnAS versions earlier than 3.1.2, to specify that the security
context should be propagated.
You should specify to the JOnAS deployment tool (GenIC) for which protocols you
would like stubs (for remote invocation) to be generated. You may choose several
protocols, this way you will not have to redeploy your EJBs when switching from one
protocol to another. The default is that GenIC generates stubs for rmi/jrmp
and Jeremie
. To change this configuration, you should call
GenIC with
the -protocols
option specifying a comma separated list of protocols
(choosed within jeremie, jrmp, iiop, cmi), e.g.:
GenIC -protocols jrmp,jeremie,iiop
This list of protocols may 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>
Since 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 by two ways:
Note that you may easily trace the SQL requests sent to a Database by relying on the JOnAS Logging system and on 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
The policy to retrieve this file is to use the CLASSPATH.
You can refer to
the monolog documentation
to know in more details how you can configure logging.
Basically, we must know that monolog is build above a standard log API (currently, log4j).
You can define loggers, each one being backed on a handler.
An handler represents an output. An handler is identified by its name.
It has a type and few others properties. In
trace.properties file
two handlers have been defined:
Each handler can define the header it will use, the type of logging (console, file, rolling file), and the file name.
Note that if you specify as output filename the tag "automatic", JOnAS will
replace this tag by 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 which 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 these 4 values:
If a logger has nothing defined, it will use the properties defined for its parent.
JOnAS code is written using directly monolog API, it can use the tty handler.
Example of setting DEBUG level for the logger used in jonas_ejb module:
logger.org.objectweb.jonas_ejb.level DEBUG
Example for setting the output of JOnAS traces both on console and 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 on a file in
$JONAS_BASE/logs/
directory:
handler.logf.output automatic logger.org.objectweb.jonas.handler.0 logf
JOnAS may be seen like 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.
Here is the 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 they appear
in the list. Therefore, the following constraints should be considered:
Considering de following example:
jonas.services registry,jmx,jtm,dbm,security,resource,jms,mail,ejb,web,ear
The registry could be omitted from the list as this service is
automatically launched if it is not already activated by another previously
started server. Same thing is true for jmx, as since JOnAS 3.1 this service
is automatically launched after the registry.
The dbm, resource, and jms services are listed after
the jtm, for the reason mentioned above.
The application components deployed on this server can use Java Messaging
and Java Mail as jms and mail are listed before ejb.
Configuration parameters for services are located in the
jonas.properties
file following a precise 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 made in
carol.properties
, see
Configuring the Communication Protocol and JNDI.
There are several Registry launching modes depending 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 JOnAS Server,remote
: the Registry has to be launched before 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 main 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 jonas.properties
file. If the file name does not
contain an absolute path name, then 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 in $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 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 2 implementations of this service. One for Jetty 4.2.x,
one for Tomcat 4.1.x.
It is necessary to run it when you want to use the
Jadmin
tool.
If the environment variables $JETTY_HOME
or
$CATALINA_HOME
are not set, the web container service can't
be loaded at the JOnAS startup. So a warning is displayed.
A WEB container is created from a war
file. If the file name does not contain
an absolute path name, then it should be located in the
$JONAS_BASE/webapps/
directory.
In order for JOnAS to create WEB containers, the corresponding file names
may be provided using the jonas.service.web.descriptors
property
in jonas.properties
file. In this case, the WEB containers are created when the
JOnAS server starts.
Example:
jonas.service.web.descriptors Bank.war
Here the WEB Container service will create a container from the
war
file named Bank.war
.
This file will be searched in $JONAS_BASE/webapps/
directory.
In order to improve the development process, you can also use webapp directories instead
of packaging a new war file at each time. So you can replace the classes by the new compiled
classes and reload the servlets in your browser and see immediatly the changes. This is also the
case 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 for using the jonasAdmin/ webapp directory
instead of jonasAdmin.war
JONAS_BASE/webapps/autoload
directory
JONAS_BASE/webapps/autoload/jonasAdmin
jonasAdmin.war
file to this directory
WEB containers may be also dynamically created from war
files
using the Jadmin
tool.
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 upon the WEB container service and the
EJB container service. The WEB container service is
used to provide the WEB containers for the wars
composing
the J2EE application, and the EJB container service is used to
provide the EJB containers for the ejb-jars
composing 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
Here the EAR service will deploy the ear
file
named Bank.ear
.
This file will be searched in $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.
It is a mandatory service. The Transaction service uses a
Transaction manager that may be local or launched in another JVM (a remote
Transaction manager). Typically when there are several JOnAS servers working
together, one of the Transaction service must be considered as the
master and the other as slaves. The later must be configured
as working with a remote Transaction manager.
Here is an example of configuration of two servers, one named TM in which a
stand alone Transaction service will be run, the second named EJB will be
used to deploy some 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 is the value of the transaction
time-out, in seconds, via the
jonas.service.jtm.timeout
property.
Here is the default configuration:
jonas.service.jtm.timeout 60
In order to be able to access one or several relational databases (e.g. Oracle, InstantDB, PostgreSQL, ...), JOnAS will create and use DataSource objects. You have to configure such a DataSource object according to the database you intend to use for the persistence of a bean. More details about DataSource objects and their configuration is provided in the "Configuring JDBC DataSources" chapter of the Bean Programmer's Guide.
The subsections below briefly explains how to configure a DataSource object for your database, in order to be able to run the Entity Bean example delivered with the platform.
Note that you may also easily trace the SQL requests sent to the Database by relying on the JOnAS Logging system and on 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
.
You must update this template with values proper 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 you are 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 lesser versions |
datasource.username | Database user name |
datasource.password | Database user password |
In order that the EJB platform creates the corresponding DataSource object,
you must have its name (Oracle1, not the JNDI name) in your
jonas.properties
file, on the jonas.service.dbm.datasources line:
jonas.service.dbm.datasources Oracle1
You may have several DataSource objects defined for an EJB server, in this case, you will have several dataSourceName.properties files, and the list of DataSource names on the jonas.service.dbm.datasources line of the jonas.properties file:
jonas.service.dbm.datasources Oracle1, Oracle2, InstantDB1
Your Oracle server must be running, and a JDBC driver installed (Oracle
JDBC drivers may be downloaded at their Web site).
You can then create the table used by the example with the SQL script
provided in examples/src/eb/Account.sql
.
For example:
sqlplus user/passwd SQL> @Account.sql SQL> quit
The JDBC driver classes must be accessible from the classpath. For that, you must
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. You must update this template with values proper 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
|
In order that the EJB platform creates the corresponding DataSource object,
you must have its name (InstantDB1, not the JNDI name) in your
jonas.properties
file, on the jonas.service.dbm.datasources line
jonas.service.dbm.datasources InstantDB1
InstantDB should have been properly installed and configured. You should use a version higher than 3.14. (examples have been tested with 3.25).
The JDBC driver classes must be accessible from the classpath. For that, you must
update the config_env file;
($JONAS_ROOT/bin/unix/config_env
on Unix,
or %JONAS_ROOT%\bin\nt\config_env.bat
on Windows).
You have to 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 kind of process can be used for other databases. We supply with JOnAS a template of datasource for PostgreSQL and for InterBase. Of course many other databases are currently used by the JOnAS users, e.g. Informix, Sybase, SQL Server, ... however 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 found 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.
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!), in order to
allow the security context propagation across method calls, see also
Security and Transaction Context Propagation.
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" />
You can use a memory, Datasource or LDAP resource for the authentication. Put the right name of the specified resource as resourceName ie : memrlm_1, memrlm_2, dsrlm_1, ldaprlm_1, etc.
For using Jetty interceptors in your web application you must provide a web-jetty.xml
file under WEB-INF
directory in the .war
file
in which it specified that the
security interceptor org.objectweb.jonas.security.realm.JRealmJetty42
for JOnAS must be used instead of the default one.
ie : 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>
You can find some web-jetty.xml examples in the earsample
example and alarm
demo.
JOnAS relies on the
jonas-realm.xml
file for the access control to the methods of EJB components.
Example : we have 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>
And now we want add a user which have the specified role (jonas) and which is authorized to call methods, etc.
How to configure the different resource in order to do the authentication
jonas-realm.xml
file
We have to add a role. The role 'jonas
'.
In the <roles>
section we put our role :
<roles> <role name="jonas" description="Role used in our sample security howto" /> </roles>Now, we have to add a user with the specified role
<users>
section we add a user with the 'jonas
' role : <users> <user name="jonas_user" password="jonas_password" roles="jonas" /> </users>
The <groups> section allow to group roles.
The memory resource to add in the jonas-realm.xml
file is :
<jonas-memoryrealm> [...] <memoryrealm name="howto_memory_1"> <roles> <role name="jonas" description="Role used in our sample security howto" /> </roles> <users> <user name="jonas_user" password="jonas_password" roles="jonas" /> </users> </memoryrealm> [...] </jonas-memoryrealm>
jonas-realm.xml
file
First, we have to build our tables in order to store our users, roles.
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 your table can contain more than two columns.
jonas
to the user jonas_user
user_name | role_name |
... | ... |
jonas_user | jonas |
... | ... |
Now we can declare our resource in the jonas-realm.xml
file.
The dsName
element describes the JNDI name of the datasource to use.
So, you have to set in your jonas.properties
file a Datasource configuration with the right JNDI name for the dbm
service.
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
file
We have to add the user in our LDAP server.
In our case, all the users are on the ou=people,dc=jonas,dc=objectweb,dc=org
DN.
The distinguished name will be for example : DN uid=jonas_user,ou=people,dc=jonas,dc=objectweb,dc=org
for the user 'jonas_user'
The role jonas will be add on the ou=groups,dc=jonas,dc=objectweb,dc=org
DN.
In our 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 we can customize the jonas-realm.xml
file by adding a LDAP resource.
There are two ways for the authentication : the bind or the compare method.
By default, this is the bind method which is used.
All the elements of the configuration for the ldap resource can fe found on the jonas-realm_1_0.dtd DTD file.
In our sample, we suppose that the LDAP server is on the same computer and is on the default port (389).
So we take 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 authentification based on client certificate in your Web container, you will have to :
Configure the Realm the Web container will have to use
Configure an SSL listener on the Web container
Configure your Web application to make it ask a client certificate
Configure the JAAS LoginModules
Populate the Realm access list
It will be mandatory that you 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 Autority or can be autosigned.
If you have installed the JOnAS-Tomcat package, you can skip that 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. So, to choose the ressource where to look for authentication data, configure JAAS.
Edit the web-jetty.xml
file under WEB-INF
directory in the .war
file, 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. So,
to choose the ressource where 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 : put the clientAuth
parameter to
false, otherwise all your Web applications will ask for a client
certificate if they need SSL. You will configure the client
authentication later, in the web.xml
file in the specific .war
files.
If you want 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 one of these two directories, depending on if you are
using Jetty in standalone or not : $JETTY_HOME/conf
or $JONAS_BASE/conf
,
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 keystore is the repository where you have to store the certificate of Jetty. This is the certificate that will present Jetty when a connection would be about to be established.
If you want more information, refer to http://jetty.mortbay.org/jetty/doc/SslListener.html
Add to the web.xml
file of the .war
file
of your Web application the following lines:
<login-config> <auth-method>CLIENT-CERT</auth-method> <realm-name>Example Authentication Area</realm-name> </login-config>
Important :
For both Tomcat and Jetty, be sure
that your 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, be sure that the Web application is always accessed with SSL unless the Web container won't get any certificate and won't be able to authentificate the user.
For both Tomcat and Jetty, when you enable authentication on client certificate, the user's Web browser receive the list of the Certification Authorities the Web site (your Web application) trusts. A connection will be established with the client only if this one has got a certificate issued by one of those Certification Autorities, otherwise his certificate will be rejected.
In Jetty, you have to import inside the keystore you specified in the SSL listener, the certificates of all the Certification Autorities you trust.
In Tomcat, you have to import
the certificates of all the Certification Autorities you trust in the $JAVA_HOME/jre/lib/security/cacerts
keystore file (you can modify this location by customising the SSL listener).
For Jetty, as you set the parameter NeedClientAuth
to true in the jetty.xml
file, ALL the Web applications
accessed with SSL will ask the user to present a certificate. Use
differents SSL listeners on differents ports if you want both Web
applications that requiere client certificate and Web applications that
does not.
For Jetty, remember to set the same realm-name
as
the one in the web-jetty.xml
file
For Jetty, if you want more information, refer to http://jetty.mortbay.org/jetty/doc/ClientCert.html
This authentication process is built on the JAAS technology. This
means that the authentication is performed in a pluggable way and the
desired authentication technology is specified at runtime. That's why
you have to 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
to use it in every authentication because it verifies the user
authentication information in the specified ressource.
It takes only one parameter :
resourceName
: the name
of the entry in the "jonas-realm.xml " file you want to use; this
entry represents how and where the authentification information are stored.
"org.objectweb.jonas.security.auth.spi.CRLLoginModule"
CRLsResourceName
: in this parameter, you specify how your CRLs are stored :
"Directory"
: in case your CRL files are stored in directory on the machine; you have to specify another parameter to point that directory :
CRLsDirectoryName
: the directory containing the CRL files (the files extension must be .crl).
"LDAP"
: in case your CRL files are stored in a LDAP repository; this functionnality is experimental; you have to specify two others parameters :
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 is described the
login module to use for authentication. This file is located in $JONAS_BASE/conf
and named jaas.config
. You can change its location and
name by editing the $JOANS_BASE/bin/jonas.sh
script and
modifying the following line :
-Djava.security.auth.login.config=$JONAS_BASE/conf/jaas.configThe content of the JAAS configuration file follows that 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 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"; };
You can have multiple entries in this file, specifying differents
configuration that JOnAS can use. There are two specificities : the
entry dedicated to Tomcat must be named tomcat
, and the
one for Jetty, jetty
. Remember that everything inhere 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 continues to proceed down the LoginModule list.
requisite
- The LoginModule is required to succeed. If it succeeds,
authentication continues down the LoginModule list. If it fails,
control immediately returns to the application (authentication does not
proceed down 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 down the LoginModule list). If it fails, authentication
continues down the LoginModule list.
optimal
- The LoginModule is not required to succeed. If it succeeds or fails,
authentication still continues to proceed down the LoginModule list.
Now users won't have to enter a login/password but just presenting
their certificates, this thing will be done transparently by the browser
(after the user has imported his certificate into). So the identity
presented to the server is not a login but a Distinguished Name : this
is the name identifying the person to whom belongs the certificate.
This name looks like this :
CN=Someone Unknown, OU=ObjectWeb, O=JOnAS, C=ORGE : Email Address
Subject
in a
certificate, sometimes there are a few more (Title, Street Address,
Postal Code, Phone Number).jonas-realm.xml
, in a memory realm for
example, there was :
<user name="jps_admin" password="admin" roles="administrator"/>
If you want to enter a certificate based user access, you'll have to
enter his DN preceded from the String: ##DN##
so it will be
like that :
<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 may also be used, other JMS provider implementations may 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
previously to the EJB execution, by the way of the proprietary JMS implementation
administration facilities. JOnAS provides "wrappers" upon 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.
Here are the properties that may 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 JOnAS Server (this is
the default value), if set to false it is launched in a separate JVM in
this case the jonas.service.jms.url
must be set with the connexion 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 what class must be used to perform
administrative operations. This class is the wrapper to the actual JMS provider
implementation. The default one is org.objectweb.jonas_jms.JmsAdminForJoram
that must be used for Joram.
You may get a com.swiftmq.appserver.jonas.JmsAdminForSwiftMQ class from the
SwiftMQ site if you intend to use the SwiftMQ product.
Some complement information about JMS configuration (and in particular some JORAM advanced configuration aspects) are provided in the JMS Administration and Running an EJB performing JMS operations sections of the Using JMS in application components chapter.
The Connector Architecture Resources service is an optional service that must be started as soon as EJB components have to 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 Connector Architecture Resources 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 way to configure the Connector Architecture Resources service is one of the following methods:
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.
In each resource adapter a jonas specific resource adapter configuration xml file must be included. This file reflects the values of all configuration properties declared in the deployment descriptor for the resource adapter. See Using a Connector Architecture Resource Adapter with JOnAS for additional information.
The JMX service must be started in order to administrate or instrument
JOnAS server via
Jadmin
. This is a mandatory service and
it will be started even if it is not present in the list of the services. Its configuration consists in
choosing one of the two supported JMX implementations, SUN RI or MX4J. The choice
is done 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 choosing the SUN RIorg.objectweb.jonas.jmx.mx4j.Mx4jJmxServiceImpl
, for choosing MX4JThe Mail service is an optional service that may be used to send email.
It is based upon
JavaMailTM
and on JavaBeansTM Activation Framework (JAF) API.
In order to be able to send or receive mails we need a mail factory,
JOnAS provides two types of mail factories: javax.mail.Session
and javax.mail.internet.MimePartDataSource
.
MimePartDataSource
factories allow you to send mails with
a subject and recipients already set.
Mail factory objects must be configured accordingly to their type.
The subsections below briefly explain how to configure Session
and MimePartDataSource
mail factory objects,
in order to be able 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
.
You must update this template with values proper 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
.
You must update this template with values proper to your installation.
You'll find in the section "Configuring a mail factory" the list of
available properties.
Let's see before, how to configure JOnAS in order to create the mail factory objects
you need.
In order for JOnAS to create mail factory objects,
you must name them. In the mailsb example, we defined 2 factories called
MailSession1 and MailMimePartDS1.
For each factory we provided a configuration file named with the name of the
factory and having the .properties
extension
(MailSession1.properties
for the MailSession1 factory).
Also, the jonas.properties
file must define the
jonas.service.mail.factories
property. In the case of our
example, we have:
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(see 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 isn't 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 isn't 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 |