DELETE Tolven-core-117-install

From DOC

INSV2REL_20110412

Note: Tolven V2 and this Installation Guide are Beta. This means that this guide, along with the procedures in it, are in a state of continual development and may change without notice from Tolven. We recommend that you place a watch on the WIKI so that you are informed when changes are made.

© 2011 Tolven, Inc. All rights reserved. Tolven and Tolven Platform are trademarks of Tolven, Inc.

All other trademarks are the property of their respective owners.

This guide presents an enterprise installation procedure that includes multiple steps, most of which can be customized for a specific environment. We strongly recommend that you follow the default/recommended installation steps the first time you install the Tolven Platform (Tolven). After your initial default installation, you can then consider making changes.

Click Printable version in the navigation pane to the left to print a copy of this guide before you start.

CR/LFs in Code Samples
Carriage Return/Line Feeds were added to some code samples for the sake of formatting when you print this guide:

If you are copying and pasting code from this guide to the command line, be aware that those CR/LFs may carry over.

Related Documentation
If you intend to use the Tolven Platform Web Services API, after following the instructions in this Installation Guide, see the Configuring Tolven V2 Web Services Tech Note for instructions.

Installation Checklist
Use this installation checklist to help keep track of the progress of your installation.

Installation Step	Installation Sub-Step	Completed?	Notes
Step 1 - Install Prerequisite Software	1.1 Install & Verify Java (Prerequisite)
	1.1.1 Install Java
	1.1.2 Verify Java Installation
	1.1.3 Verify JAVA_HOME Setup
	1.2 Install Database (Prerequisite)
	1.2.1 Install PostgreSQL
	1.2.1.1 Install PostgreSQL on Windows
	1.2.1.2 Install PostgreSQL on Linux
	1.2.2 Install Oracle
Step 2 - Download Software	2.1 Download Tolven
	2.2 Download Tolven Configuration Files
	2.3 Download JDBC Driver
	2.4 Download OpenDS Software
	2.5 Download OpenAM Software
	2.6 Download Policy Agent
	2.7 Download Glassfish
	2.8 Download Apache Tomcat
Step 3 - Install Tolven	3.1 Unzip the Installation File
	3.2 Create Permanent tolven-config Directory
	3.3 Verify TPF Version
Step 4 - Configure Your Database	4.1 Configure PostgreSQL
	4.1.1 Modify pg_hba.conf
	4.1.2 Modify postgresql.conf
	4.1.2.1 Modify postgresql.conf to Enable SSL
	4.1.2.2 Modify postgresql.conf Maximum Transactions
	4.2 Configure Oracle
Step 5 - Set Up Your Security Environment	5.1 Set Up Server Name
	5.2 Set Up SSL Keystore
	5.3 Set Up SSL Truststore
	5.4 Set Up MQKeystore
Step 6 - Assemble Tolven	6.1 Edit Global Properties
	6.2 Initialize the Runtime Repository
	6.3 Run the Check Integrity Command
	6.4 Run Phase 1 Configuration
	6.5 Run Phase 2 Configuration
	6.6 Create Schemas
	6.7 Assemble Tolven OpenAM Library Jar
	6.8 Assemble MQKeyStore
	6.9 Assemble Tolven EAR File
Step 7 - Install & Configure Identity Software	7.1 Install, Start & Stop OpenDS
	7.1.1 Check Port Assignments & Security Setup
	7.1.2 Install OpenDS
	7.1.3 Start OpenDS
	7.1.3.1 Start OpenDS From Command Line
	7.1.3.2 Start (& Stop) OpenDS Using the Control Panel
	7.1.4 Stop OpenDS
	7.2 Configure OpenDS
	7.2.1 Set Up Tolven-Specific Configuration
	7.2.2 Configure OpenDS
	7.2.3 Reconfigure Control Panel
	7.2.4 Running OpenDS From the Control Panel
	7.2.5 Installing OpenDS as a Windows Service
	7.3 Install & Start Tomcat
	7.3.1 Check Port Setup
	7.3.2 Install Tomcat
	7.3.3 Start Tomcat
	7.3.4 Test Tomcat
	7.3.5 Shut Down Tomcat
	7.4 Configure Tomcat
	7.4.1 Remove Sample WAR Files
	7.4.2 Enable HTTPS Access
	7.5 Install OpenAM
	7.5.1 Install OpenAM WAR File
	7.5.2 Rename war File
	7.5.3 Start Tomcat
	7.5.4 Test OpenAM
	7.6 Configure OpenAM
	7.6.1 Installing tolven-openam-auth.jar in OpenAM
	7.6.2 Unzip Tolven Configuration Files
	7.6.3 Add Custom Tomcat Startup
	7.6.4 Add Tolven Configuration Files
	7.6.5 Prepare to Configure OpenAM
	7.6.6 Setup OpenAM Configurator Tool
	7.6.7 Setup the OpenAM Administration Tool
	7.6.8 Apply the Tolven Configuration Using ssoadmin Tool
Step 8 - Set Up Your Application Server	8.1 Install Application Server Containers
	8.1.1 Install Tolven JBoss V6
	8.1.2 Install Glassfish
	8.1.2.1 Install Kit or Unzip
	8.1.2.2 Rename the Default Domain
	8.1.2.3 Setup a Persistent Master Password
	8.1.2.4 Install Credentials
	8.1.2.5 Install JDBC Driver
	8.1.2.6 Add Tolven Customization
	8.1.3 Configure Glassfish
	8.1.3.1 Start the Application Server
	8.1.3.2 Configure General Settings
	8.1.3.3 Configure JDBC Settings
	8.1.3.4 Configure JMS Settings
	8.1.3.5 Stop the Application Server
	8.1.4 Install Policy Agent
	8.1.4.1 Unzip Software
	8.1.4.2 Secure Policy Agent
	8.1.5 Configure Policy Agent
	8.1.6 Update Agent In OpenAM
	8.1.7 Remove agentadmin User From OpenAM
	8.1.8 Start Glassfish
	8.1.9 Deploy Policy Agent
	8.1.10 Install Tolven Glassfish
	8.1.10.1 Stop Glassfish
	8.1.10.2 Fix Welcome Page
	8.1.10.3 Install Tolven-Specific Components into Glassfish
	8.1.10.4 Verify JMS Configuration
Step 9 - Configure Tolven	9.1 Deploy Tolven Glassfish Libraries
	9.2 Configure Tolven Glassfish
	9.2.1 Start Glassfish
	9.2.2 Create Resource Adapter
	9.2.3 Deploy the mqKeyStore.rar
	9.2.4 Change imqusermgr Password
	9.2.5 Create JMS Resource
	9.2.6 Deploy mqKeyStore.rar
	9.3 Deploy Tolven EAR File
	9.4 Update Database Indexes
	9.5 Update Server Properties
	9.5.1 (Optional) Disable Use of User Security Certificates
	9.6 Create a Tolven User
	9.6.1 Add User
	9.6.2 Add Role
	9.7 Add Application Metadata to plugins.xml
	9.8 Add Vocabularies to plugins.xml
	9.9 Run repositoryInit
	9.10 Run Phase 3 Configuration
	9.11 Activate Vocabulary Plugins
Step 10 - Next Steps

Step 1 - Install Prerequisite Software

A Tolven installation requires that a number of prerequisite software products be installed. Later, during configuration, you will be directed how to configure these prerequisite components to work with Tolven.

After the prerequisite software packages are installed, they do not need to be changed when a new version of Tolven is installed unless specifically directed to do so in the Tolven release notes.

1.1 Install & Verify Java (Prerequisite)

1.1.1 Install Java

Tolven requires Java 1.6 SE (desktop) to be installed. Java EE components will then be installed later, as part of the application server install. Tolven generally requires the latest released version.

Windows:

Install the Java JDK if it is not already installed. Tolven requires JDK version 1.6.0 or newer. You can download the Java JDK here:

JDK download site

You can install it anywhere you want, but we recommend something like the following (depending on the version):

c:\jdk1.6.0

This kit will also install the corresponding Java Runtime Environment (JRE). This is the JRE that Tolven will use. I usually accept the default location for the JRE. Tolven does not use any applets or Java-based browser plugins.

After installing Java, the JAVA_HOME environment variable should point to this (new) JDK. You can verify this on Windows as follows:

Start > Control Panel > System > Advanced > Environment Variables

Linux:

Install the Java JDK if it is not already installed. Tolven requires JDK version 1.6.0 or newer.

JDK download site

You can install it anywhere you want, but we recommend something like the following (depending on the JDK version and your Linux flavor):

/usr/java/jdk1.6.0_10

This kit will also install the corresponding Java Runtime Environment (JRE). This is the JRE that Tolven will use. Tolven does not use any applets or Java-based browser plugins.

1.1.2 Verify Java Installation

Verify that Java is set up correctly. Execute the following from the command line:

Windows:

java -version

Linux:

which java

Verify that the version number is 1.6 or greater.

1.1.3 Verify JAVA_HOME Setup

After installing Java, the JAVA_HOME environment variable should point to this (new) JDK. You can verify this as follows:

Windows:

set JAVA_HOME

Linux:

echo $JAVA_HOME

Verify that this environment variable refers to a Java JDK (not JRE) installation.

1.2 Install Database (Prerequisite)

Install one of the following database products if not already installed:

1.2.1 Install PostgreSQL

• You can use pgAdminIII (also available from the PostgreSQL site) to test communication with the database.

• You must download an appropriate JDBC driver and point to this driver in the plugins.xml file. This will be done later in the installation process.

1.2.1.1 Install PostgreSQL on Windows

The PostgreSQL documentation describes building PostgreSQL from source, but that is not needed for Tolven. The binary kit is adequate.

1. Unzip postgresql-8.2.3-1.zip (or the current version of the Windows version of PostgreSQL) into a temporary location such as:

c:\download\postgres

The directory should look something like this:

2. Double click:

postgresql-8.2.msi

3. For this example, in the installation options step, no options will be changed from the default, but we will change the installation directory to the following using the Browse button:

c:\postgreSQL\8.2\

4. On the Service configuration screen, accept the account name and enter "postgres" as the Postgres password. You will need to provide this password to Glassfish later. Also specify that Postgres be installed as a service.

The Initialize database cluster will create the initial database, which Tolven will use.

5. Change the encoding to UTF-8. Specify your Locale.

6. Provide a Postgres password for the default database super user postgres. This means that you will have a database named postgres and a super user named postgres. Use this default password to avoid additional steps in the configuration process.

7. Accept the default procedural language settings. Tolven does not need anything special in this area. Tolven has no dependencies on any PostgreSQL-specific features.

8. For the contrib options, accept the default, which includes the very useful administrative tools found in the Adminpack.

If the installation completes successfully, you should see something similar to the following:

At this point your database should be up and running. You will need to shut it down to configure security.

9. Run the PGadminIII tool which should look like this:

This tool will allow you to start and stop the database server when the time comes and to look at the database contents. To connect to the database, provide the super user and password (postgres for the username and password).

The Postgres installation is complete. You will add some configuration later in this installation process, namely digital certificates for secure communication via SSL.

10. Now that you've had a look around the empty database, stop the database server:

11. You can now delete the temporary directory you created. For example:

c:\download\postgres 

1.2.1.2 Install PostgreSQL on Linux

The PostgreSQL documentation describes building PostgreSQL from source but that is not needed for Tolven. The binary kit is adequate. If PostgreSQL is not installed on your system, please following package installation guidelines for your flavor of Linux. One important note, is that Tolven assumes that you have installed PostgreSQL in the directory /usr/local/pgsql, although /var/lib/pgsql is also a well-known location. For a new installation it will be simpler to use /usr/local/pgsql. The various options are presented below. Note that no advice is given where the pgsql's data directory already exists, because it is assumed that it contains a live database.

If the original install was in /var/lib/pgsql, then step 1.2.1.2.1 With No Existing Postgres Database below can be carried out first, followed by step 1.2.1.2.2 With An Existing Postgres Database. Otherwise, only step 1.2.1.2.2 With An Existing Postgres Database is required.

1.2.1.2.1 With No Existing Postgres Database

Where there is no existing postgres database, moving PostgreSQL installed in /var/lib/pgsql to /usr/local/pgsql This assumes that PostgreSQL is already installed in /var/lib/pgsql, but there is no postgres database as yet.

The postgres home directory is likely to be /var/lib/pgsql. It can remain here, but if it's empty you can consider moving postgres home to /usr/local/pgsql. It is not absolutely necessary to do so, but just a convenience. First create the home directory and give it postgres permissions:

mkdir /usr/local/pgsql
chown postgres:postgres /usr/local/pgsql

