Embedded Files
Linux or Windows Operating System
Tomcat 5.0 or greater (and Java 5.0 or greater)
MySQL 5.0 (use UTF-8 as character set). Recent versions of MySQL have changed the way "dialects" are handled. Use MySQL 5.0.
A running Active Directory domain controller (Windows Server 2003 or 2008)
A service account with domain admin rights to access active directory (admin rights are needed for account and group updates)
An encryption certificate accepted by your domain controller (to set passwords through the application)
A basic knowledge of Tomcat and MySQL is required to perform this installation. The assistance of your Active Directory administrator might be required as well.
Create and populate the MySQL databases
In this documentation, Windows is assumed with C:\Documents and Settings\Thierry\My Documents\directory being the folder where you extracted the application files. Settings highlighted in orange need to be modified.
Open a MS-DOS command session.
cd C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\installmefirst
mysql -u root -prootpassword
create database directory;
use directory;
source ./sql/main-directory/shared/install/mysql/install_all_shared_mysql.sql;
create database session;
use session;
source ./sql/framework/core/session/install/mysql/install_all_session_mysql.sql;
create database organization;
use organization;
source ./sql/framework/core/organization/install/mysql/install_all_organization_mysql.sql;
create database geography;
use geography;
source ./sql/framework/core/geography/install/mysql/install_all_geography_mysql.sql;
create database proxy;
use proxy;
source ./sql/framework/core/proxy/install/mysql/install_all_proxy_mysql.sql;
create database warning;
use warning;
source ./sql/framework/core/warning/install/mysql/install_all_warning_mysql.sql;
Create the MySQL users
GRANT ALL PRIVILEGES ON *.* TO diry_user@localhost IDENTIFIED BY 'diry_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO diry_user@localhost.localdomain IDENTIFIED BY 'diry_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO session_user@localhost IDENTIFIED BY 'session_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO session_user@localhost.localdomain IDENTIFIED BY 'session_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO orgn_user@localhost IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO orgn_user@localhost.localdomain IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO geog_user@localhost IDENTIFIED BY 'geog_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO geog_user@localhost.localdomain IDENTIFIED BY 'geog_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO proxy_user@localhost IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO proxy_user@localhost.localdomain IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO warning_user@localhost IDENTIFIED BY 'warning_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO warning_user@localhost.localdomain IDENTIFIED BY 'warning_password' WITH GRANT OPTION;
Note: Linux users need to execute these statements twice. First using "localhost" and "localhost.localdomain", then using the host and domain names stored in /etc/hosts. Example using "mylocahost" and "mylocalhost.mylocaldomain":
GRANT ALL PRIVILEGES ON *.* TO diry_user@mylocalhost IDENTIFIED BY 'diry_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO diry_user@mylocalhost.mylocaldomain IDENTIFIED BY 'diry_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO session_user@mylocalhost IDENTIFIED BY 'session_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO session_user@mylocalhost.mylocaldomain IDENTIFIED BY 'session_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO orgn_user@mylocalhost IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO orgn_user@mylocalhost.mylocaldomain IDENTIFIED BY 'orgn_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO geog_user@mylocalhost IDENTIFIED BY 'geog_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO geog_user@mylocalhost.mylocaldomain IDENTIFIED BY 'geog_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO proxy_user@mylocalhost IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO proxy_user@mylocalhost.mylocaldomain IDENTIFIED BY 'proxy_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO warning_user@mylocalhost IDENTIFIED BY 'warning_password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO warning_user@mylocalhost.mylocaldomain IDENTIFIED BY 'warning_password' WITH GRANT OPTION;
exit;
Customize Active Directory settings
You need to use a service account to connect to Active Directory. This service account must have domain admin rights to be able to create and edit accounts, contacts, groups, including resetting passwords. If you are just evaluating Corendal Directory, you can use your own account and password for this evaluation, but you will get errors when performing updates.
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\datasources\ldapsource\activedirectory\ldapsource.xml
<property name="java.naming.provider.url">ldap://mydomaincontroller.mydomain.mycompany.com:389</property>
<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.security.authentication">simple</property>
<property name="java.naming.security.principal">myserviceaccount@mydomain.mycompany.com</property>
<property name="java.naming.security.credentials">myservicepassword</property>
<property name="com.sun.jndi.ldap.connect.pool">true</property>
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\datasources\ldapsource\activedirectory\nodes\Account.xml
<dn>dc=mydomain,dc=mycompany,dc=com</dn>
<preferred-domain>mydomain.mycompany.com</preferred-domain>
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\datasources\ldapsource\activedirectory\nodes\Contact.xml
<dn>dc=mydomain,dc=mycompany,dc=com</dn>
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\datasources\ldapsource\activedirectory\nodes\Group.xml
<dn>dc=mydomain,dc=mycompany,dc=com</dn>
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\datasources\ldapsource\globalcatalog\ldapsource.xml
<property name="java.naming.provider.url">ldap://mydomaincontroller.mydomain.mycompany.com:3268</property>
<property name="java.naming.factory.initial">com.sun.jndi.ldap.LdapCtxFactory</property>
<property name="java.naming.security.authentication">simple</property>
<property name="java.naming.security.principal">myserviceaccount@mydomain.mycompany.com</property>
<property name="java.naming.security.credentials">myservicepassword</property>
<property name="com.sun.jndi.ldap.connect.pool">true</property>
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\datasources\ldapsource\globalcatalog\nodes\Account.xml
<dn>dc=mycompany,dc=com</dn>
<preferred-domain>mydomain.mycompany.com</preferred-domain>
In doubt, ask your Windows administrator for these Active Directory settings.
Create an Active Directory keystore
This part is required if you need to set passwords through Corendal Directory, including while creating users. This is NOT required by the other features of the application, such as account, contact and group lookups, or account, contact and group updates.
Obtain a root certificate trusted by the domain controller for the purpose of SSL connections (port 636) with that domain controller.
In many setups, this certificate can be obtained through Internet Explorer, as described in this article:
http://alextch.members.winisp.net/ResetADPasswordFromJava/SetADPasswordFromJava.htm
The following command in Windows will create a file "activedirectory.jks" based upon your exported certificate file "myencryptionca.cer":
keytool -import -alias activedirectory -keystore activedirectory.jks -file C:\myencryptionca.cer
Move the file created in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\keystores\
The keystore file must be named activedirectory.jks in that folder.
Customize the applications.xml file
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\setups
<property name="framework.core.webapp.protocol">
http
</property>
<property name="framework.core.webapp.host">
localhost
</property>
<property name="framework.core.webapp.port">8080</property>
<property name="framework.core.webapp.folder">
/directory
</property>
<property name="framework.core.uploads.maxsize">
50
</property>
<property name="framework.core.smtp.host">
mailserverip.mycompany.com
</property>
<property name="framework.core.emails.domain">
mycompany.com
</property>
<property name="framework.core.cookies.domain">
mycompany.com
</property>
If you install Corendal Directory application to a remote server (as opposed to the machine that you will be using as a client), you do need to change the "framework.core.webapp.host" property to that server's name. Corendal Directory will always attempt to redirect your client to that server. If you want to disable that feature, remove the "framework.core.webapp.host" property line.
If you are not using Tomcat, you don't know the port number and you just want to evaluate this application, just remove the "framework.core.webapp.port" property line. The application will detect automatically the port number. However, this is a required property for production setups.
Configure your Group Policies
Accounts in Active Directory need to follow Group Policies that control the complexity and expiration of passwords as well as account locking mechanisms. These settings are not detected automatically by Corendal Directory. For an accurate reporting of which passwords are expired, which accounts are locked out, and to control the complexity of passwords set through the application, setup the following properties in the applications.xml file:
<property
name="framework.core.activedirectoryaccountpassword.minagebeforechange">
0
</property>
<property
name="framework.core.activedirectoryaccountpasswordcomplexity.enabled">
N
</property>
<property
name="framework.core.activedirectoryaccountpasswordcomplexityforadmins.enabled">
N
</property>
<property
name="framework.core.activedirectoryaccountpassword.minimumlength">
6
</property>
<property
name="framework.core.activedirectoryaccountpasswordforadmins.minimumlength">
6
</property>
<property
name="framework.core.activedirectoryaccountpassword.maxagebeforeexpiration">
90
</property>
<property
name="framework.core.activedirectoryaccountlockout.duration">
0
</property>
framework.core.activedirectoryaccountpassword.minagebeforechange indicates the minimum number of days end-users must wait between two password changes.
framework.core.activedirectoryaccountpasswordcomplexity.enabled indicates whether end-users must enter passwords that contain characters from at least three of the following four categories:
- English uppercase characters (A - Z)
- English lowercase characters (a - z)
- Base 10 digits (0 - 9)
- Non-alphanumeric (for example: !, $, #, or %)
framework.core.activedirectoryaccountpasswordcomplexityforadmins.enabled indicates whether these password complexity rules also apply to passwords set by administrators of Corendal Directory.
framework.core.activedirectoryaccountpassword.minimumlength indicates the minimum number of characters passwords must contain when they are set by end-users.
framework.core.activedirectoryaccountpasswordforadmins.minimumlength indicates the minimum number of characters passwords must contain when they are set by administrators of Corendal Directory.
framework.core.activedirectoryaccountpassword.maxagebeforeexpiration indicates the maximum number of days a password can be used without being changed.
framework.core.activedirectoryaccountlockout.duration indicates the number of minutes an account is locked after too many incorrect login attempts.
Your Active Directory administrator should know which values to enter based upon these descriptions. If you are just evaluating this application and don't know your group policies, you can skip this step.
Customize the jcifs.properties file
This properties file is used by the NTLM authentication. The domain, username and password are required for pre-authentication / SMB sign-in against Windows Server 2003.
in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\properties
jcifs.http.domainController=mydomaincontroller.mycompany.com
jcifs.smb.client.soTimeout=600000
jcifs.netbios.cachePolicy=1200
jcifs.smb.client.domain=mydomain.mycompany.com
jcifs.smb.client.username=myserviceaccount
jcifs.smb.client.password=myservicepassword
jcifs.util.loglevel=1
Customize the C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\setups\applications.xml file to specify which IP ranges should have NTLM authentication.
<ntlm-ip-address-ranges>
<ip-address-range>
<from>127.0.0.1</from>
<to>127.0.0.1</to>
</ip-address-range>
<ip-address-range>
<from>192.168.0.1</from>
<to>192.168.0.255</to>
</ip-address-range>
<ip-address-range>
<from>192.168.56.1</from>
<to>192.168.56.255</to>
</ip-address-range>
</ntlm-ip-address-ranges>
To disable NTLM all together, leave only one range, such as:
<ntlm-ip-address-ranges>
<ip-address-range>
<from>128.0.0.1</from>
<to>128.0.0.1</to>
</ip-address-range>
</ntlm-ip-address-ranges>
If you want to use NTLM over HTTPS, there are some tricky setups for your HTTPS proxy because of Internet Explorer bugs. Write me an email for more info: Thierry Danard (tdanard@yahoo.com)
Customize the preprocessor.properties file
This file will be used to perform search/replace in many of the configuration files at startup. Your configuration files will not be changed, this application creates and uses temporary files on startup.
HelpDeskName=My Company's Help Desk
HelpDeskEmailAddress=helpdesk@mycompany.com
HelpDeskPhoneNumber=+1 555 123-4567
HelpDeskApplicationName=Directory Web Application
PublicApplicationName=Directory
CompanyName=My Company
ApplicationReleaseDate=April 19th, 2006
UserDocumentationLocation=My Company's User Documentation Home
UserTrainingContact=My Company's User Training Contact
LegalTermsPageURL=My Company's Legal Terms URL
Install the web application
Copy the C:\Documents and Settings\Thierry\My Documents\directory folder to your Tomcat webapps folder (example:C:\Program Files\Apache Software Foundation\Tomcat 5.0\webapps)
Note: Recent versions of Tomcat have a more strict parsing of the webapps/directory/WEB-INF/web.xml file. If duplicate entries are present, Tomcat will fail to load the application.
Prerequirements
In the web.xml file, there are duplicate lines:
<servlet-mapping>
<servlet-name>DynamicDatabaseHTTPServlet</servlet-name>
<url-pattern>/materialrequest</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>DynamicDatabaseHTTPServlet</servlet-name>
<url-pattern>/materialrequest/*</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>DynamicDatabaseHTTPServlet</servlet-name>
<url-pattern>/materialrequest</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>DynamicDatabaseHTTPServlet</servlet-name>
<url-pattern>/materialrequest/*</url-pattern>
</servlet-mapping>
should be
<servlet-mapping>
<servlet-name>DynamicDatabaseHTTPServlet</servlet-name>
<url-pattern>/materialrequest</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>DynamicDatabaseHTTPServlet</servlet-name>
<url-pattern>/materialrequest/*</url-pattern>
</servlet-mapping>
Start Tomcat.
Use the application
Depending on your settings, the address of the application should be http://localhost:8080/directory/home/
You will notice that the first page is long to load at first. Each time a page is loaded for the first time, a cache is built.
User accounts
Two users are built-in: demoadmin (password is admin), and demoguest (password is guest). You can also use your Active Directory account and password.
The application is designed to work with Active Directory. If you want to create your own built-in users, look at the C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\installmefirst\sql\framework\core\shared\populate\populate_account_table_core.sql for examples. To generate encrypted passwords for these users, use the "main" method of the com.corendal.netapps.framework.core.utils.OneWayEncryptUtil class
Administration
To gain administrator access, just execute a SQL statement. Example if "tdanard" is your Active Directory login :
use directory;
insert into account_role_xref values ('admin1', 'tdanard', 'CORE-ROLE-1', null, null, 'Y');
commit;
To delete the default users:
use directory;
delete from account where id='demoadmin';
delete from account where id='demoguest';
commit;
Once the application is started, you can also use the "System Accounts and Groups Monitor" screens to grant various roles, including Administrator.
MySQL
MySQL has a default limitation of 1 MB for files. You will get a FileTooBigException when trying to upload large files. See www.mysql.com to learn how to change your my.cnf settings. By default, MySQL only indexes words that are at least 4 character-long. This setting can be changed as well.
Install the crons (optional for evaluation)
The "everyminute" cron is the cron/batch that sends all emails generated by the application. Emails are never sent directly by Corendal Directory, they are always queued and then sent by this cron if you enabled it. You can check the list of queued emails prior to executing this cron from the "Admin > Emails Monitor" screen.
Other cron file examples are provided (everyfiveminutesdirectory and dailydirectory), they are not officially supported. Use them are reference if you want to implement advanced notifications, such reminding users to change their password prior to expiration.
All cron files for Linux are in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\installmelast\crons.
In Linux, edit your crontab of your "tomcat" user to execute the "everyminutedirectory.cron" cron at system startup.
All bat files for Windows are in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\installmelast\bats.
In Windows, edit your scheduled tasks to execute the "everyminutedirectory.bat" at system startup.
Customization of User Interface
It is fairly easy to adapt the site to your corporate standards.
All template files are in C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\templates. The following files are usually customized to edit the header and the footer of each page:
C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\templates\template-core-page-header.vm
C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\templates\template-core-page-footer.vm
Other files you might want to edit to customize the look and feel of the application are:
C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\setups\styles.xml
C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\setups\colors.xml
C:\Documents and Settings\Thierry\My Documents\directory\WEB-INF\configs\directorydevconfig\setups\icons.xml
C:\Documents and Settings\Thierry\My Documents\directory\css\screen.css
Oracle
Corendal Directory has been tested successfully with Oracle 10g .
The Oracle installation is very similar to the MySQL installation, except for the hibernate.cfg.xml files that need to be changed.
Follow this template for hibernate.cfg.xml files.
<hibernate-configuration>
<session-factory name="java:hibernate/SessionFactory">
<property name="hibernate.connection.url">
jdbc:oracle:thin:@(DESCRIPTION =
(FAILOVER = ON)
(ADDRESS_LIST =
(ADDRESS=(PROTOCOL=TCP)(HOST=myhost1.mydomain)(PORT=1521))
(ADDRESS=(PROTOCOL=TCP)(HOST=myhost2.mydomain)(PORT=1521))
)
(CONNECT_DATA =
(SERVICE_NAME = DIRECTORY)
(FAILOVER_MODE =
(TYPE = SESSION)
(METHOD = BASIC)
(RETRIES = 180)
(DELAY = 5)
)
)
)
</property>
<property name="hibernate.connection.driver_class">
oracle.jdbc.driver.OracleDriver
</property>
<property name="hibernate.connection.username">
diry_user
</property>
<property name="hibernate.default_schema">
diry_user
</property>
<property name="hibernate.connection.password">
diry_password
</property>
<property name="hibernate.connection.SetBigStringTryClob">
true
</property>
<property name="hibernate.jdbc.batch_size">0</property>
<property name="hibernate.jdbc.use_streams_for_binary">
true
</property>
<property name="hibernate.show_sql">false</property>
<property name="hibernate.statement_cache">0</property>
<property name="hibernate.transaction.factory_class">
org.hibernate.transaction.JDBCTransactionFactory
</property>
<property name="c3p0.acquire_increment">1</property>
<property name="c3p0.idle_test_period">100</property>
<property name="c3p0.max_size">100</property>
<property name="c3p0.max_statements">0</property>
<property name="c3p0.min_size">1</property>
<property name="c3p0.timeout">100</property>
</session-factory>
</hibernate-configuration>
In this template, an Oracle cluster is used with two nodes: myhost1.mydomain and myhost2.mydomain
The SQL scripts to create the tables and sequences in Oracle are included in this distribution. Instead of executing source ./sql/main-directory/shared/install/mysql/install_all_shared_mysql.sql, execute @./sql/main-directory/shared/install/oracle/install_all_shared_oracle.sql.
Gotchas
The Velocity templating engine creates a velocity.log file in your tomcat directory at startup. Make sure that you are starting Tomcat under a user that has write-access to that directory.
It's safer to use the Sun JDK rather than the Linux vendor-supplied (.rpm) version.
If Tomcat doesn't start and you used a .war file to deploy this web application, make sure that Tomcat deployed all files.
Page updated
Google Sites
Report abuse