Install IG in Apache Tomcat

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.

Downloading and Starting IG in Tomcat

The commands in this guide assume that you install Tomcat to /path/to/tomcat, and after installation, you have a directory /path/to/tomcat/webapps in which you install IG. If you use another directory structure, substitute the commands.

  1. Download a supported version of Tomcat server from its download page, and install it to /path/to/tomcat.

  2. Remove the ROOT directory in Tomcat:

    $ rm -rf /path/to/tomcat/webapps/ROOT
  3. Download IG-7.1.0.war from the ForgeRock BackStage download site.

  4. Copy the IG-7.1.0.war to the Tomcat webapps directory, as ROOT.war:

    $ cp IG-7.1.0.war /path/to/tomcat/webapps/ROOT.war

    Tomcat automatically deploys IG in the root context on startup.

  5. Start Tomcat:

    $ /path/to/tomcat/bin/startup.sh

    If necessary, make the startup scripts executable.

  6. Check that IG is running in one of the following ways:

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 domain property 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.

Configure 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 Configure 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"

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.

Configure 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:

  1. Download the MySQL JDBC Driver Connector/J from http://dev.mysql.com/downloads/connector/j.

  2. Copy the driver .jar to /path/to/tomcat/lib/ so that it is on Tomcat’s class path.

  3. 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"
    />
  4. 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>
  5. Restart Tomcat to read the configuration changes.

About 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 jvmRoute attribute 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.