Installing IG in Apache Tomcat
For basic information about how to install IG in Tomcat, see "Downloading and Starting IG in Tomcat". The following sections describe other installation options:
About Using Tomcat
Important
If you use startup scripts to bootstrap the IG web container, the scripts can start the container process with a different user. To prevent errors, make sure that the location of the IG configuration is correct. Alternatively, adapt the startup scripts to specify the IG_INSTANCE_DIR env variable or ig.instance.dir system properties, taking care to set file permissions correctly.
If you start and stop the IG web container yourself, the default location of the IG configuration files is correct. By default, IG configuration files are located under $HOME/.openig on Linux, Mac, and UNIX systems, and under %appdata%\OpenIG on Windows.
Configure Tomcat to use the same protocol as the application you are protecting with IG. If the protected application is on a remote system, configure Tomcat to use the same port as well. If your application listens on both an HTTP and an HTTPS port, then you must configure Tomcat to do so, too.
To configure Tomcat to use an HTTP port other than 8080, modify the defaults in /path/to/tomcat/conf/server.xml. Search for the default value of 8080 and replace it with the new port number.
Configuring Cookie Domains in Tomcat
To protect multiple applications running on different hosts, set a cookie domain as follows:
For stateful sessions, add a context element to
/path/to/conf/Catalina/server/root.xml, as in the following example, and then restart Tomcat to read the configuration changes:<Context sessionCookieDomain=".example.com" />
If JwtSession is not configured, stateful sessions are created automatically. For more information, see "Sessions".
For stateless sessions, configure the
domainproperty of JwtSession. When set, the JWT cookie can be accessed from different hosts in that domain. When not set, the JWT cookie can be accessed only from the host where the cookie was created. For information, see "JwtSession".
Configuring IG for HTTPS (Server-Side) in Tomcat
This section describes how to set up IG to run as a server over HTTPS. For information about the set up for HTTPS (client-side), see "Configuring IG For HTTPS (Client-Side)".
To get Tomcat up quickly on an SSL port, add an entry similar to the following in /path/to/tomcat/conf/server.xml:
<Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true">
<SSLHostConfig sslProtocol="TLS" protocols="all" certificateVerification="none">
<Certificate certificateKeystoreFile="/path/to/tomcat/conf/keystore"
certificateKeystorePassword="password"
certificateKeystoreType="PKCS12" />
</SSLHostConfig>
</Connector>
Also create a keystore holding a self-signed certificate:
$ keytool \
-genkey \
-alias tomcat \
-keyalg RSA \
-keystore /path/to/tomcat/conf/keystore \
-storetype PKCS12 \
-storepass password \
-keypass password \
-dname "CN=openig.example.com,O=Example Corp,C=FR"Note
Because KeyStore converts all characters in its key aliases to lower case, use only lowercase in alias definitions of a KeyStore.
Notice the keystore file location and the keystore password both match the configuration. By default, Tomcat looks for a certificate with alias tomcat.
Restart Tomcat to read the configuration changes.
Browsers generally do not trust self-signed certificates. To work with a certificate signed instead by a trusted CA, see the Tomcat documentation on configuring HTTPS.
Configuring Access to MySQL Over JNDI in Tomcat
If IG accesses an SQL database, then you must configure Tomcat to access the database using Java Naming and Directory Interface (JNDI). To do so, you must add the driver .jar for the database, set up a JNDI data source, and set up a reference to that data source.
The following steps are for MySQL Connector/J:
Download the MySQL JDBC Driver Connector/J from http://dev.mysql.com/downloads/connector/j.
Copy the driver .jar to
/path/to/tomcat/lib/so that it is on Tomcat's class path.Add a JNDI data source for your MySQL server and database in
/path/to/tomcat/conf/context.xml:<Resource name="jdbc/forgerock" auth="Container" type="javax.sql.DataSource" maxActive="100" maxIdle="30" maxWait="10000" username="mysqladmin" password="password" driverClassName="com.mysql.jdbc.Driver" url="jdbc:mysql://localhost:3306/databasename" />
Add a resource reference to the data source in
/path/to/tomcat/conf/web.xml:<resource-ref> <description>MySQL Connection</description> <res-ref-name>jdbc/forgerock</res-ref-name> <res-type>javax.sql.DataSource</res-type> <res-auth>Container</res-auth> </resource-ref>Restart Tomcat to read the configuration changes.
Session Stickiness and Session Replication for Tomcat
Tomcat can help with session stickiness, and a Tomcat cluster can handle session replication:
If you choose to use the Tomcat connector (mod_jk) on your web server to perform load balancing, then see the LoadBalancer HowTo for details.
In the HowTo, you configure the
jvmRouteattribute in the Tomcat server configuration,/path/to/tomcat/conf/server.xml, to identify the server. The connector can use this identifier to achieve session stickiness.A Tomcat cluster configuration can handle session replication. When setting up a cluster configuration, the ClusterManager defines the session replication implementation.