Then execute the following to move the postgres home directory (assumed to be /var/lib/pgsql) to /usr/local/pgsql (double check that it doesn't contain more data in it subdirectories, than you desire to to move):

usermod -d /usr/local/pgsql postgres

1.2.1.2.2 With An Existing Postgres Database

Where there is no existing postgres database and PostgreSQL is installed in /usr/local/pgsql. The first two commands are the same as those executed in step 1.2.1.2.1 With No Existing Postgres Database, if that step was necessary.

mkdir /usr/local/pgsql/data
chown postgres:postgres /usr/local/pgsql/data

Now log in as posgres:

su - postgres

Execute the env command to see if it contains PGDATA. If not, then you can default it for the next time you log in, by creating/editing the .bash_profile in the postgres home directory, which is where you should be after executing the command above. It is not critical if the home directory is elsewhere. Add the following lines to .bash_profile for postgres:

PGDATA = /usr/local/pgsql/data
export PGDATA

If you have just edited the .bash_profile, then exit and re-execute 'su - postgres' again to pick up the changes. Check with the env command.

As the postgres user, execute the following to create the database:

initdb -E UTF8 -D /usr/local/pgsql/data

The /usr/local/pgsql/data directory should now have contents, and you should be able to start the database:

As postgres:

pg_ctl start

or, if you exit back to root, then:

su -c 'pg_ctl -D /usr/local/pgsql/data start' postgres
<pre>

Check that PostgreSQL is running by using the 'ps' command, or:

<pre>
netstat -a | grep postgres
<pre>

or

<pre>
netstat -a | grep 5432

Following the guidelines in PostgreSQL and your Linux documentation to set the server as a service.

1.2.2 Install Oracle

The database server does not need to be on the same machine as the Tolven Application Server. Installing Oracle depends on the operating system. Please consult both the Oracle documentation, and also the documentation for your operating system.

While installing Oracle, the following information will be required during the configuration of Tolven:

• Server name on which Oracle is being installed (default: localhost)
• Port number (default: 1521)
• Database name or SID (default: ORCL)

A number of Oracle tools including Oracle SQL Developer, can be used to test communication with the database once it is installed.

Set Up a Tolven User

You will need to add one user named tolven which will need permission to create, populate and query tables, views, indexes, and perhaps sequences (core Tolven does not use sequences).

JDBC Driver

You must provide an appropriate JDBC driver and point to this driver in the plugins.xml file (done later).

Oracle usually provides a driver in the installation. However, this driver does not work for Glassfish V3.0.1, and so you will need to download a newer driver from Oracle Download Site

Step 2 - Download Software

All of the downloading is done first and does not need to be repeated for subsequent installs. We recommend that you download all of the components to a convenient location to be accessed during various installation steps that follow.

2.1 Download Tolven

Download tolven-v2.x.x.zip from the Tolven download site:

http://tolven.org/download/v2/tpf/tolven-V2.0.25.zip

2.2 Download Tolven Configuration Files

Tolven uses several components which are downloaded from their respective download sites. In order to speed up the configuration of these products, Tolven provides a number of files that are used during this process. Very often, these files are specific to a particular product and often to a particular version of that product.

In many cases, you will notice that the directory structure of these configuration files follow the directory structure of the product being installed.

Download each of the following zip files:

http://tolven.org/download/v2/catalog/plugins/org.tolven.openam.config-2.0.15.zip

http://tolven.org/download/v2/catalog/plugins/org.tolven.opends.config-2.0.5.zip

Notice that org.tolven.opends.config-2.0.5.zip is not the OpenDS software. It contains Tolven configuration files that will be added to the OpenDS installation.

For Oracle, download and unzip the following zip file:

http://tolven.org/download/v2/catalog/plugins/org.tolven.glassfish.oracle.config-2.0.1.zip

For PostgreSQL, download and unzip the following zip file:

http://tolven.org/download/v2/catalog/plugins/org.tolven.glassfish.postgresql.config-2.0.1.zip

2.3 Download JDBC Driver

In general, we recommend that you download and use the latest version of the JDBC driver, regardless of the version of the underlying database.

For Oracle, download the JDBC driver here:

http://www.oracle.com/technology/software/tech/oci/instantclient/index.html

Also see the Oracle Glassfish compatibility matrix:

http://www.oracle.com/technology/software/products/middleware/files/oracle_glassfish_3_0_1_certification_matrix.xls

For PostgreSQL, download the JDBC driver here:

http://jdbc.postgresql.org/download.html

2.4 Download OpenDS Software

Download the OpenDS 2.3.0 Directory Service software from the OpenDS download site:

https://opends.dev.java.net/public/downloads_index.html

Note: Download OpenDS 2.3.0. There is a bug in OpenDS 2.2.0 related to SSHA password verification.

2.5 Download OpenAM Software

Two components are downloaded, the Single Sign On server itself, and a corresponding Policy Agent that will eventually be deployed into various containers. The policy agent is, in effect, the enforcer of the security policies that are defined in the SSO server and stored in an OpenDS (LDAP) datastore.

Download openam_snapshot_951RC2.zip from ForgeRock:

http://www.forgerock.com/downloads.html

2.6 Download Policy Agent

Download the stable version of the J2EE Policy Agent called appserver_v10_agent_3 that corresponds to openam_snapshot_951RC2.zip from the same ForgeRock site:

http://www.forgerock.com/downloads.html

2.7 Download GlassFish

Download Glassfish 3.0.1 from:

GlassFish Open Source download site

Select your platform and your language. Agree to the license agreement and then click Continue.

Note: At this point, you will not need to be connected to the Internet again until you get to the Configure Tolven step.

2.8 Download Apache Tomcat

Download the Apache Tomcat 7.0.5 zip file from:

Apache Tomcat 7 Downloads

Step 3 - Install Tolven

At this point, you will be installing the Tolven Plugin Framework and the initial version of the tolven-config directory if this is the first time installing on this system.

You will have the choice of using the trunk (live snapshot plugin catalog or the trunk (live) plugin catalog.

In order to install Tolven, you must already have followed the previous steps in Installation Guide V2. In particular, the download steps should have been performed.

3.1 Unzip the Installation File

The Tolven installer is shipped as a zip file and is platform-independent. It runs on both 32- and 64-bit hardware and operating systems. The unzipped directory is called tolven-V2 by default and will be referred to as the Tolven software home directory.

Windows:

Unzip the downloaded tolven-v2.x.x.zip file. For example, downloading to c: in Windows, the Tolven software home directory becomes:

c:\tolven-v2.x.x

Linux:

cd /usr/local
unzip tolven-v2.x.x.zip

This will create the Tolven software home directory called:

• /usr/local/tolven-v2.x.x

3.2 Create Permanent tolven-config Directory

This step installs the initial Tolven software which is a bootstrap for the many plugins that will be added during configuration. This step also creates a tolven-config directory that contains data specific to your configuration and is not overridden from release to release.

Windows

cd tolven-V2\bin
install

Linux

cd tolven-V2/bin
./install.sh

The install command installs for a PostgreSQL configuration by default. For PostgreSQL, the install command is equivalent to the long form:

Windows

cd tolven-V2\bin
install -pluginsxml glassfish3-legacypostgresql-plugins.xml

Linux

cd tolven-V2/bin
./install.sh -pluginsxml glassfish3-legacypostgresql-plugins.xml

For Oracle, the install command is equivalent to the long form:

cd tolven-V2\bin install -pluginsxml glassfish3-oracle-plugins.xml

cd tolven-V2/bin ./install.sh -pluginsxml glassfish3-oracle-plugins.xml

Both glassfish3-legacypostgresql-plugins.xml and glassfish3-oracle-plugins.xml are located in the kit directory: template-pluginsxml. Using the relative path above in the install command causes the kit to look in this directory for a matching template. An absolute path can also be used to determine a template elsewhere.

You will be prompted for the following (default values are suggested by the installer):

• The tolven-config directory (by default c:\tolven-config or /usr/local/tolven-config). If you have a previous tolven-config directory, then you would normally reuse it in order to pick up previous installation information.

After it is installed, the configuration directory (tolven-config) will not be overwritten by subsequent installations and upgrades. However, over time, many different Tolven installation directories (tolvenVersion) will be created. You may delete obsolete installation directories without affecting the Tolven configuration directory. We recommend that you never make changes in the installation directory.

Plugin Properties

The plugins.xml file contains a list of plug-ins, some of which contain a <root> tag. This file

is important because it determines which plug-ins will be downloaded from the [[Plugin Library

Repository | Library Repositories]], and allows you to configure plug-ins. Each plug-in named in

this XML file may have the optional one <root/> tag. The presence of a <root> tag generally means

that the plug-in is required and guarantees that the plug-in and all its dependencies will be

downloaded. Other plug-ins may be downloaded if there is a direct or indirect dependency.

A given plug-in can have any number of <property> tags specific to that plugin. The <property>

tags can also exist outside of any particular plug-in, making them global <nowwiki><property>

tags</nowiki>.

There are many other properties in plugins.xml that you may want to change. Whenever you change

these properties, it is necessary to run configPhase1 for them to take effect. But during this

initial configuration, do not execute this command until instructed to do so later in this

install.

The default plugins.xml file is located in the tolven-config directory. It is identical to:

<install-dir>/template-pluginsxml/glassfish3-legacypostgresql-ldap-plugins.xml

For Oracle, the file is:

<install-dir>/template-pluginsxml/glassfish3-oracle-ldap-plugins.xml

One of these is automatically copied during the install command, as described in section 3.2

Create Permanent tolven-config Directory.

3.3 Verify TPF Version

Verify the version of TPF.

Windows:

cd <install-dir>\bin
tpf -version

Linux:

cd <install-dir>/bin
./tpf.sh -version

Installing an Off-Line Catalog

If you will be using the recommended Tolven install process which uses the live version of plugins, then you can ignore this section.

1. Unzip the catalog to a convenient folder. For example, snapshot12 could be unzipped to tolven-config/.
2. Edit tolven-config/plugins.xml. Change the property that specifies the locations of the repository libraries.

<property name="repositoryLibrary">
  <property name="v0">
    <property name="trunkMetadata" value="http://tolven.org/download/plugins.xml" />
    <property name="snapshotMetadata" value="file:///#{globalProperty['installation.dir']}/repositorySnapshot/v0/plugins.xml" />
    <property name="useSnapshot" value="false" />
    <property name="overwriteSnapshot" value="false" />
  </property>
  <property name="v2">
    <property name="trunkMetadata" value="http://tolven.org/download/v2/catalog/plugins.xml" />
    <property name="snapshotMetadata" value="file:///#{globalProperty['installation.dir']}/repositorySnapshot/v2/plugins.xml" />
    <property name="useSnapshot" value="false" />
    <property name="overwriteSnapshot" value="false" />
  </property>
  <property name="repositoryLocal">
    <property name="trunkMetadata" value="file:///#{globalProperty['config.dir']}/repositoryLocal/plugins.xml" />
  </property>
</property>

Because this is offline, any sub-properties with a trunkMetadata using http:// to a site you can't reach off-line, needs to be commented out. In the default plugins.xml above, that will leave only the repositoryLocal property active, which is fine, since it uses the file:// protocol. You can use that directory, or leave it for development, and add a new section with your own directory name:

<property name="repositoryLibrary">
	<property name="repositoryLocal">
		<property name="trunkMetadata" value="file:///#{globalProperty['config.dir']}/repositoryLocal/plugins.xml" />
	</property>
	<property name="snapshot12">
		<property name="trunkMetadata" value="file:///#{globalProperty['config.dir']}/snapshot12/plugins.xml" />
	</property>
</property>

Place your plugins in snapshot12/plugins, and use the following command to create the file: snapshot12/plugins.xml:

genMetadata -plugins c:/tolven-config/snapshot12/plugins -liburl file:///c:/tolven-config/snapshot12 -outdir c:/tolven-config/snapshot12

If you decided to use repositoryLocal, then execute the above command targeted at that directory.

Using a Tolven Catalog Snapshot

If you will be using the recommended Tolven install process which uses the live version of plugins, then you can ignore this section. In that case, plugins will be downloaded from the live Tolven plugin site, on-demand, when you run getPlugins (repositoryInit) command later during the install process. If you want to use a static snapshot of the Tolven Plugin Catalog, you can do so by following this procedure:

Snapshots are available from a location separate from the normal Tolven Plugin Catalog such as in the snapshots folder adjacent to the live catalog location. You will have to modify the tolven-config/plugins.xml file that was created above in order to reference a snapshot.

Tolven V2 uses two catalogs and therefore two snapshots. One catalog is the V0 catalog which contains plugins that have not changed in V2, and then the V2 catalog containing plugins new or changed for V2. Change both entries as show below. A third entry, for repositoryLocal, does not need to change.

Also, set the useSnapshot properties to true, otherwise, it will use the live (trunk) plugins.

Your repositoryLibrary section should look like this:

<property name="repositoryLibrary">
  <property name="catalog0">
    <property name="trunkMetadata" value="http://tolven.org/download/plugins.xml" />
    <property name="snapshotMetadata" value="http://tolven.org/download/snapshots/plugins20100723051950.xml" />
    <property name="useSnapshot" value="true" />
    <property name="overwriteSnapshot" value="false" />
  </property>
  <property name="catalog2">
    <property name="trunkMetadata" value="http://tolven.org/download/v2/catalog/plugins.xml" />
    <property name="snapshotMetadata" value="http://tolven.org/download/v2/catalog/snapshots/plugins20100910025956.xml" />
    <property name="useSnapshot" value="true" />
    <property name="overwriteSnapshot" value="false" />
  </property>
  <property name="repositoryLocal">
     <property name="trunkMetadata" value="file:///#{globalProperty['config.dir']}/repositoryLocal/plugins.xml" />
  </property>
</property>

The snapshot of the installation documentation, possibly the document you are reading now, is also located in the snapshots directory.

Creating a Local Tolven Catalog Snapshot

This mechanism is also capable of creating a snapshot for you. In that case, your plugins.xml would be modified as follows:

  <property name="repositoryLibrary">
        <property name="v0">
            <property name="trunkMetadata" value="http://tolven.org/download/plugins.xml" />
            <property name="snapshotMetadata" value="file:///#{globalProperty['installation.dir']}/repositorySnapshot/v0/plugins.xml" />
            <property name="useSnapshot" value="true" />
            <property name="overwriteSnapshot" value="false" />
        </property>
        <property name="v2">
            <property name="trunkMetadata" value="http://tolven.org/download/v2/catalog/plugins.xml" />
            <property name="snapshotMetadata" value="file:///#{globalProperty['installation.dir']}/repositorySnapshot/v2/plugins.xml" />
            <property name="useSnapshot" value="true" />
            <property name="overwriteSnapshot" value="false" />
        </property>
        <property name="repositoryLocal">
            <property name="trunkMetadata" value="file:///#{globalProperty['config.dir']}/repositoryLocal/plugins.xml" />
        </property>
    </property>

In this case, the plugin.xml files will be downloaded to a place on your local system. As long as useSnapshot is true, repositoryInit will use this snapshot instead of the live plugins.xml.

Step 4 - Configure Your Database

Configure your selected database.

4.1 Configure PostgreSQL

In a later step, the Tolven configuration Manager will add SSL certificates to the postgres directory and add schemas to the PostgreSQL database. Here, you must configure postgreSQL to use SSL.

4.1.1 Modify pg_hba.conf

Use Notepad or wordpad to modify postgreSQL/version/data/pg_hba.conf to allow network access to the database. JDBC, even from localhost, requires network access to the database. Documentation is included in that file. The uncommented line should look something like this:

# TYPE   DATABASE    USER        CIDR-ADDRESS          METHOD
hostssl  postgres    postgres    127.0.0.1/32          md5 

You are done with the pg_hba.conf file, although remember to change this file if you need to access postgreSQL from clients not on localhost. You can also change the TYPE from hostssl to host, which will allow connections via non-ssl clients, but this is not recommended.

4.1.2 Modify postgresql.conf

4.1.2.1 Modify postgresql.conf to Enable SSL

Next, edit the postgreSQL/version/data/postgresql.conf file so that its security configuration enables SSL.

In the postgresql.conf file this line:

# ssl = off 

should be changed to:

ssl = on 

(remove the # and change off to on)

4.1.2.2 Modify postgresql.conf Maximum Transactions

The postgres.conf file has a property value which can lead to a warning message:

WARN [loggerI18N] [com.arjuna.ats.internal.jta.resources.arjunacore.norecoveryxa] [com.arjuna.ats.internal.jta.resources.arjunacore.norecoveryxa]
Could not find new XAResource to use for recovering non-serializable XAResource...

To resolve this issue, change the max_prepared_transactions property to be greater than zero. For example, uncomment and change the following:

max_prepared_transactions = 5 # zero disables the feature

You must restart the PostgreSQL server for this change to take effect.

4.2 Configure Oracle

Add a user to Oracle called tolven, which has permissions to create tables, indexes etc.

Step 5 - Set Up Your Security Environment

These mandatory steps are needed in order to successfully install the single sign on environment on which Tolven depends.

5.1 Set Up Server Name

Tolven and SSO depend on the ability to authenticate server components such as web and EJB containers. As such, you must establish proper domain names for each server, even in a development environment. Using IP addresses or the generic localhost will not work.

You should start by establishing the number of physical or virtual servers and their operating systems will be needed for your configuration. Each server should have or be given a domain name. If the server is already in a public or corporate DNS, then the domain name provided is adequate. If not, then you will need to create entries in the hosts file for your system.

Each server will need a digital certificate. For example, let's say that you will use two physical servers. That means that you will ultimately need two digital certificates, one for each of these systems. Each system may already have a simple host name. We will use able and baker as the host names in the rest of the instructions.

But these host names are not domain names, which typically have a dot in the name. In fact, during the installation, certain components will verify that the dot is present.

Note: OpenAM requires two dots, such as dev.able.com. Therefore, we will use an example with two dots.

In this example and in the remainder of the installation instructions, we will prefix the type of system to the name, such as dev, test, prod, etc.

If you don't have this domain name registered on the internet, you can add an entry to the hosts file for each node containing the IP address and the domain name - each name with at least two dots.

192.168.1.101 dev.able.com
192.168.1.102 dev.baker.com

The advantage to this approach is that the hosts file can be the same on each system.

If everything runs on a single server, you can use IP address 127.0.0.1 for dev.able.com or whatever domain name you decide to use.

5.2 Set Up SSL Keystore

Each physical or virtual server (node) involved in Tolven will need to have a keystore containing keys that are used to authenticate that server. See step Set Up Server Name.

You will create one keystore per node. For this example, we will use two server nodes to deploy Tolven, named dev.able.com and dev.baker.com. Therefore, we will create two keystores. This means that if you were to run more than one application server container (any mixture of Glassfish, JBoss, Tomcat, etc. servers) on a single node, then each container on that node will use the same credentials.

You should store the credentials in a place where you can find them later. For this example, we will store them in:

tolven-config/credentials/dev.able.com/ and

tolven-config/credentials/dev.baker.com/.

There will be a step later in the installation process that will set the alias, password, and file name of these credentials in the products that use them.

Use the [Java Keytool] to create the keystore for each node. The dname must refer to the domain name and realm that will be used in the SSO configuration. The c=, o= and ou= entries can be whatever you want.

mkdir /tolven-config/credentials/dev.able.com/
cd /tolven-config/credentials/dev.able.com/
keytool -genkey -alias tolven -dname "cn=dev.able.com, ou=services, o=tolven, c=US" -keystore keystore.jks -storepass 
  tolven -keypass tolven -validity 7300 

Repeat the process for the other node:

mkdir /tolven-config/credentials/dev.baker.com/
cd /tolven-config/credentials/dev.baker.com/
keytool -genkey -alias tolven -dname "cn=dev.baker.com, ou=services, o=tolven, c=US" -keystore keystore.jks -storepass 
  tolven -keypass tolven -validity 7300 

Later, you will use the Java Keytool again to create a truststore called cacerts which will contain a reference to the (public) keys each node is willing to trust. This completes the two halves of mutual authentication between any given two server nodes.

5.3 Set Up SSL Truststore

Each physical or virtual server (node) involved in Tolven will need to maintain a list of server nodes that it will trust. This is done by creating a truststore and putting the public keys of each node to be trusted into that truststore.

If not done already, see step 5.2 Set Up SSL Keystore to setup the keystore(s).

To setup a truststore, you will use the [Java Keytool]. Although you may choose to do so, Tolven avoids using the cacerts file located in the Java directory. You should store the truststores in a place where you can find them later. For this example, we will store them in /tolven-config/credentials/dev.able.com/ and /tolven-config/credentials/dev.baker.com/.

To create and populate the truststore with the first public key to be trusted by able, you may first need to export the public key to be trusted:

cd /tolven-config/credentials/dev.able.com/
keytool -export  -alias tolven -file cert.cer -rfc -keystore keystore.jks -storepass tolven

Repeat this process again for dev.baker.com:

cd /tolven-config/credentials/dev.baker.com/
keytool -export  -alias tolven -file cert.cer -rfc -keystore keystore.jks -storepass tolven

Next, import the dev.baker.com certificate into the truststore for dev.able.com and vice versa for baker's truststore. Also, it is reasonable to expect that components on the same server may authenticate one another. Therefore, you will also import the certificate for each server into the corresponding cacerts. This will cover all permutations.

cd /tolven-config/credentials/dev.able.com/
keytool -import -alias dev.able.com -file cert.cer -keystore cacerts.jks -trustcacerts -storepass tolven -keypass tolven
keytool -import -alias dev.baker.com -file ../dev.baker.com/cert.cer -keystore cacerts.jks -trustcacerts -storepass 
  tolven -keypass tolven

Repeat this process again for dev.baker.com, which will trust dev.able.com and itself:

cd /tolven-config/credentials/dev.baker.com/
keytool -import -alias dev.baker.com -file cert.cer -keystore cacerts.jks -trustcacerts -storepass tolven -keypass tolven
keytool -import -alias dev.able.com -file ../dev.able.com/cert.cer -keystore cacerts.jks -trustcacerts -storepass 
  tolven -keypass tolven

At this point, under the dev.able.com folder, you should have one keystore (keystore.jks) and one truststore (cacerts.jks) as well as the exported certificate, cert.cer. You can repeat this process for as many nodes as you have in your network.

5.4 Set Up MQKeystore

Use Sun's Keytool utility to create a self-signed JKS tolvendev-mdbuser.p12 file, with your chosen password. The cn can be, for example mdbuser, and will later be used as the defaultAlias during the configuration of the MQKeyStore. The o=, ou=, etc. parameters are not currently used.

mkdir /tolven-config/credentials/mdbuser/
cd /tolven-config/credentials/mdbuser/
keytool -genkeypair -alias mdbuser -keyalg RSA -dname "cn=mdbuser, ou=services, o=tolven, c=US" -keystore tolvendev-mdbuser.p12 
  -storetype pkcs12 -storepass tolven -keypass tolven -validity 7300 

Note: Only the RSA algorithm is currently supported, and after this keystore is used by the Tolven application, you must back it up.

5.5 Set Up PostgreSQL SSL

This step requires the use of openssl because the keytool utility provides no functionality to directly export a private key from a *.jks file. When prompted for a password by openssl:

1. Create a keystore.p12 from the keystore.jks:

keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -srcstoretype JKS -deststoretype PKCS12 
-srcstorepass tolven -deststorepass tolven -noprompt

2. Export the postgresql SSL server.key from the keystore.p12 (you will be prompted for the keystore password, default: tolven):

openssl pkcs12 -in keystore.p12 -out server.key -nocerts

3. Export the postgresql SSL server.crt from the keystore.p12 (you will be prompted for the keystore password more than once, default: tolven):

openssl pkcs12 -in keystore.p12 -out server.crt -nokeys

4. Create the postgresql SSL root.crt.

5. Make a copy of server.crt and call it root.crt.

6. Copy the three files server.key, server.crt, and root.crt to the postgresql data directory:

a. PostgreSQL requires the server.key to be unencrypted, which can be done as follows:

openssl dsa -in server.key -out server-nopasswd.key

b. Move server.key to backup (NB: It is always available from keystore.jks anyway).

c. Rename server-nopasswd.key back to server.key.

d. Ensure all three files are owned by postgres.

e. Ensure that permissions are read-only.

7. Restart PostgreSQL.

Step 6 - Assemble Tolven

Next, you will be assembling Tolven itself. The assembly process will only create components in the <config-dir>/build directory, and in particular the staging area:

• <config-dir>/build/repositoryStage

Some files will be deployed using commands, and some files will need to be manually deployed to their final destination. The deployment process will not occur until later at the end of the entire configuration process.

Note: Assembly is required whenever you make changes to the plugins.xml file in the <config-dir>, or when new or updated plugins are downloaded from a catalog.

The bulk of this configuration process involves customizing the tolven-config/plugins.xml file and running various plug-ins that assemble the configured Tolven components. There are many other properties in plugins.xml that you may want to change. Whenever these properties are changed, you must run configPhase1 in order for them to take effect. However, during this initial configuration, do not execute this command until instructed to do so later in this installation guide.

6.1 Edit Global Properties

Three important properties defined in this file must be edited to reference your local installation directories:

<property name="authRestful.url" value="https://dev.able.com:8444/openam/identity"/>
<property name="appRestful.url" value="https://dev.able.com:8443/api"/>
<property name="appserver.home" value="your-appserver-homeDir" />

Property	Windows Example	Description
appserver.home	C:/tolven-glassfish3	This location of the target application server. This property helps TPF determine where to deploy the assembled Tolven EAR file.

Note: appRestful.url appears twice in the plugins.xml file.

Note: On Windows, you must use forward slashes when specifying directory paths in these Java-based properties files (backslash is taken as an escape character).

6.2 Initialize the Runtime Repository

The Runtime Repository normally starts out empty and valid. It will contain the plugins that will be downloaded, selected, and used to configure Tolven. Once the root plugins have been selected for addition to the Runtime Repository, all the dependent plugins can be determined from those root plugins. After running the repositoryInit command, make note of any errors on the console and check the server log for details. Because having the plugins download correctly is essential, resolve any issues before proceeding with the installation.

Troubleshooting: If, when running repositoryInit, you get a cannot delete file for one or more of the plugins, manually delete the file and re-run repositoryInit.

Windows:

cd <install-dir>\bin
repositoryInit

Linux:

cd <install-dir>/bin
./repositoryInit.sh

Tolven will then contact each of the Library Repositories and download the root plugins by default, followed by all the dependent plugins. When complete, the following directory should contain a number of plugin zip files:

c:/tolven-config/repositoryRuntime/plugins

6.3 Run the Check Integrity Command

Check that the files below contain the properties and path files that you have used in previous steps. Do not change the username, password, and role to those that you used when you installed the policy agent. To run the check integrity command and all over commands in this installation, leave the default username <coe>admin</code>, password sysadmin, and role tolvenAdmin.

Also, the domain that is referenced in these files is dev.able.com for both the keystore and truststore. If you are installing in a domain other than dev.able.com, you must also make sure that these files reference your domain.

Windows:

tpfenv.bat and tpf.bat

Linux:

tpfenv.sh OR tpf.sh

Execute the following command which carries out a light integrity check that is adequate at this stage:

checkIntegrity

There should be no errors in the command shell or in the <install-dir>/log/tolven.log.

6.4 Run Phase 1 Configuration

The configPhase1 command is located in the <install-dir>/bin directory and assembles the Tolven libraries required by Glassfish.

configPhase1

No files are deployed to Glassfish during this command and it will only result in the creation of the following files:

tolven-config/build/repositoryStage/tolven-glassfish3/glassfish/domains/tolven/lib/mqKeyStore-api.jar
tolven-config/build/repositoryStage/tolven-glassfish3/glassfish/domains/tolven/lib/tolvenCommon.jar
tolven-config/build/repositoryStage/tolven-glassfish3/glassfish/domains/tolven/lib/tolven-openamclient.jar

Note: The build directory is periodically deleted if changes are made to the tolven-config/plugins.xml or if repositoryInit is used to download new plug-ins. If that is the case, then configPhase1 must be executed again to ensure the latest jar files are available for later deployment.

6.5 Run Phase 2 Configuration

This phase involves one-time and rarely changed configuration steps. The actual effect of configPhase2 depends on the database you've chosen.

6.6 Create Schemas

Oracle:

Tolven does not require that you create any Oracle schemas.

Postgre:

Tolven requires PostgreSQL to have the schemas shown below. Please use your database tool (for example, psql or pgAdminIII) to create the schemas.

CREATE SCHEMA app;
COMMENT ON SCHEMA app IS 'Application metadata and extracted instance data';
CREATE SCHEMA core;
COMMENT ON SCHEMA core IS 'User, account, sequence generator and related tables';
CREATE SCHEMA ctom;
COMMENT ON SCHEMA ctom IS 'NCI Clinical Trial Object Model';
CREATE SCHEMA doc;
COMMENT ON SCHEMA doc IS 'Document Metaphor storage';
CREATE SCHEMA flow;
COMMENT ON SCHEMA flow IS 'Business Process Flow';
CREATE SCHEMA gen;
COMMENT ON SCHEMA gen IS 'Seed Data for Virtual Patient Generation';
CREATE SCHEMA jms;
COMMENT ON SCHEMA jms IS 'JMS Message processing';
CREATE SCHEMA provider;
COMMENT ON SCHEMA provider IS 'Provider';
CREATE SCHEMA public;
COMMENT ON SCHEMA public IS 'Default schema';
CREATE SCHEMA umls;
COMMENT ON SCHEMA umls IS 'UMLS Tables';
CREATE SCHEMA who;
COMMENT ON SCHEMA who IS 'World Health Organization Tables';

6.7 Assemble Tolven OpenAM Library Jar

tpf -plugin org.tolven.assembler.library -libPlugin org.tolven.openam

No files are deployed to Glassfish during this command and it will only result in the update of the following directory:

tolven-config/build/repositoryStage/org.tolven.openam/web

Tolven comes with encryption (document encryption, etc.) turned on by default, but encryption only takes place if users have a userPKCS12 keystore. The required library is located in the web/WEB-INF/lib/tolven-openam-auth.jar, and this jar must be incorporated as a library for OpenAM. In addition, as part of the post-authentication process, users need to have certain session variables set by default, and this is currently the only means available in OpenAM.

The web directory also contains a number of other configuration files required by Tolven. For example, when changing user passwords, the corresponding user keystore password (if the keystore exists) needs to be kept in sync.

6.8 Assemble MQKeyStore

tpf -plugin org.tolven.assembler.connectormodule -rarPlugin org.tolven.mqkeystore

No files are deployed to Glassfish during this command and it will only result in the update of the following directory:

tolven-config/build/repositoryStage/org.tolven.mqkeystore

6.9 Assemble Tolven EAR File

tpf -plugin org.tolven.assembler.ear -earPlugin org.tolven.component.tolvenear -earFile tolven.ear

No files are deployed to Glassfish during this command and it will only result in the update of the following directory:

tolven-config/build/repositoryStage/org.tolven.component.tolvenear

Step 7 - Install & Configure Identity Software

The identity software does not need to be on the same machine as the Tolven Application Server.

7.1 Install, Start & Stop OpenDS

The OpenDS LDAP server is used by Tolven to store user data for the purpose of user authentication and to provide user demographic data. Tolven usually does not access LDAP directly but rather the single-signon server accesses LDAP. In particular, passwords are never stored in Tolven.

7.1.1 Check Port Assignments & Security Setup

• OpenDS is a free-standing server which typically listens on port 636 (LDAPS). Therefore, this port must be available on the server that it is installed on. As a convention, Tolven assigns alternate ports by prefixing the number with 1, 2, 3, etc.

• The OpenDS server uses SSL and therefore, you should have already created or acquired keystore(s) and created truststore(s) in previous installation steps.
  

7.1.2 Install OpenDS

OpenDS installation is straightforward. Unzip the downloaded OpenDS-2.3.0.zip to a location such as c: on Windows or /usr/local/ on Linux.

7.1.3 Start OpenDS

7.1.3.1 Start OpenDS From Command Line

You can start by starting OpenDS on an insecure port but the SSL port will be activated during configuration.

Windows:

C:\OpenDS-2.3.0\bat\start-ds.bat

Linux:

./usr/local/OpenDS-2.3.0/bin.start-ds

7.1.3.2 Start (& Stop) OpenDS Using the Control Panel

OpenDS has a GUI tool to allow direct query and editing of LDAP data. This tool will allow you to start and stop OpenDS.

openDS\bin> control-panel.bat

7.1.4 Stop OpenDS

Because you will be configuring OpenDS shortly, shut down OpenDS if it is currently running.

Either click the Stop button on the control panel or, stop it via the command line:

Windows:

C:\OpenDS-2.3.0\bat\stop-ds.bat

Linux:

./usr/local/OpenDS-2.3.0/bin.stop-ds

7.2 Configure OpenDS

You should have already followed the instructions to Install OpenDS.

7.2.1 Set Up Tolven-Specific Configuration

Unzip the contents of downloaded file org.tolven.opends.config-2.0.5.zip to your OpenDS installation. Notice the corresponding file hierarchies. This will add Tolven-specific configuration files to the OpenDS installation.

One of the files just added is config/tolvendev-keystore.pin which contains the password used to protect the SSL Java Keystore used by OpenDS. In order to enter the following commands, the password for your OpenDS SSL JKS passwords needs to be in config/tolvendev-keystore.pin, which currently contains the default password: tolven. Ensure that only the owner of the OpenDS directory can read this password file.

Basic access controls for OpenDS can be found in the LDIF files in the OpenDS directory, which will be used with the commands below.

There is a Tolven administrator called uid=Manager,ou=people,dc=tolven,dc=com, which is different from the default rootDN cn=Directory Manager.

The rootDN password that comes with OpenDS is password. This is used with the -w option below. The password for the Tolven administrator appears in tolven-admin.ldif as an {SSHA} entry. This password, by default, is secret.

You can change the Tolven LDAP manager password (secret) using an LDAP browser UI. However, if you allow Tolven to access this LDAP, then Tolven will also need to know this password.

Also verify the paths to the keystore.jks and cacerts.jks files, and check that the port which defaults to 636 is the one you want to use. (If you have more than one LDAP on a single box, you will probably need to assign additional ports. We used 1636, 2636, etc. Port 4444 in the commands below is the administration port for OpenDS. It will be changed to 5555 in order to avoid a port conflict later.

7.2.2 Configure OpenDS

Windows:

Execute the following from the openDS directory:

cd c:\OpenDS-2.3.0

set opts=-h localhost -p 4444 -D "cn=Directory Manager" -w password -X --no-prompt 

bat\start-ds.bat

bat\dsconfig %opts% set-password-policy-prop --policy-name "Default Password Policy" --set allow-pre-encoded-passwords:true

bat\dsconfig %opts% set-key-manager-provider-prop --provider-name "JKS" --set enabled:true  ^
 --set key-store-type:JKS --set key-store-file:C:/tolven-config/credentials/dev.able.com/keystore.jks ^
 --set key-store-pin-file:c:/openDS-2.3.0/config/tolvendev-keystore.pin

bat\dsconfig %opts% set-trust-manager-provider-prop --provider-name "JKS" --set enabled:true ^
 --set trust-store-type:JKS --set trust-store-file:C:/tolven-config/credentials/dev.able.com/cacerts.jks ^
 --set trust-store-pin-file:c:/openDS-2.3.0/config/tolvendev-keystore.pin

bat\dsconfig %opts% set-connection-handler-prop --handler-name "LDAPS Connection Handler" ^
 --set enabled:true --set listen-port:636 --set ssl-client-auth-policy:optional --remove ssl-cert-nickname:server-cert

bat\dsconfig %opts% set-connection-handler-prop --handler-name "LDAP Connection Handler" --set enabled:false

bat\dsconfig %opts% set-backend-prop --backend-name userRoot --add base-dn:dc=tolven,dc=com  --noPropertiesFile

bat\dsconfig %opts% set-backend-prop --backend-name userRoot --remove base-dn:dc=example,dc=com

bat\import-ldif -h localhost -p 4444 -X --bindDN "cn=Directory Manager" ^
 --bindPassword password -l c:/OpenDS-2.3.0/tolven-admin.ldif ^
 --backendID userRoot --append --noPropertiesFile 

bat\ldapmodify -h localhost -p 4444 -D "cn=Directory Manager" -w password -X --useSSL ^
 --keyStorePath C:/tolven-config/credentials/dev.able.com/keystore.jks -W tolven --filename c:/OpenDS-2.3.0/tolven-aci.ldif

bat\ldapmodify -h localhost -p 4444 -D "cn=Directory Manager" -w password -X --useSSL ^
--keyStorePath C:/tolven-config/credentials/dev.able.com/keystore.jks -W tolven --filename c:/OpenDS-2.3.0/tolven-user-status.ldif

rem switch to port 5555
bat\dsconfig %opts% set-administration-connector-prop --set listen-port:5555

rem Restart server to activate port change
bat\stop-ds.bat
bat\start-ds.bat

rem Just a test to make sure the server is up and listening
bat\ldapsearch --hostname localhost --port 5555 --useSSL -w password -X --baseDN "ou=people,dc=tolven,dc=com" "(objectClass=*)"
bat\ldapsearch --hostname localhost --port 5555 --useSSL -w password -X --baseDN "ou=groups,dc=tolven,dc=com" "(objectClass=*)"

The second to last line just verifies that the administration port was successfully changed. It also shows the users created. The results should look something like this:

dn: ou=people,dc=tolven,dc=com
ou: people
objectClass: organizationalunit

dn: uid=Manager,ou=people,dc=tolven,dc=com
objectClass: person
objectClass: organizationalperson
objectClass: inetorgperson
uid: Manager
cn: Manager
sn: Manager

dn: uid=admin,ou=people,dc=tolven,dc=com
objectClass: person
objectClass: organizationalperson
objectClass: inetorgperson
uid: admin
cn: admin
sn: admin

The last line just verifies that the roles were added. The results should look something like this:

dn: ou=groups,dc=tolven,dc=com
ou: groups
objectClass: organizationalunit

dn: cn=Administrator,ou=groups,dc=tolven,dc=com
uniqueMember: uid=Manager,ou=people,dc=tolven,dc=com
cn: Administrator
objectClass: groupOfUniqueNames

dn: cn=tolvenSSO,ou=groups,dc=tolven,dc=com
uniqueMember: uid=admin,ou=people,dc=tolven,dc=com

dn: cn=tolvenAdmin,ou=groups,dc=tolven,dc=com
uniqueMember: uid=admin,ou=people,dc=tolven,dc=com

Linux:

Execute the following from the openDS directory (note the verification steps in the windows version above):

cd /usr/local/OpenDS-2.3.0

OPTS='-h localhost -p 4444 -D "cn=Directory Manager" -w password -X --no-prompt'

start-ds

bin/dsconfig $OPTS set-password-policy-prop --policy-name "Default Password Policy" \
 --set allow-pre-encoded-passwords:true

bin/dsconfig $OPTS set-key-manager-provider-prop --provider-name "JKS" \
 --set enabled:true --set key-store-type:JKS \
 --set key-store-file:/usr/local/tolven-config/credentials/dev.able.com/keystore.jks \
 --set key-store-pin-file:config/tolvendev-keystore.pin

bin/dsconfig $OPTS set-trust-manager-provider-prop --provider-name "JKS" \
 --set enabled:true --set trust-store-type:JKS \
 --set trust-store-file:/usr/local/tolven-config/credentials/dev.able.com/cacerts.jks \
 --set trust-store-pin-file:config/tolvendev-keystore.pin

bin/dsconfig $OPTS set-connection-handler-prop --handler-name "LDAPS Connection Handler" \
 --set enabled:true --set listen-port:636 --set ssl-client-auth-policy:optional \
 --remove ssl-cert-nickname:server-cert

bin/dsconfig $OPTS set-connection-handler-prop --handler-name "LDAP Connection Handler" \
 --set enabled:false

bin/dsconfig $OPTS set-backend-prop --backend-name userRoot \
 --add base-dn:dc=tolven,dc=com  --noPropertiesFile

bin/dsconfig $OPTS set-backend-prop --backend-name userRoot \ 
--remove base-dn:dc=example,dc=com

bin/import-ldif -h localhost -p 4444 -X --bindDN "cn=Directory Manager" \
 --bindPassword password -l tolvenOpenDS/tolven-admin.ldif \
 --backendID userRoot --append --noPropertiesFile 

bin/ldapmodify -h localhost -p 4444 -D "cn=Directory Manager" -w password -X \
 --useSSL --keyStorePath /usr/local/tolven-config/credentials/dev.able.com/keystore.jks \
 -W tolven --filename tolvenOpenDS/tolven-aci.ldif

bin/ldapmodify -h localhost -p 4444 -D "cn=Directory Manager" -w password -X \
 --useSSL --keyStorePath C:/tolven-config/credentials/dev.able.com/keystore.jks \
 -W tolven --filename c:/OpenDS-2.3.0/tolven-user-status.ldif

bin/dsconfig $OPTS set-administration-connector-prop --set listen-port:5555
stop-ds
start-ds

bin/ldapsearch --hostname localhost --port 5555 --useSSL -X --baseDN "ou=people,dc=tolven,dc=com" "(objectClass=*)"
bin/ldapsearch --hostname localhost --port 5555 --useSSL -X --baseDN "ou=groups,dc=tolven,dc=com" "(objectClass=*)"

Note: At this point, OpenDS is running and should not need to be taken down again.

7.2.3 Reconfigure Control Panel

Edit the file C:\OpenDS-2.3.0\config\tools.properties and uncomment (or replace) the host/port/bind address as needed.

hostname=dev.able.com
port=5555
bindDN=cn=Directory Manager

This will allow the control panel to connect to the correct OpenDS administrative port.

7.2.4 Running OpenDS From the Control Panel

You can run the OpenDS control panel if you want to browse the directory, stop and start the server, etc.

C:\OpenDS-2.3.0\bat\control-panel.bat
or
/usr/local/OpenDS-2.3.0/bin/control-panel

7.2.5 Installing OpenDS as a Windows Service

If you would like to run OpenDS as a Windows Service, use the following command:

bat\windows-service -e

7.3 Install & Start Tomcat

Tomcat will be used in this procedure as the container where OpenAM (single sign on server) runs.

7.3.1 Check Port Setup

Tomcat will listen on ports 8080 and 8444 which are sufficient for development. It also listens on port 8005 for shutdown commands. Therefore, all of these ports must be available on the host on which it will be installed. If you need to change any of these ports, do so by changing the conf/server.xml file.

7.3.2 Install Tomcat

Unzip the downloaded apache-tomcat-7.0.5.zip into the directory apache-tomcat-7.0.5, which is the default.

7.3.3 Start Tomcat

Temporarily start Tomcat using one of the following:

Linux:

apache-tomcat-7.0.5/bin/startup.sh

Windows:

apache-tomcat-7.0.5/bin/startup.bat

Later, you will use a customized version of these files to start Tomcat.

Check files in apache-tomcat-7.0.5/logs for errors.

7.3.4 Test Tomcat

At this point you should be able to navigate to the default pages in Tomcat using a browser and verify that Tomcat is working properly:

http://localhost:8080/

7.3.5 Shut Down Tomcat

Shut down Tomcat using one of the following:

Windows:

apache-tomcat-7.0.5/bin/shutdown.bat

Linux:

apache-tomcat-7.0.5/bin/shutdown.sh

You will make additional changes to this configuration in subsequent steps.

7.4 Configure Tomcat

Tolven requires that you establish credentials in Tomcat. See Step 4 - Set Up Your Security Environment for detailed instructions.

7.4.1 Remove Sample WAR Files

There are several folders under webapps containing sample web applications which you can delete.

Leave the ROOT webapp.

7.4.2 Enable HTTPS Access

Edit apache-tomcat-7.0.0/conf/server.xml in order to activate the https connector. You can either paste the following or edit the (commented) connector as shown below:

<Connector port="8444" protocol="org.apache.coyote.http11.Http11Protocol" 
    SSLEnabled="true"
    maxThreads="150" scheme="https" secure="true" 
    clientAuth="false" sslProtocol="TLS" 
    keystoreFile="C:\tolven-config\credentials\dev.able.com\keystore.jks" 
    keystorePass="tolven"
    keyAlias="tolven"/>

In order to avoid a port conflict with other components on the same server, comment out the following lines in server.xml:

    <!--<Connector port="8080" protocol="HTTP/1.1" 
               connectionTimeout="20000" 
               redirectPort="8443" /> -->

Edit the keystore location as needed. In this example, Tomcat will be installed on node dev.able.com.

Note: Do not set up Tomcat to listen on a on a non-SSL port (80, 8080, etc.). If Tomcat listens those ports, it will run into conflicts with the application server which by default Tolven configures to listen on those ports.

Restart Tomcat and continue with the Glassfish install, letting Glassfish use port 8080.

7.5 Install OpenAM

• OpenAM, the single sign on server, is deployed as a war file in a Tomcat or similar Java EE web container.

• OpenAM requires a Java EE Servlet container such as Tomcat or one of the EJB containers that have a built-in Web container such as Glassfish or Tomcat. The container should be configured for HTTPS access.

• If you have not done so already, follow the instructions in step 7.3.2 Install Tomcat and step 7.4 Configure Tomcat. The Tomcat server should not be running.

• This procedure will require at least one LDAP server to be installed and operational. See step 7.1.2 Install OpenDS. Once installed with proper credentials, the LDAP server should not need to be taken down again.

• You should have already created or acquired keystore(s) and created truststore(s) as described in Step 4 - Set Up Your Security Environment.

7.5.1 Unzip the OpenAM Download

Unzip the openam_snapshot_951RC2.zip file that you downloaded. Look for the opensso.war file in <openam_folder>/opensso/deployable-war.

7.5.2 Copy, Rename and Install the war File

1. Because ForgeRock has renamed the opensso.war file in later updates of OpenAM, and in order to make further upgrades smoother going forward with Tolven, make a copy of opensso.war and rename it to openam.war.

2. Place the openam.war file that you copied and renamed in apache-tomcat-7.0.0/webapps.

7.5.3 Start Tomcat

cd to the following directory:

• apache-tomcat-7.0.0/bin

Start Tomcat using one of the following commands:

Windows:

apache-tomcat-7.0.0/bin/startup.bat

Linux:

apache-tomcat-7.0.0/bin/startup.sh

7.5.4 Test OpenAM

This is just an initial test to verify that the base OpenAM was installed properly.

Don't try creating a configuration yet, because the presence of an existing configuration will cause failure of the automated configuration tool, which will be used a later step. Start Tomcat using the instructions above if it is not already started.

https://localhost:8444/openam

7.6 Configure OpenAM

The OpenAM configuration is unavoidably complex. In particular, please be aware of the subtle distinction between the OpenAM configuration tool, which is used to setup an initial configuration and the OpenAM admin tool, which is used to setup Tolven-specific settings. In addition, because OpenAM runs in a Tomcat Web server container, Tomcat also plays a role in the OpenAM configuration process.

OpenAM must have already been downloaded, unzipped, and the war file installed into a container (Tomcat).

7.6.1 Installing tolven-openam-auth.jar in OpenAM

1. Stop the Tomcat server:

Shut down Tomcat using one of the following:

Windows:

apache-tomcat-7.0.0/bin/shutdown.bat

Linux:

apache-tomcat-7.0.0/bin/shutdown.sh

2. The contents of the web directory below (not the web directory itself) need to be copied to the openam.war archive, maintaining the hierarchy, which will match that already found in openam.war. Be sure to use an original openam.war archive, and not one that you've previously updated with Tolven updates. The web directory was created during the Assemble Tolven process and is located in:

<your-config-directory>/build/repositoryStage/org.tolven.openam/web

3. Remove the openam directory to ensure that when Tomcat is restarted, it will recreate it from the updated openam.war file.

4. Restart Tomcat and check the logs for any errors.

Redundant Section 7.6.2 Removed

7.6.2 Unzip Tolven Configuration Files

1. Stop the tomcat server again and proceed to the next step.
2. Unzip the downloaded org.tolven.openam.config-2.0.15.zip file to apache-tomcat-7.0.0. The directory structures in the zip file corresponds with the Tomcat file structure.

7.6.3 Add Custom Tomcat Startup

The following custom startup script will add appropriate JVM properties to support SSL. This SSL configuration is different from the connector ssl configuration which is used by browsers and other HTTP clients. This server will also require mutual authentication with other components.

Check and edit the contents of one the following files to ensure that the paths to the credentials that you setup previously are correct:

Windows:

apache-tomcat-7.0.0/bin/tolvenstartup.bat

Linux:

apache-tomcat-7.0.0/bin/tolvenstartup.sh

7.6.4 Add Tolven Configuration Files

Notice that the files listed below are now in a new folder under apache-tomcat-7.0.0 named openam-conf.

• apache-tomcat-7.0.0/openam-conf/amWebAgent.xml
• apache-tomcat-7.0.0/openam-conf/tolven-agent-attributes.txt
• apache-tomcat-7.0.0/openam-conf/tolven-datastore-attributes.txt
• apache-tomcat-7.0.0/openam-conf/tolven-global-attributes.txt
• apache-tomcat-7.0.0/openam-conf/tolven-policies.xml
• apache-tomcat-7.0.0/openam-conf/tolven-referrals.xml
• apache-tomcat-7.0.0/openam-conf/tolven-ws-policies.xml

Check the contents of the files to ensure that domain names, hosts, etc. match your network configuration. In particular, note the LDAP password in tolven-datastore-attributes.txt (authpw). If you changed the formal domain name you assigned in the Set Up Server Name step from the default value of dev.able.com, edit each of these files to reflect your formal name. Similarly, these files as provided assume the default port of 8443 for Tolven and 8444 for openAM. Do not change these port numbers unless you altered these ports in your local configuration.

It would be best to leave the uid=Manager,ou=people,dc=tolven,dc=com and password attributes as is until you are familiar with the administrative mechanisms of OpenDS and OpenAM.

7.6.5 Prepare to Configure OpenAM

If OpenAM has just been installed, then visiting the SERVER_URL (see below) should indicate that there is no configuration, by offering to manually create a default one or a custom one. The automated steps below will yield the default configuration.

7.6.6 Setup OpenAM Configurator Tool

This step creates an initial openam configuration. You will run a configuration tool which reads a configuration file and creates a new configuration. Subsequent steps will make further changes to the configuration. The process starts by extracting a few files to a new directory, creating a new configuration parameter file, and then running the program that generates the new configuration directory. After this step is completed, you will no longer need the configuration tool or the tolvenconfiguration file. Start Tomcat if it is not already started before completing these steps.

1. Extract ssoConfiguratorTools.zip from the downloaded openam_snapshot_951RC2.zip file to a directory of your choice, for example, you can unzip it to a folder named ssoConfiguratorTools.

2. Read the README.setup file in the unzipped directory. Make a copy of the sampleconfiguration file and name it tolvenconfiguration. Then make the following edits to the tolvenconfiguration file. Also note that the java execution command line mentioned in the README.setup file, needs to be supplied with your certificate information as will be described below shortly:

• The SERVER_URL must match the location of the openam server.
• The cookie domain must match that of the server on which openam is running. Notice the leading dot in the name.

The target configuration directory must not exist (see openam docs). Rather, this directory will be created to hold the openam configuration.

If the OpenAM server is to be running on the same box as Glassfish (which by default claims port 8443), then for the SERVER_URL below, use port 8444 instead of 8443.

Windows:

SERVER_URL=https://dev.able.com:8444
DEPLOYMENT_URI=/openam
BASE_DIR=c:/tolven-sso/openam
locale=en_US
PLATFORM_LOCALE=en_US
AM_ENC_KEY=
ADMIN_PWD=sysadmin
AMLDAPUSERPASSWD=00000000
COOKIE_DOMAIN=.dev.able.com
...
DATA_STORE=embedded
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=dev.able.com
DIRECTORY_PORT=50389
DIRECTORY_ADMIN_PORT=7777
DIRECTORY_JMX_PORT=1689
ROOT_SUFFIX=dc=opensso,dc=tolven,dc=org
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=secret

Linux:

SERVER_URL=https://dev.able.com:8444
DEPLOYMENT_URI=/openam
BASE_DIR=/user/local/tolven-sso/openam
locale=en_US
PLATFORM_LOCALE=en_US
AM_ENC_KEY=
ADMIN_PWD=sysadmin
AMLDAPUSERPASSWD=00000000
COOKIE_DOMAIN=.dev.able.com
...
DATA_STORE=embedded
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=dev.able.com
DIRECTORY_PORT=50389
DIRECTORY_ADMIN_PORT=7777
DIRECTORY_JMX_PORT=1689
ROOT_SUFFIX=dc=opensso,dc=tolven,dc=org
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=secret

Verify: The following command will create the OpenAM configuration directory, whose value is the BASE_DIR shown above. Ensure that this directory does not exist, otherwise the following command will fail, since it believes there is a previous configuration.

3. Both the Tomcat server and OpenDS must be running. Execute the configurator from the ssoConfiguratorTools directory which you created above. For example:

java -Djavax.net.ssl.keyStore=c:/tolven-config/credentials/dev.able.com/keystore.jks ^
 -Djavax.net.ssl.keyStorePassword=tolven ^
 -Djavax.net.ssl.trustStore=c:/tolven-config/credentials/dev.able.com/cacerts.jks ^
 -Djavax.net.ssl.trustStorePassword=tolven ^
 -jar configurator.jar -f tolvenconfiguration

Verify: The OpenAM configuration directory, whose value is the BASE_DIR shown above should now exist.

4. After executing the configurator.jar as described in the README.setup, and startup Tomcat, you can visit the SERVER_URL+DEPLOYMENT_URI url and should be at the OpenAM login screen instead of the configuration screen. This means that the configuration was successful.

7.6.7 Setup the OpenAM Administration Tool

The SSO administration tool is used to complete the openam configuration process. Carry out these steps:

1. Extract ssoAdminTools.zip from the downloaded openam_snapshot_951RC2.zip file as per OpenAM documentation to a new folder such as c:\ssoAdminTools.

2. Execute the setup script as described in the README.setup. You will need the directory information that you set up later in the installation process.

C:\ssoAdminTools>setup
Path to config files of OpenAM server (example: C:\opensso):c:/tolven-sso/openam)
Debug Directory:C:/ssoAdminTools/debug
Log Directory:C:/ssoAdminTools/log
The scripts are properly setup under directory: C:\ssoAdminTools\openam
Debug directory is C:/ssoAdminTools/debug.
Log directory is C:/ssoAdminTools/log.
The version of this tools.zip is: Snapshot Build 9.5.1_RC2(2010-June-30 20:23)
The version of your server instance is: Snapshot Build 9.5.1_RC2(2010-June-30 20:23)

3. Add the JSSE keystore/truststore as java -D options to the ssoAdminTools/openam/bin/ssoadm file. For example:

Windows:

-Djavax.net.ssl.keyStore=c:/tolven-config/credentials/dev.able.com/keystore.jks 
-Djavax.net.ssl.keyStorePassword=tolven 
-Djavax.net.ssl.trustStore=c:/tolven-config/credentials/dev.able.com/cacerts.jks
-Djavax.net.ssl.trustStorePassword=tolven

Linux:

-Djavax.net.ssl.keyStore=/usr/local/tolven-config/credentials/dev.able.com/keystore.jks 
-Djavax.net.ssl.keyStorePassword=tolven 
-Djavax.net.ssl.trustStore=/usr/local/tolven-config/credentials/dev.able.com/cacerts.jks
-Djavax.net.ssl.trustStorePassword=tolven

At this point, the ssoadmin tool should be available to run against the running OpenAM server in Tomcat.

7.6.8 Apply the Tolven Configuration Using ssoadmin Tool

Create a file named amadminpassword that contains the amAdmin password. Make sure that amadminpassword has read-only permissions for the current user.

Execute the commands in the boxes below one by one in the order shown. At the end of each step, perform the verification for that step shown in the blue boxes before the commands. The verification usually involves logging into OpenAM.

ssoadm update-svc -X C:/apache-tomcat-7.0.0/openam-conf/amWebAgent.xml -u amAdmin -f
amadminpassword ssoadm set-appl -e / -m iPlanetAMWebAgentService -a "actions=GET" "actions=POST" 
"actions=PUT" "actions=DELETE" -u amAdmin -f amadminpassword

Verify: Execute the following command:

ssoadm show-appl -e / -m iPlanetAMWebAgentService -u amAdmin -f amadminpassword

Check that the following actions are listed:

actions=POST=true
actions=GET=true
actions=DELETE=true
actions=PUT=true

ssoadm create-realm -e tolven -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab. The Tolven realm should show up in the Realms list.

ssoadm delete-datastores -e tolven -m embedded -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/tolven realm row/DataStoresTab. There should be no datastores in the list.

ssoadm create-datastore -e tolven -m tolven -t LDAPv3ForOpenDS -D 
C:/apache-tomcat-7.0.0/openam-conf/tolven-datastore-attributes.txt 
-u amAdmin -f amadminpassword

Verify:

Navigate in OpenAM to AccessControlTab/tolven realm row/DataStoresTab. There should now only be the tolven datastore in the list.

Navigate in OpenAM to AccessControlTab/tolven realm row/SubjectsTab. There should be the default user Manager in the User list

Navigate in OpenAM to AccessControlTab/tolven realm row/SubjectsTab/Manager row/GroupTab. Administrator should be in the Selected list.

ssoadm create-identity -e / -i agentadmingroup -t Group -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/SubjectsTab/GroupTab. The agentadmingroup should be in the list.

ssoadm add-privileges -e / -i agentadmingroup -t Group -g AgentAdmin -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/PrivilegesTab/agentadmingroup row. Only Read and write access to all configured Agents should be selected.

ssoadm create-identity -e / -i agentadmin -t User 
-a "givenname=agentadmin" "cn=agentadmin" "sn=agentadmin"
"userpassword=sysadmin" -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/SubjectsTab. agentadmin should be in the User list.

ssoadm add-member -e / -m agentadmin -y User -i agentadmingroup -t Group -u 
amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/SubjectsTab/agentadminrow/GroupTab. agentadmingroup should be in the Selected list.

ssoadm delete-identities -e / -i anonymous -t User -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm >row/SubjectsTab. anonymous should not be in the User list.

ssoadm delete-identities -e / -i demo -t User -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/SubjectsTab. demo should not be in the User list.

ssoadm create-policies -e / -X C:/apache-tomcat-7.0.0/openam-conf/tolven-referrals.xml 
-u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/PoliciesTab. tolvenreferral should be in the Policies list.

ssoadm create-policies -e tolven -X C:/apache-tomcat-7.0.0/openam-conf/tolven-policies.xml
-u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/tolven realm row/PoliciesTab. tolvenapi.admin.policy, tolvenweb.api.policy, tovlenweb.policy, tolvenweb.api.vestibule.policy, and tolvenweb.vestibule.policy should be in the Policies list. Click a policy, and then click any rule. Without making any changes, ensure that there are four action options available: DELETE, GET, POST and PUT.

ssoadm set-attr-defs -s iPlanetAMSessionService -t Global -D 
C:/apache-tomcat-7.0.0/openam-conf/tolven-global-attributes.txt 
-u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to ConfigurationTab/GlobalTab/Session row. The properties in tolven-global-attributes.txt should be in the Notification Properties list.

ssoadm set-attr-defs -s iPlanetAMAdminConsoleService -t Organization -a 
"iplanet-am-admin-console-password-reset-enabled=true" -u amAdmin 
-f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/SubjectsTab/amAdmin row/Edit link. The Old Password field should be enabled.

ssoadm set-svc-attrs -e tolven -s iPlanetAMAuthService -a 
iplanet-am-auth-post-login-process-class=org.tolven.identity.authentication.spi.
TolvenAMPostAuthProcess -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/tolven realm row/AuthenticationTab/All Core Settings.... tolven.identity.authentication.spi.TolvenAMPostAuthProcess should be in the Authentication Post Processing Classes list.

If there is a problem, you may need to look at the log file in the /log folder.

Update OpenAM's internal OpenDS SelfWriteAttributes

OpenAM allows users to change their password, which if they have a userPKCS12 keystore, must then result in the keystore password being updated. Note that this time you are using OpenAM's internal OpenDS port (DIRECTORY_PORT), manager (DS_DIRMGRDN) and password (DS_DIRMGRPASSWD), which was defined in Setup OpenAM Configurator Tool:

Windows

cd c:\OpenDS-2.3.0

bat\ldapmodify -h localhost -p 50389 -D "cn=Directory Manager" -w secret -X --filename c:/OpenDS-2.3.0/tolven-delegation.ldif

Verify: Execute the following command and ensure that the result contains both userCertificate and userPKCS12:

bat\ldapsearch --hostname localhost --port 50389 -D "cn=Directory Manager" --baseDN "ou=services,dc=opensso,dc=tolven,dc=org" "&(ou=SelfWriteAttributes)(sunserviceID=indexes)" sunKeyValue

Linux

cd /usr/local/OpenDS-2.3.0

bin/ldapmodify -h localhost -p 50389 -D "cn=Directory Manager" -w secret -X --filename /usr/local/OpenDS-2.3.0/tolven-delegation.ldif

Verify: Execute the following command and ensure that the result contains both userCertificate and userPKCS12:

bin/ldapsearch --hostname localhost --port 50389 -D "cn=Directory Manager" --baseDN "ou=services,dc=opensso,dc=tolven,dc=org" "&(ou=SelfWriteAttributes)(sunserviceID=indexes)" sunKeyValue

Adding More Users

In the above process, you added a few key users. After the full system is installed and operational, you will have the following options available for creating users and/or groups:

• User and/or role can be added to LDAP via LDIF import
• User and/or role can be added to LDAP via JXplorer GUI or the OpenDS control panel GUI
• User and/or role can be added to OpenAM via the OpenAM console, which leads to entries in LDAP
• User and/or role can be added to OpenAM via the ssoadm command line
• User and/or role can be added via RESTful API calls to OpenAM
• User and/or role can be added via RESTful API calls to Tolven
• User and/or role can be added by an admin GUI in Tolven

Note: Tolven user creation is only useful for creating users in a single LDAP, even if you have a SSO configuration with multiple LDAP servers.

Step 8 - Set Up Your Application Server

8.1 Install Application Server Containers

Install either Glassfish or a Tolven JBoss application server containers:

8.1.1 Install Tolven JBoss V6

Install Tolven JBoss V6

8.1.2 Install Glassfish

Before installing Glassfish, be sure that you have downloaded Glassfish and set up security credentials. See Step 4 - Set Up Your Security Environment for detailed instructions. These steps are necessary or Tolven will not function.

8.1.2.1 Install Kit or Unzip

For this example, we will assume that Glassfish is installed into a folder named tolven-glassfish3. If you expanded the zip file to glassfishv3 then rename it to tolven-glassfish3

8.1.2.2 Rename the Default Domain

Rename the folder tolven-glassfish3/glassfish/domains/domain1 to tolven-glassfish3/glassfish/domains/tolven. This will provide a reasonable starting point for configuring Glassfish for use by Tolven.

8.1.2.3 Set Up a Persistent Master Password

If you are doing a re-install, before doing this step, you should delete any previous password setup in the user's directory. On Windows, this will be:

C:\Documents and Settings\<username>\.asadminpass

Then, whether this is a new install or a reinstall, execute the Glassfish command below to set the master password to "tolven" to avoid your having to reinstall because the password is forgotten.

Windows

tolven-glassfish3\bin\asadmin change-master-password --savemasterpassword=true tolven

Unix

tolven-glassfish3/bin/asadmin change-master-password --savemasterpassword=true tolven

Although saving the password to a file is not recommended for production, if you don't save one now, you will have to enter it for all commands during installation and configuration or create a password file and add that as an argument to all commands. See the Glassfish Admin Guide). At the end of the whole process, you can always change the password, and then set the option to false.

8.1.2.4 Install Credentials

You will be replacing the credentials found in tolven-glassfish/glassfish/domains/tolven/config. Copy the following credential files:

tolven-config/credentials/<this domain name>/keystore.jks
tolven-config/credentials/<this domain name>/cacerts.jks
tolven-config/credentials/mdbuser/tolvendev-mdbuser.p12

To the directory:

tolven-glassfish3/glassfish/domains/tolven/config

8.1.2.5 Install JDBC Driver

Copy your downloaded JDBC driver to tolven-glassfish3/glassfish/domains/tolven/lib.

8.1.2.6 Add Tolven Customization

Unzip the contents of one of the following zip files files to tolven-glassfish3. These zip files were contained in the org.tolven.glassfish.oracle.config-2.0.1.zip or the org.tolven.glassfish.postgresql.config-2.0.1.zip zip files that you downloaded earlier. Notice the corresponding file hierarchies.

• pre-tolven-glassfish3-postgresql.zip
• pre-tolven-glassfish3-oracle.zip

8.1.3 Configure Glassfish

During the configuration of Glassfish and when complete there should be no errors in either of the following logs:

• tolven-glassfish3/glassfish/domains/tolven/logs/server.log
• tolven-glassfish3/glassfish/domains/tolven/imq/instances/imqbroker/log/log.txt

Execute the Glassfish configuration commands, after first checking that the database hostnames and ports match the default values or that you specified earlier for the various servers.

8.1.3.1 Start the Application Server

asadmin start-domain tolven

8.1.3.2 Configure General Settings

Linux: Escape the single backslash file\: as follows: file\\:.

asadmin set server-config.iiop-service.iiop-listener.orb-listener-1.enabled=false
asadmin set server-config.iiop-service.iiop-listener.SSL.enabled=false
asadmin set server-config.iiop-service.iiop-listener.SSL_MUTUALAUTH.enabled=false
asadmin set server-config.iiop-service.iiop-listener.SSL.ssl.cert-nickname=tolven
asadmin set server-config.iiop-service.iiop-listener.SSL_MUTUALAUTH.ssl.cert-nickname=tolven
asadmin set server-config.network-config.network-listeners.network-listener.http-listener-1.port=8080
asadmin set server-config.network-config.network-listeners.network-listener.http-listener-2.port=8443
asadmin set server-config.network-config.protocols.protocol.http-listener-2.ssl.ssl3-enabled=true
asadmin set server-config.network-config.protocols.protocol.http-listener-2.ssl.cert-nickname=tolven
asadmin set property.administrative.domain.name.value=tolven
asadmin --echo delete-jvm-options -client
asadmin --echo create-jvm-options -Djava.awt.headless=true
asadmin --echo delete-jvm-options -XX\:MaxPermSize=192m
asadmin --echo create-jvm-options -server
asadmin --echo create-jvm-options -Xms512m
asadmin --echo delete-jvm-options -Xmx512m
asadmin --echo create-jvm-options -Xmx1024m
asadmin --echo create-jvm-options -XX\:PermSize=256m
asadmin --echo create-jvm-options -XX\:MaxPermSize=512m
asadmin --echo create-jvm-options -XX\:+UseConcMarkSweepGC
asadmin --echo create-jvm-options -XX\:+CMSClassUnloadingEnabled
asadmin --echo create-jvm-options -Dsun.rmi.dgc.client.gcInterval=3600000
asadmin --echo create-jvm-options -Dsun.rmi.dgc.server.gcInterval=3600000
asadmin --echo create-jvm-options -Dxa-driver-does-not-support-non-tx-operations=true
asadmin --echo create-jvm-options -Dlog4j.configuration=file\:///${com.sun.aas.instanceRoot}/config/log4j.xml
asadmin --echo create-jvm-options -Djava.security.egd=file\:///dev/urandom

8.1.3.3 Configure JDBC Settings

PostgreSQL:

asadmin delete-jdbc-connection-pool --cascade DerbyPool
asadmin list-jdbc-connection-pools
asadmin create-jdbc-connection-pool --datasourceclassname org.postgresql.xa.PGXADataSource --restype 
  javax.sql.XADataSource --description "TolvenDataSource" --property
  serverName=localhost:databaseName=postgres:portNumber=5432:user=postgres:password=postgres TolvenDataSource
asadmin list-jdbc-connection-pools
asadmin ping-connection-pool TolvenDataSource
asadmin create-jdbc-resource --description "TolvenDataSource" --connectionpoolid TolvenDataSource jdbc/__default
asadmin list-jdbc-resources
asadmin delete-jdbc-connection-pool --cascade __TimerPool
asadmin list-jdbc-connection-pools
asadmin create-jdbc-resource --description "Timer" --connectionpoolid TolvenDataSource jdbc/__TimerPool

Oracle:

asadmin delete-jdbc-connection-pool --cascade DerbyPool
asadmin list-jdbc-connection-pools
asadmin create-jdbc-connection-pool --datasourceclassname oracle.jdbc.xa.client.OracleXADataSource 
  --restype javax.sql.XADataSource --description "TolvenDataSource" 
  --property url=jdbc\\:oracle\\:thin\\:@localhost\\:1521\\:ORCL:user=tolven:password=tolven TolvenDataSource
asadmin list-jdbc-connection-pools
asadmin ping-connection-pool TolvenDataSource
asadmin create-jdbc-resource --description "TolvenDataSource" --connectionpoolid TolvenDataSource 
  jdbc/__default
asadmin list-jdbc-resources
asadmin delete-jdbc-connection-pool --cascade __TimerPool
asadmin list-jdbc-connection-pools
asadmin create-jdbc-resource --description "Timer" --connectionpoolid TolvenDataSource jdbc/__TimerPool

8.1.3.4 Configure JMS Settings

asadmin create-jmsdest --desttype queue adminApp
asadmin create-jmsdest --desttype queue generator
asadmin create-jmsdest --desttype queue invitation
asadmin create-jmsdest --desttype queue rule
asadmin list-jmsdest
asadmin create-jms-resource --restype javax.jms.Queue --property Name=adminApp queue/adminApp
asadmin create-jms-resource --restype javax.jms.Queue --property Name=generator queue/generator
asadmin create-jms-resource --restype javax.jms.Queue --property Name=invitation queue/invitation
asadmin create-jms-resource --restype javax.jms.Queue --property Name=rule queue/rule
asadmin list-jms-resources

8.1.3.5 Stop the Application Server

asadmin.bat stop-domain tolven

8.1.4 Install Policy Agent

Before completing this step, you must have already downloaded the Policy Agent and configured the application software. See step 2.5 Download OpenAM Software and step 8.1.3 Configure Glassfish.

8.1.4.1 Unzip Software

Unzip the contents of the downloaded appserver_v10_agent_3.zip file into tolven-glassfish3/glassfish directory.

8.1.4.2 Secure Policy Agent

The policy agent does not talk securely to the OpenAM server by default. In order to allow this, you need to add the JSSE keystore paths to the j2ee_agents/appserver_v10_agent/bin/agentadmin(.bat) file as options to java which launches the agent:

-Djavax.net.ssl.keyStore=c:/tolven-config/credentials/dev.able.com/keystore.jks 
-Djavax.net.ssl.keyStorePassword=tolven 
-Djavax.net.ssl.trustStore=c:/tolven-config/credentials/dev.able.com/cacerts.jks 
-Djavax.net.ssl.trustStorePassword=tolven

8.1.5 Configure Policy Agent

Note: Before configuring the policy agent, make sure that the Glassfish application server that the agent is protecting is stopped, and that the OpenAM server is running.

There is supposed to be a scripted way to execute this code, but it does not work well in the current version. Therefore, use the interactive steps shown below. This also allows you to keep an eye on the parameters. Below are typical answers to these questions.

Execute the following command in the directory tolven-glassfish3\glassfish\j2ee_agents\appserver_v10_agent\bin:

agentadmin --custom-install

You will need to agree to licensing as your first two inputs. Do you completely agree with all the terms and conditions of this License
Agreement (yes/no): [no]:

yes

Enter the complete path to the directory which is used by Application Server to store its configuration Files. This directory uniquely identifies the Application Server instance that is secured by this Agent:

C:/tolven-glassfish3/glassfish/domains/tolven/config

Enter the name of the Application Server instance

Hit enter to accept the default called server.

Enter the URL where the OpenSSO server is running. Please include the deployment URI and use your own domain. Note that if this server will be running on the same box as Glassfish, then you need to use a port other than 8443 (8444 is shown below as an example):

https://dev.able.com:8444/openam

Enable this field only when the agent is being installed on a remote server instance host:

false

The location of agent in the Glassfish server (use your own domain, and Glassfish is set up by default to use 8443):

https://dev.able.com:8443/agentapp

Enter a valid Encryption Key:

Hit enter to accept the default.

Enter the Agent profile name, which will be created in the OpenAM server:

TolvenRESTfulAgent

Create the file agentpassword.txt containing a password for TolvenRESTfulAgent (default: sysadmin). Enter the path to this file here:

C:/tolven-glassfish3/glassfish/j2ee_agents/agentpassword.txt

WARNING:
Agent profile/User: TolvenRESTfulAgent does not exist in OpenSSO server!
Either "Hit the Back button, and re-enter the correct agent profile
name/user name", or "Create this agent profile when asked (available only in
custom-install)", or "Continue without validating it because agent
profile is in sub realm", or "Continue without validating/creating it, and
manually validate/create it in OpenSSO server after installation".

Enter true if the Agent Profile is being created into OpenSSO server by the
installer. Enter false if it will be not be created by installer

This Agent Profile does not exist in OpenSSO server, will it be created by the
installer? (Agent Administrator's name and password are required) [true]:

true

Troubleshooting: If you see the following warning instead:

WARNING: Password validation cannot be done as OpenSSO server is not running

openAM is not running and it should be started. Exit this configuration utility, start OpenAM, and return to the beginning of this section.

Troubleshooting: If you see the following warning instead:

Enter true only if agent is being installed on a remote instance from the
Domain Administration server host.
[ ? : Help, < : Back, ! : Exit ]
Is the agent being installed on the DAS host for a remote instance ? false:

You may have already configured the TolvenRESTfulAgent in OpenAM. While you could continue past this point, we recommend that you exit this script; log in to OpenAM (user amAdmin, password: sysadmin); navigate to Access Control > Top Level Realm > Agents > J2EE select TolvenRESTfulAgent:; and click Delete. Then return to the beginning of this section.

The Agent Administrator is the user, which has permissions to create TolvenRESTfulAgent. This user was created during the OpenAM configuration, and was given the necessary permissions:

agentadmin

The path to a file which contains the password to the agentadmin which was setup in OpenAM by the ssoadm commands (default is sysadmin):

C:/tolven-glassfish3/glassfish/j2ee_agents/agentpassword.txt

Enter true only if agent is being installed on a remote instance from the Domain Administration server host. Is the agent being installed on the DAS host for a remote instance ? [false]:

false

Verify your settings above and decide from the choices below.
1. Continue with Installation
2. Back to the last interaction
3. Start Over
4. Exit
Please make your selection [1]:

1

If there are no errors, then you should be able to log into the OpenAM console as amAdmin, select the top realm. From there select the Agents/J2EE tabs, and TolvenRESTfulAgent should be listed there.

8.1.6 Update Agent In OpenAM

Now that the agent has been created in OpenAM as TolvenRESTfulAgent, there is one more step to configure it using ssoadm.

Return to the OpenAM bin directory that was created in Step 6.6.8: ssoAdminTool/openam/bin.

From there execute the following command:

ssoadm update-agent -e / -b TolvenRESTfulAgent -D C:/apache-tomcat-7.0.0/openam-conf/tolven-agent-attributes.txt 
  -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/AgentsTab/J2EETab/TolvenRESTfulAgent row/ApplicationTab. The attributes in
tolven-agent-attributes.txt should be in the Profile Attribute Mapping list.

8.1.7 Remove agentadmin User From OpenAM

Now that the agent has been created in OpenAM there is no immediate need for the agentadmin user which created it, so use the following command to remove the user as a security precaution.

ssoadm delete-identities -e / -i agentadmin -t User -u amAdmin -f amadminpassword

Verify: Navigate in OpenAM to AccessControlTab/Top Level Realm row/SubjectsTab.
The user agentadmin should no longer be present. It can be added again if and when it is needed.

8.1.8 Start Glassfish

The next step is to deploy the policy agent to the application server. But before you can do that, you must start Glassfish.

asadmin start-domain tolven

8.1.9 Deploy Policy Agent

Deploy the agentapp.war file by copying it from:

tolven-glassfish3/glassfish/j2ee_agents/appserver_v10_agent/etc/agentapp.war

To:

tolven-glassfish3/glassfish/domains/tolven/autodeploy

Check the Glassfish server.log for errors.

8.1.10 Install Tolven Glassfish

8.1.10.1 Stop Glassfish

Ensure that Glassfish is stopped.

asadmin.bat stop-domain tolven

8.1.10.2 Fix Welcome Page

Delete the following file, which is not required. It will be replaced by an index.jsp in the next step:

tolven-glassfish3/glassfish/domains/tolven/docroot/index.html

8.1.10.3 Install Tolven-Specific Components into Glassfish

Unzip one of the following downloaded files to the Glassfish folder tolven-glassfish3. Notice the corresponding file hierarchy in the zip file:

post-tolven-glassfish3-postgresql.zip
post-tolven-glassfish3-oracle.zip

8.1.10.4 Verify JMS Configuration

Ensure that the database hostname and port match that of your database:

tolven-glassfish3/glassfish/domains/tolven/imq/instances/imqbroker/props/config.properties

Step 9 - Configure Tolven

Next, you will be configuring Tolven software. As a result, many of the decisions you make will relate to the specific configuration that you intend to deploy.

The Tolven plugin catalog containing all published V2 plugins can be found at here.

You will be deploying Tolven components that you assembled earlier. Those components can be found in <config-dir>/build/repositoryStage.

Most of the previous steps prepared the environment for Tolven and in most cases, should not need to be repeated again. For example, at this point, the running opensso, OpenDS, and database servers can remain up and running even if you will be updating Tolven (and possibly application server) software.

9.1 Deploy Tolven Glassfish Libraries

The deployment command below will affect the Glassfish server; therefore, stop the Glassfish server before running the deployment command. It also should not contain the tolven.ear file, because it depends on these libraries.

The command below will deploy tolvenCommon.jar, mqKeyStore-api.jar, and tolven-openamclient.jar, providing they have been previously assembled as described in the "Run Phase 1 Coniguration" step.

Change to the Tolven bin directory:

'''cd c:\tolven-V2.0.25\bin'''???

Run the tpfenv command:

Windows:

tpfenv

Linux:

. ./tpfenv.sh

Run the following:

tpf -plugin org.tolven.deploy.glassfish -config

The jars will be deployed to the following directory:

• tolven-glassfish3/glassfish/domains/tolven/lib

Troubleshooting: When running the tpf command, if you are asked for the Config Directory, User ID, Password, and Realm, you should run <tolven-install-dir>\bin\tpfenv and then run tpf again.

9.2 Configure Tolven Glassfish

9.2.1 Start Glassfish

asadmin start-domain tolven

Ensure no errors occurs in any of the logs located in the following directories:

tolven-glassfish3/glassfish/domains/tolven/logs/server.log
tolven-glassfish3/glassfish/domains/tolven/imq/instances/imqbroker/log/log.txt
tolven-glassfish3/glassfish/j2ee_agents/appserver_v10_agent/Agent_001/logs\debug

Check these logs periodically, as the following commands in this section are executed.

9.2.2 Create Resource Adapter

Create a resource adapter for the MQKeyStore.

Linux: Escape the single backslash file\: as follows: file\\:.

asadmin create-resource-adapter-config --property keyStoreURL=file\:///\${com.sun.aas.instanceRoot}/config/
  tolvendev-mdbuser.p12:keyStoreType=PKCS12:keyStorePassword=tolven:defaultAlias=mdbuser --threadpoolid 
  thread-pool-1 mqKeyStore

9.2.3 Deploy the mqKeyStore.rar

Next, you will deploy mqKeyStore.rar.

Note: You must re-assemble MQKeyStore whenever you make changes to the plugins.xml file in the <config-dir>, or when new or updated plugins are downloaded from a catalog. Therefore, if you have made those changes, you must to re-assemble MQKeyStore before you run the tpf command in this step.

tpf -plugin org.tolven.deploy.glassfish -rarPlugins org.tolven.mqkeystore

The above command will deploy the mqKeyStore.rar to the following directory:

tolven-glassfish3/glassfish/domains/tolven/autodeploy

Verify: The server.log should show that the mqKeyStore.rar has been deployed, and in addition a file called mqKeyStore.rar_deployed should appear in the autodeploy directory

9.2.4 Change imqusermgr Password

Change the default imqusermgr password to one of your choice (defaulted here to sysadmin), which Glassfish will use to access the message broker:

tolven-glassfish3/mq/bin/imqusermgr update -f -u admin -p sysadmin

9.2.5 Create JMS Resource

Create a JMS resource which uses the password just chosen above:

asadmin create-jms-resource --restype javax.jms.ConnectionFactory --property UserName=admin:Password=sysadmin jms/JmsXA
asadmin list-jms-resources
asadmin --user admin set server.jms-service.jms-host.default_JMS_host.admin-password=sysadmin

9.2.6 Deploy mqKeyStore.rar

Finally, these commands can only be executed when the mqKeyStore.rar is deployed, which was done in a previous step:

asadmin create-connector-connection-pool --raname mqKeyStore --connectiondefinition org.tolven.connectors.mqkeystore.api.MQKeyStoreConnectionFactory mqKeyStore
asadmin list-connector-connection-pools
asadmin create-connector-resource --poolname mqKeyStore mqKeyStore
asadmin list-jndi-entries

If you un-deploy the mqKeyStore.rar, you will need to use the delete-connector-connection-pool and delete-connector-connection-pool commands, and then repeat the create commands once the RAR is redeployed.

9.3 Deploy Tolven EAR File

The tolven.ear file should only be deployed once Glassfish has started, since it relies on the agent.war file and mqKeyStore.rar files being successfully deployed first. In general those files should deploy faster than tolven.ear, but if they don't you will get errors.

Note: You must re-assemble the Tolven EAR file whenever you make changes to the plugins.xml file in the <config-dir>, or when new or updated plugins are downloaded from a catalog. Therefore, if you have made those changes, you must to re-assemble tolven.ear before you run the tpf command in this step.

tpf -plugin org.tolven.deploy.glassfish -earPlugins org.tolven.component.tolvenear

The above command will deploy tolven.ear to the following directory:

tolven-glassfish3/glassfish/domains/tolven/autodeploy

Check the server.log to ensure that there are no errors.

Verify: The server.log should show that tolven.ear has been deployed, and in addition a file called tolven.ear_deployed should appear in the autodeploy directory, after a minute or two.

9.4 Update Database Indexes

Create the following database indexes using an appropriate database tool, once tolven.ear is deployed, because the deployment process creates the tables referred to below. This step is normally carried out during a first installation, and might only need to be re-run if new indexes are announced in Tolven. This process can take a few minutes to run for a large database.

PostgreSQL:

CREATE INDEX touch_index1
  ON public.touch
  USING btree
  (account_id,updateplaceholder_id);

CREATE INDEX md_index1
  ON app.menu_data
  USING btree
  (menustructure_id);

CREATE INDEX md_index2
  ON app.menu_data
  USING btree
  (menustructure_id, parent01_id);

CREATE INDEX md_index3
  ON app.menu_data
  USING btree
  (trimheader_id);
  
CREATE INDEX md_index4
  ON app.menu_data
  USING btree
  (account_id, document_id);

CREATE INDEX md_index5
  ON app.menu_data
  USING btree
  (account_id, menu_path);

CREATE INDEX md_index6 
  ON app.menu_data 
  USING btree
  (account_id, reference_id);


CREATE UNIQUE INDEX mdv_index1
  ON app.menu_data_version
  USING btree
  (account_id, element);

CREATE INDEX mdw_index1
  ON app.menu_data_word
  USING btree
  (menudata_id);

CREATE INDEX mdw_index2
  ON app.menu_data_word
  USING btree
  (menustructure_id, word, menudata_id);
    
CREATE UNIQUE INDEX ph_index2
  ON app.placeholder_id
  USING btree
  (account_id, menustrucuture_id, id_root, id_extension);

CREATE INDEX ms_index1
  ON app.menu_structure
  USING btree
  (account_id, path_name);
  
CREATE INDEX mcol_index1
  ON app.ms_column
  USING btree
  (menustructure_id, account_id);

CREATE INDEX ums_index1
  ON app.user_menu_structure
  USING btree
  (accountuser_id, underlyingms_id);

CREATE INDEX au_index1
  ON core.account_user
  USING btree
  (user_id);

CREATE INDEX user_index1
  ON core.tolven_user
  USING btree
  (uid, status, id);

CREATE INDEX doc_index1
  ON doc.document
  USING btree
  (account_id, xml_name);

CREATE INDEX th_index1
  ON app.trim_header
  USING btree
  (name,status);

CREATE INDEX th_index2
  ON app.trim_header
  USING btree
  (status, id);
  
CLUSTER md_index1 ON app.menu_data;

Oracle:

CREATE INDEX tolven.md_index1 ON tolven.menudata (menustructure_id);
CREATE INDEX tolven.md_index2 ON tolven.menudata (menustructure_id, parent01_id);
CREATE INDEX tolven.md_index3 ON tolven.menudata (trimheader_id);
CREATE INDEX tolven.md_index4 ON tolven.menudata (account_id, documentid);
CREATE INDEX tolven.md_index5 ON tolven.menudata (account_id, path);
CREATE INDEX tolven.md_index6 ON tolven.menudata (account_id, reference_id);
CREATE UNIQUE INDEX tolven.mdv_index1 ON tolven.menudataversion (account_id, element);
CREATE INDEX tolven.mdw_index1 ON tolven.menudataword (menudata_id);
CREATE INDEX tolven.mdw_index2 ON tolven.menudataword (menustructure_id, word, menudata_id);
CREATE UNIQUE INDEX tolven.ph_index2 ON tolven.placeholderid (account_id, menustrucuture_id, root, extension);
CREATE INDEX tolven.ms_index1 ON tolven.accountmenustructure (account_id, path);
CREATE INDEX tolven.mcol_index1 ON tolven.mscolumn (menustructure_id, account_id);
CREATE INDEX tolven.ums_index1 ON tolven.usermenustructure (accountuser_id, underlyingms_id);
CREATE INDEX tolven.au_index1 ON tolven.accountuser (user_id);
CREATE INDEX tolven.user_index1 ON tolven.tolvenuser (ldapuid, status, id);
CREATE INDEX tolven.doc_index1 ON tolven.docbase (account_id, xmlname);
CREATE INDEX tolven.th_index1 ON tolven.trimheader (name,status);
CREATE INDEX tolven.th_index2 ON tolven.trimheader (status, id);

9.5 Update Server Properties

The next step is to configure the Tolven runtime server properties. An initial set of properties will be created which you can deploy to the database. Thereafter, you can change these properties when needed, even while the application server is running. The properties are managed by the following entry in the tolven-config/plugins.xml file:

<plugin id="org.tolven.appserverproperties">
	<root />
	<property name="appserver.default.propertiesFile" value="server-default-config.properties.xml" />
</plugin>

The filename value of the appserver.default.propertiesFile, is by default a relative path to the file within the plugin itself. These default properties are currently a part of the plugin. If you wish to edit these properties, then place all of those properties in your own file, and use an absolute path to that file. For example:

Windows:

<property name="appserver.default.propertiesFile" value="c:/tolven-config/server-default-config.properties.xml" />

Please note the forward slashes for the path which appears in the plugins.xml.

Linux:

<property name="appserver.default.propertiesFile" value="/usr/local/tolven-config/server-default-config.properties.xml" />

You can use the example file provided in the <config-dir> or unzip the one in the plugin itself, and then place that externally wherever you choose, and then edit it. If you already have properties in the database from a previous installation, then there is no need to run this command, otherwise:

tpf -plugin org.tolven.appserverproperties -load

9.5.1 (Optional) Disable Use of User Security Certificates

In normal operations, Tolven uses user security certificates to encrypt data at rest within the database. In a development environment, encryption keys are not essential, so you can use org.tolven.appserverproperties property to disable the use of security certificates and keystores.

When this property is set to false (default), Accounts cannot be created by users who do not have a user certificate and user PCKCS12 keystore in LDAP. To avoid having to deal with the additional steps of creating certificates and keystores at this stage, you can make the keys optional, which is helpful while becoming accustomed to Tolven in non-production environments. Account documents will still be encrypted, but the AccountPrivateKey will be stored in the database unencrypted.

In a Tolven development environment, execute the following to disable the enforced use of user security certificates and keystores:

tpf -plugin org.tolven.appserverproperties -set tolven.security.user.keysOptional true

In a Tolven production environment, we recommend that the certificates and keystores should not be optional, and thus all AccountPrivateKeys will be encrypted, as well as the documents they were involved in encrypting. Execute the following to return to using the security certificates and keystores:

tpf -plugin org.tolven.appserverproperties -set tolven.security.user.keysOptional false

9.6 Create a Tolven User

9.6.1 Add User

If you have not done so already, create a Tolven user. There are several ways to do this. But in this case, the example will show how to create a user using OpenAM.

1. Connect to OpenAM such as https://localhost:8444/openam and login as AmAdmin.
2. Under the Access Control tab, click the tolven realm.
3. Click the Subjects tab.
4. Click New.

Enter data for the following fields and Click OK when done:

Field	Description
ID	This field takes the identifier of the user purposes of logging into the OpenSSO Enterprise console. This property does not have to be a DN.
First Name	The first name of the user.
Last Name	The last name of the user.
Full Name	The full name of the user.
Password	The password for the user.
Password (Confirm)	Confirm the password.
User Status	This option indicates whether the user is allowed to authenticate through OpenSSO Enterprise.

9.6.2 Add Role

1. Click on that user.
2. Select the Group tab.
3. Add tolvenSSO to your user.
4. Save.

9.7 Add Application Metadata to plugins.xml

Tolven requires metadata that defines the basic application behavior. You upload metadata, in the form of plugins, to the database where it is used at runtime.

In order for these plugins to be available to your repositoryRuntime, you need to first add the following snippets to your <tolven-config>/plugins.xml file in order to make them root plugins.

Below are prototypes (examples) that Tolven updates regularly on the download site. Add the following to <tolven-config>/plugins.xml:

<plugin id="org.tolven.prototype.applications">
	<root />
</plugin>
<plugin id="org.tolven.prototype.application.trim">
	<root />
</plugin>

The plugins below are automatically downloaded to your <config-dir>/repositoryRuntime/plugins directory the next time you execute repositoryInit, and as newer versions appear, they too will be downloaded.

9.8 Add Vocabularies to plugins.xml

Applications need standard vocabulary. Tolven provides several vocabularies in the form of plugins that you include by pasting some or all of the following into plugins.xml.

<plugin id="org.tolven.deploy.allergies">
	<root />
</plugin>
<plugin id="org.tolven.deploy.breastproblems">
	<root />
</plugin>
<plugin id="org.tolven.deploy.diagnoses">
	<root />
</plugin>
<plugin id="org.tolven.deploy.immunization">
	<root />
</plugin>
<plugin id="org.tolven.deploy.problems">
	<root />
</plugin>
<plugin id="org.tolven.deploy.procedures">
	<root />
</plugin>
<plugin id="org.tolven.deploy.rxnorm">
	<root />
</plugin>

9.9 Run repositoryInit

To download the above plugins to your repositoryRuntime, execute repositoryInit.

Windows:

cd <install-difr>\bin
repositoryInit

Linux:

cd <install-dir>/bin
./repositoryInit.sh

9.10 Run Phase 3 Configuration

This command will activate those plugins that have account types, rules, trims, vocab, etc. to upload to the database via the application server. In other words, it uploads the Tolven application configuration.

This is likely to be the most commonly repeated configuration command once the installation and configuration process has been completed. You will rarely if ever make direct database changes sanctioned by Tolven. The SSO and LDAP software should rarely need updating. However, you may be changing the SSO configuration to meet specific security requirements. If you make changes that affect the ear or war files, then you will need to run configPhase1.

Note: When configPhase3 runs, it only updates a "prototype account" for each account type. Therefore, no user-accessible accounts are updated at this time. As users log into each account, the changes are propagated to that account. For example, if you have a total of four accounts on the system, then a user must log into each of those four accounts for the changes to propagate to each account on the system. If a user happens to be logged in at the time configPhase3 runs and is the account administrator for that account, that user can initiate propagation using the Update Metadata option under Preferences.

The application server must be running before executing the following command

Windows:

configPhase3

Linux:

./configPhase3.sh

Verify: Navigate to the Tolven Web application (https://localhost:8444/openam/UI/Login?realm=tolven&goto=https%3A%2F%2Flocalhost%3A8443%2FTolven%2F).
After logging in, verify that the Select Account page displays. If you have not loaded any applications, there will be no choices available and you will not be able to go any further. This is normal. If you have configured a custom vestibule, then the initial page following login may be different.

9.10 Activate Vocabulary Plugins

The vocabulary plugins are not automatically activated during configPhase3, and so have their own commands. You may be prompted for userId, password and <config-dir> unless you have taken the appropriate configuration steps given earlier in the configuration process, so these commands must be executed individually. If your userId, password and <config-dir> are set up you can simply execute them all, and they will simply execute sequentially:

Windows:

tpf -plugin org.tolven.deploy.allergies
tpf -plugin org.tolven.deploy.breastproblems
tpf -plugin org.tolven.deploy.diagnoses
tpf -plugin org.tolven.deploy.immunization
tpf -plugin org.tolven.deploy.problems
tpf -plugin org.tolven.deploy.procedures
tpf -plugin org.tolven.deploy.rxnorm

Linux:

./tpf.sh -plugin org.tolven.deploy.allergies
./tpf.sh -plugin org.tolven.deploy.breastproblems
./tpf.sh -plugin org.tolven.deploy.diagnoses
./tpf.sh -plugin org.tolven.deploy.immunization
./tpf.sh -plugin org.tolven.deploy.problems
./tpf.sh -plugin org.tolven.deploy.procedures
./tpf.sh -plugin org.tolven.deploy.rxnorm

Step 10 - Next Steps

Your installation and initial configuration of Tolven and dependent products is complete. As a developer, you will most likely want to proceed to the Developer's Guide where you will learn how to create new Tolven functionality and add it to the configuration.

From this point on, you will be making iterative changes to the application configuration and running configPhase1 or configPhase3 as needed. Likewise, if Tolven adds new functionality such as the synchronous submit feature or makes bug fixes, you will only need to do:

1. tpfenv
2. repositoryInit
3. configPhase1 or configPhase3

There is no need to repeat any of the installation steps.