The application got one main setup file. However, if JAAS security and user authentication is used other setup files are mandatory as well. All setup and configuration files are stored in $APP_HOME/WEB-INF/classes.
- jproject.properties
-
This is the main setup file. Various properties can be setup. See Section 3.1, “Project property file [jproject.properties]” for more details.
- log4j.properties
-
Log4J is used as an application logger. Check http://logging.apache.org/log4j/docs/ for more details how to use the logger.
- hibernate.properties
-
Config File of the persistence layer. Hibernate (http://www.hibernate.org) is used the standard persistence mechanism. See Section 3.3, “Persistance Layer (Hibernate)” how to setup Hibernate for this application.
- jproject.jaas
-
Defines the LoginModule used by the system. Check Section 3.4, “Login and User Authentication” for more details.
- policy.xml
-
Standard, principal based policy file used by the policy provider shipped with this application. Define permissions to user based on principals used by JAAS. If you change the JAAS login module to other but those provided by the application (Standard and LDAP), you need to adjust this file to your principals and values.
- jproject.policy
-
Example policy file if the standard Sun / Java policy provider is used. Those entries needs to be placed in the standard VM policy file.
- font.properties
-
Fonts definition file if PJA must be used to support the reporting subsystem. (Linux, JDK 1.3).
Table 3.1. Property
| Property name | Purpose |
|---|---|
| LOGGER | Switches the logger on or off. |
| STYLE | Standard css file used by the system if no other are defined by the user. |
| DEBUG_TIME | If set to "true" JSP and action processing times will be shown on every page footer. |
| ENCODE_PASSWORDS | If set to "true" passwords in the user table will be encoded |
| currency.name | standard currency; valid values may depend on your VM [ADP - ATS - BEF - BGL - BOV - BYB - CLF - DEM - ESP - EUR - FIM - FRF - GRD - IEP - ITL - LUF - MXV - NLG - PTE - RUB - USN - USS - XAF - XAG - XAU - XBA - XBB - XBC - XBD - XCD - XDR - XFO - XFU - XOF - XPD - XPF - XPT - XTS] |
| currency.symbol | standard currency symbol |
| currency.useVMSettings | If set to true (standard), VM settings will be used instead of above settings. Note that you might get problems with older VM versions; they will not show EURO as currency for european countries but the old country currency e.g. DM, etc. |
| standard.policy.profile | needs to be a valid profile defined in the policy file (see Section 3.6, “User/Principal Permissions”); this profile will be used for new created users |
| languages | languages supported by the system; e.g. de, en, de_DE, en_US, en_UK etc. |
| global.security.usejaas |
If you are running on JDK 1.4 or higher, the use of JAAS for authorization is recommended. The Standard [jcon.jproject.jaas.BasePolicy] will handle the policy.xml file. Any other Policy Provider might me used. If you are using JDK 1.3, JAAS is not supported for authorization. However, if you switch off the use of JAAS via this property, no policy provider will be used, neither the standard one nor the one you might provide via the property [policy.provider]. The standard policy.xml file will be read in an normal way, and the authorization will take place as usual. No own implementation can be used if you switch this property off. If you want to use JAAS authorization even in an JDK 1.3 environment you might either use your own policy provider or use the standard policy provider of your JDK. An example policy file for use with Sun's policy provider implementation is shipped with this application. |
| jproject.security.auth.policy | Path to the standard policy file. Specify this, if you have problems with the automatic find process of the application. |
| java.security.auth.login.config | Path to the login module config file. Specify this, if you have problems with the automatic find process of the application. |
| policy.provider |
Define the policy provider if needed. If you are using JDK 1.3 the standard application policy de.jcon.jproject.jaas.BasePolicy should be not declared as the policy provider. This policy only works from JDK 1.4 on. |
| jproject.plugin.dir | Path to the plugin directory relative to the web content directory. Specify this, if you have problems with the automatic find process of the application. |
| report.compile.dir | Path to the report directory where the compiled reports should be placed. Specify this, if you have problems with the automatic find process of the application. |
| ldap.login.username | LDAP user |
| ldap.login.pwd | LDAP password |
| ldap.context.factory | specifies the context factory used to access the server |
| ldap.provider.url | the URL to connect to |
| ldap.search.context | an optional context for defining an additional filter |
| ldap.mapping.attr.uid | the LDAP attribute used for uid verification |
| ldap.mapping.attr.password | the LDAP attribute used for password verification |
| ldap.mapping.attr.roles | the LDAP attribute used to get the roles needed for getting the right policy authorization |
| person.accessor.factory | Factory for person accessor. Use the LDAP factory if you want to access or LDAP directory as the pool for your client data. See Section 3.5, “LDAP Accessor config” for more details. |
| company.accessor.factory | NOT SUPPORTED IN VERSION 0.1.2 !! Factory for company accessor. Use the LDAP factory if you want to access or LDAP directory as the pool for your client data. See Section 3.5, “LDAP Accessor config” for more details. |
| java.awt.headless | Some "headless" operating systems (e.g. Linux) have problems by accessing classes from the graphical environment within Java. So this feature got introduced in JDK 1.4. See Section 3.7, “Reporting config” for more details. |
| SSHA_SALT | SSHA "salt" string to beeing applied for SSHA key generation and verification. Note that if you change this string, all SSHA keys stored in your database will not be able to beeing verified anymore. |
-
Setup Section 3.3, “Persistance Layer (Hibernate)”. This is mandatory.
Just start the setup page with http://$yourserver$:$yourport$/jproject/setup.jsp.
-
You have to specify your userid, password and DB Dialect.
-
Specify either your DataSource OR
-
Specify your database connection by setting your DB Driver and DB URL.
-
Hit Save to save your property file to your chosen destination. (Standard is $WEBAPP_HOME/jproject/WEB-INF/classes). It needs to go in a path, which is available via the CLASSPATH settings.
![[Tip]](../images/admons/tip.png)
Tip You might not be able to save to your chosen directory due to the security constraints of your application server. If this happens you need to save the hibernate.properties file somewhere else and copy it manually to the origin destination.
You need to save the properties first before you can initialize the database. Make sure that you wait that amount of time your application server needs to reload changed resources. If the automatic reload feature is disabled for your server, you can change the settings and initialize the database only once. Further changes to the persistence setup within the same session, will not being applied until you restart your servlet container!
-
If you wish to initialize your database, hit Initialize Database.
![[Note]](../images/admons/note.png)
Note All tables will be dropped and recreated if you reinitialize your database. To prevent that this might happen by accident, you should remove the setup.jsp file after you finished the setup. You can try to do this automatically by selecting the appropriate checkbox. Again, your security settings might prevent you from doing this via an JSP file, so you have to do this manually.
Check the output on the page if your tables have been successfully created. Should there be an error, check your settings.
An example hibernate.properties file might look like this:
#Property file generated by jProject Business Suite Setup. #Thu Mar 11 11:55:00 CET 2004 hibernate.connection.driver_class=com.mysql.jdbc.Driver hibernate.dialect=net.sf.hibernate.dialect.MySQLDialect hibernate.jdbc.use_streams_for_binary=true hibernate.jdbc.batch_size=0 hibernate.query.substitutions=true 1, false 0, yes 'Y', no 'N' hibernate.query.imports=net.sf.hibernate.test, net.sf.hibernate.eg hibernate.connection.username=test hibernate.use_outer_join=true hibernate.proxool.pool_alias=pool1 hibernate.jdbc.use_scrollable_resultset=true hibernate.connection.url=jdbc\:mysql\://localhost/test hibernate.connection.password=test hibernate.show_sql=false hibernate.connection.pool_size=1 hibernate.statement_cache.size=25
You might either want to use the internal user verification system or the Java Authentication and Authorization Service (JAAS) provided by Java. This service has been included in the JDK 1.4.
|
|
Note |
|---|---|
|
The Java Authentication and Authorization Service (JAAS) is a set of APIs that enable services to authenticate and enforce access controls upon users. It implements a Java technology version of the standard Pluggable Authentication. Check http://java.sun.com/products/jaas/overview.html for more details. |
|
If the global.security.usejaas is set to false (standard), the internal user verification is used for authentication.
You can use the JAAS Authentication Service by specifying a LoginModule. Several login modules are already shipped with JDK 1.4, e.g.
-
Java Naming and Directory Interface (JNDI)
-
UNIX Operating Environment
-
Windows NT
-
Kerberos
-
Keystore
By using JAAS, you can reuse your already existing user database or verification mechanism. You can even provide your own LoginModule. See http://java.sun.com/developer/technicalArticles/Security/jaasv2/index.html for more details.
An example jproject.jaas file might look like this:
jprojectJaas {
de.jcon.jproject.jaas.login.StandardLoginModule required debug=true;
/*de.jcon.jproject.jaas.login.LDAPLoginModule required debug=true;*/
/*com.tagish.auth.DBLogin required dbDriver="sun.jdbc.odbc.JdbcOdbcDriver" dbURL="jdbc:odbc:DBLogin";*/
/*com.tagish.auth.win32.NTSystemLogin required returnNames=true returnSIDs=false defaultDomain="domain";*/
/*com.tagish.auth.FileLogin required debug=true pwdFile="/path/to/passwd";*/
/*com.sun.security.auth.module.Krb5LoginModule required debug=true useTicketCache=false;*/
};
The property global.security.usejaas needs to be set to true if you want to use JAAS. You specify you login module in the jproject.jaas config file. The application comes with the support of two own login modules.
Note that the standard Sun modules:
-
com.sun.security.auth.module.NTLoginModule
-
com.sun.security.auth.module.UnixLoginModule
will not work with this application because the don't use callback handlers to validate application specifics enties of userid/password. They will only validate the user under which context the application is running on.
-
For standard validation against the application user tables use:
de.jcon.jproject.jaas.login.StandardLoginModule required debug=true
-
For validating on LDAP or Active Directory use (see: user documentation for config parameters):
de.jcon.jproject.jaas.login.LDAPLoginModule required debug=true
-
For validating on an NT domain (only available for NT/2000 OS, not XP!) use (see: http://free.tagish.net/jaas/doc.html):
com.tagish.auth.win32.NTSystemLogin required returnNames=true returnSIDs=false defaultDomain="domain"
-
For validating on Linux / Win2000 domain with Kerberos protocol use:
com.sun.security.auth.module.Krb5LoginModule required debug=true useTicketCache=false
-
For validating on database tables use (see: http://free.tagish.net/jaas/doc.html):
com.tagish.auth.DBLogin required dbDriver="sun.jdbc.odbc.JdbcOdbcDriver" dbURL="jdbc:odbc:DBLogin"
-
For validating on a file use (see: http://free.tagish.net/jaas/doc.html):
de.jcon.jproject.jaas.login.StandardLoginModule required debug=true;
-
For standard validation against the application user tables use:
com.tagish.auth.FileLogin required debug=true pwdFile="/path/to/passwd"
|
|
Note |
|---|---|
|
Note that at the moment only the standard JAAS module has support for user profiles / roles defined within the policy.xml file! All other login modules will assign the standard user profile. This will be enhanced during the next releases. |
|
- de.jcon.jproject.jaas.login.StandardLoginModule (standard)
-
Wrappes the standard user verification mechanism within this JAAS module. If JAAS is enabled and this module is specified the user authentication takes place in the same way as JAAS wouldn't be enabled.
- de.jcon.jproject.jaas.login.LDAPLoginModule
-
This login module can be used to access an LDAP Server for user authentication. You need to specify the following parameters in the jproject.properties file:
Table 3.2. Configuration properties for LDAP Login Module
Property name Purpose ldap.login.username LDAP user ldap.login.pwd LDAP password ldap.context.factory specifies the context factory used to access the server ldap.provider.url the URL to connect to ldap.search.context an optional context for defining an additional filter ldap.mapping.attr.uid the LDAP attribute used for uid verification ldap.mapping.attr.password the LDAP attribute used for password verification ldap.mapping.attr.roles the LDAP attribute used to get the roles needed for getting the right policy authorization An example config might look like this:
ldap.login.username=cn=admin,dc=jconhome,dc=com ldap.login.pwd=admin ldap.context.factory=com.sun.jndi.ldap.LdapCtxFactory ldap.provider.url=ldap://jconserver/ ldap.search.context=ou=devel,dc=jconhome,dc=com ldap.mapping.attr.uid=uid ldap.mapping.attr.password=userPassword ldap.mapping.attr.roles=employeeType
You need to set the person.accessor.factory property to de.jcon.jproject.accessor.ldap.LDAPPersonBOAccessorFactory (Standard is: de.jcon.jproject.accessor.PersonBOAccessorFactory) if you want to use the LDAP person accessor. In addition to this, you need to configure this accessor with following properties:
Table 3.3. Configuration properties for LDAP Accessor Module
| Property name | Purpose |
|---|---|
| ldap.person.ldapversion | LDAP version |
| ldap.person.login.username | LDAP user |
| ldap.person.login.pwd | LDAP password |
| ldap.person.context.factory | specifies the context factory used to access the server |
| ldap.person.provider.url | the URL to connect to |
| ldap.person.search.context | an optional context for defining an additional filter |
| ldap.person.create.template | LDAP entry which is used a template for the creation of new records. This entry needs to be specified if you wish to create new persons/companies. |
| ldap.person.mapping.attr.ID | the LDAP attribute used for id verification; note that this attribute will be changed by the application if you connect to an existing LDAP system once this component will be enhanced by application specific values (e.g. ROLES, etc.) |
| ldap.person.mapping.attr.$XYZ$ | Other LDAP attributes which needs to be mapped to an person object. |
| ldap.person.mapping.pk.USERID | Specify the primary key of a person object which is used in relation to other entries in the application database. |
An example config might look like this:
ldap.person.ldapversion=3 ldap.person.login.username=cn=admin,dc=jconhome,dc=com ldap.person.login.pwd=admin ldap.person.context.factory=com.sun.jndi.ldap.LdapCtxFactory ldap.person.provider.url=ldap://jconserver/ ldap.person.search.context=ou=devel,dc=jconhome,dc=com ldap.person.create.template=cn=admin,ou=devel,dc=jconhome,dc=com ldap.person.maximum.fetch=10000 ldap.person.mapping.attr.ID=internationaliSDNNumber ldap.person.mapping.attr.LASTNAME=sn ldap.person.mapping.attr.FIRSTNAME=givenName ldap.person.mapping.attr.BIRTHDAY=birthDate ldap.person.mapping.attr.CITY=l ldap.person.mapping.attr.ZIPCODE=postalCode ldap.person.mapping.attr.COUNTRY=preferredLanguage ldap.person.mapping.attr.STREET=postalAddress ldap.person.mapping.attr.POBOX=postOfficeBox ldap.person.mapping.attr.PHONE1=homePhone ldap.person.mapping.attr.PHONE2=telephoneNumber ldap.person.mapping.attr.FAX=facsimileTelephoneNumber ldap.person.mapping.attr.EMAIL=mail ldap.person.mapping.attr.MOBILE=mobile ldap.person.mapping.attr.WEB=pager ldap.person.mapping.attr.DESCRIPTION=description # # not that this mapping is just an example # if there is a standard RCF schema for mapping this # attributes, of course this should be used # ldap.person.mapping.attr.BANK_ACCOUNT=departmentNumber ldap.person.mapping.attr.BANK=businessCategory ldap.person.mapping.attr.BANK_ID=carLicense # # this USERID is part of the primary key and NOT the userid # of a USERROLE # ldap.person.mapping.pk.USERID=destinationIndicator
The company accessor is setup in the same way.
|
|
Note |
|---|---|
|
Note, that the LDAP person and company accessor is still an experimental feature. Although it might be possible to switch the accessors in an already running system (as long as the USERID feature uses the same key) its definitely not recommended. You should decide once you setup your system, which accessor you use. Of course you can export/import data at the same way independent which accessor type you use. The system might even store some data redundant in database tables, even if you use the LDAP accessor. This has mainly technical reasons and is used for better SQL performance ;-( |
|
Permission Config.
Use following values to define permissions:
- $application$.create
-
create permission
- $application$.read
-
read permission
- $application$.update
-
update permission
- $application$.delete
-
delete permission
- $application$.report
-
report permission
- $application$.*
-
all permissions
If you want to specify permissions on your own, you have to add all permissions you need.
E.G. A test for a "read" permission will fail if you just specify a "create" permission. You have to add the read permission as well.
Supported permission sections:
-
home
-
logout
-
project
-
uow
-
travel
-
invoice
-
invoiceRec
-
timeRecord
-
car
-
person
-
company
-
role
-
group
-
relation
-
settings
-
user
-
password
Of course there are combinations of this sections which don't make sense at all. However, you can specify profile in a way you like.
For JDK 1.4 the recommended way to define your policies/permissions is via the internal PolicyProvider and the policy.xml file.
<permissions> <!-- Principal with role = standard --> <principal> <class>de.jcon.jproject.jaas.JaasRolePrincipal</class> <value>standard</value> <permission> <class>de.jcon.jproject.jaas.StandardPermission</class> <value>home.*</value> <action></action> </permission> <permission> <class>de.jcon.jproject.jaas.StandardPermission</class> <value>logout.*</value> <action></action> </permission> .... <permission> <class>de.jcon.jproject.jaas.StandardPermission</class> <value>project.read</value> <action></action> </permission> </principal> <!-- Principal with role = admin --> <principal> <class>de.jcon.jproject.jaas.JaasRolePrincipal</class> <value>admin</value> <permission> <class>de.jcon.jproject.jaas.StandardPermission</class> <value>home.*</value> <action></action> </permission> <permission> <class>de.jcon.jproject.jaas.StandardPermission</class> <value>logout.*</value> <action></action> </permission> ... <permission> <class>de.jcon.jproject.jaas.StandardPermission</class> <value>project.*</value> <action></action> </permission> </principal> </permissions>
If you choose the use the standard policy provider shipped with your VM, you might define the principal permission in another way. Check your documentation how to setup your VM with Java security permissions.
E.G. Sun's VM uses properties files to define permissions. Check the programlisting.
// principal based - JDK 1.4
grant principal de.jcon.jproject.jaas.JaasRolePrincipal
"standard" {
permission de.jcon.jproject.jaas.StandardPermission "home.*";
permission de.jcon.jproject.jaas.StandardPermission "logout.*";
permission de.jcon.jproject.jaas.StandardPermission "project.read";
permission de.jcon.jproject.jaas.StandardPermission "uow.*";
permission de.jcon.jproject.jaas.StandardPermission "travel.*";
permission de.jcon.jproject.jaas.StandardPermission "invoice.*";
permission de.jcon.jproject.jaas.StandardPermission "timeRecord.*";
permission de.jcon.jproject.jaas.StandardPermission "car.*";
permission de.jcon.jproject.jaas.StandardPermission "person.*";
permission de.jcon.jproject.jaas.StandardPermission "company.*";
permission de.jcon.jproject.jaas.StandardPermission "role.*";
permission de.jcon.jproject.jaas.StandardPermission "group.*";
permission de.jcon.jproject.jaas.StandardPermission "relation.*";
permission de.jcon.jproject.jaas.StandardPermission "settings.*";
};
// principal based - JDK 1.4
// this principal can do everything
grant principal de.jcon.jproject.jaas.JaasRolePrincipal
"admin" {
permission de.jcon.jproject.jaas.StandardPermission "home.*";
permission de.jcon.jproject.jaas.StandardPermission "logout.*";
permission de.jcon.jproject.jaas.StandardPermission "project.*";
permission de.jcon.jproject.jaas.StandardPermission "uow.*";
permission de.jcon.jproject.jaas.StandardPermission "travel.*";
permission de.jcon.jproject.jaas.StandardPermission "invoice.*";
permission de.jcon.jproject.jaas.StandardPermission "timeRecord.*";
permission de.jcon.jproject.jaas.StandardPermission "car.*";
permission de.jcon.jproject.jaas.StandardPermission "person.*";
permission de.jcon.jproject.jaas.StandardPermission "company.*";
permission de.jcon.jproject.jaas.StandardPermission "role.*";
permission de.jcon.jproject.jaas.StandardPermission "group.*";
permission de.jcon.jproject.jaas.StandardPermission "relation.*";
permission de.jcon.jproject.jaas.StandardPermission "settings.*";
permission de.jcon.jproject.jaas.StandardPermission "user.*";
};
// standard JDK 1.3 - no different roles/principals are supported
grant {
permission de.jcon.jproject.jaas.StandardPermission "home.*";
permission de.jcon.jproject.jaas.StandardPermission "logout.*";
permission de.jcon.jproject.jaas.StandardPermission "project.*";
permission de.jcon.jproject.jaas.StandardPermission "uow.*";
permission de.jcon.jproject.jaas.StandardPermission "travel.*";
permission de.jcon.jproject.jaas.StandardPermission "invoice.*";
permission de.jcon.jproject.jaas.StandardPermission "timeRecord.*";
permission de.jcon.jproject.jaas.StandardPermission "car.*";
permission de.jcon.jproject.jaas.StandardPermission "person.*";
permission de.jcon.jproject.jaas.StandardPermission "company.*";
permission de.jcon.jproject.jaas.StandardPermission "role.*";
permission de.jcon.jproject.jaas.StandardPermission "group.*";
permission de.jcon.jproject.jaas.StandardPermission "relation.*";
permission de.jcon.jproject.jaas.StandardPermission "settings.*";
permission de.jcon.jproject.jaas.StandardPermission "user.*";
};
The application uses the open source framework Jasper Reports as the core reporting system. There are a lot of tools who helps you writing your own reports or adjusting the standard reports shipped with the system. Additional reports can be easily added via the plugin interface (see Chapter 5, Plugin Development and Configuration ). For additional information how to create new reports please refer to http://jasperreports.sourceforge.net. You can find even some links to good GUI based WYSIWYG report creation tools.
There are some prerequisites that the reporting system is able to run on an application server / servlet container. The Java VM or the operation system itself needs to support the so called headless environment feature. Thus the system need to support a graphical environment even if there is no graphical environment (e.g. X-Server) running.
At the moment there are no problems running on Windows, but on Linux. There are two solution to get the reporting system run on Linux:
-
Use JDK 1.4 and switch the headless.property via the jproject.properties file on.
-
If you have to use JDK 1.3, you need to install the PJA Toolkit from Eteks (see http://www.eteks.com/pja/en/).
-
Add -Xbootclasspath/a:"$your_path_to$/pja.jar" to the vm startup option of your servlet container. It's not enough to just adjust the CLASSPATH!!
-
Enable following properties in the Section 3.1, “Project property file [jproject.properties]” setup file:
awt.toolkit=com.eteks.awt.PJAToolkit java.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment java2d.font.usePlatformFont=false user.home=./WEB-Content/Web-inf