Install IG in Apache Tomcat (deprecated)

The delivery of a .war file was deprecated in IG 7. Consider installing IG from a .zip file, as described in Install IG. For more information, refer to Migrate from web container mode to standalone mode.

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

Download and start 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.

Download a supported version of Tomcat server from its download page, and install it to /path/to/tomcat.
Remove the ROOT directory in Tomcat:
```
$ rm -rf /path/to/tomcat/webapps/ROOT
```
Download IG-2023.6.0.war from the ForgeRock BackStage download site.
Copy the IG-2023.6.0.war to the Tomcat webapps directory, as ROOT.war:
```
$ cp IG-2023.6.0.war /path/to/tomcat/webapps/ROOT.war
```
Tomcat automatically deploys IG in the root context on startup.
Start Tomcat:
```
$ /path/to/tomcat/bin/startup.sh
```
If necessary, make the startup scripts executable.
Check that IG is running in one of the following ways:
- Ping IG at http://ig.example.com:8080/openig/ping, and make sure an HTTP 200 is returned.
- Access the IG welcome page at http://ig.example.com:8080.
- When IG is running in development mode, display the product version and build information at http://ig.example.com:8080/openig/api/info.

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, refer to 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, refer to 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), refer to Configure IG For HTTPS (client-side).

Browsers generally do not trust self-signed certificates. To work with a certificate signed instead by a trusted CA, refer to the Tomcat documentation on configuring HTTPS.

Create a keystore holding a self-signed certificate:
1. Locate a directory for secrets, and go to it:
  $ cd /path/to/secrets
2. Create a keystore:
  $ keytool \ -genkey \ -alias tomcat \ -keyalg RSA \ -keystore keystore \ -storetype PKCS12 \ -storepass password \ -keypass password \ -dname "CN=ig.example.com,O=Example Corp,C=FR"
  Because keytool converts all characters in its key aliases to lowercase, 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.

Add an entry similar to the following in /path/to/tomcat/conf/server.xml, replacing /path/to/tomcat/conf/keystore with the path to your keystore:

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

Restart Tomcat.

Configure SameSite for HTTP session cookies in Tomcat

Change the cookie processor element in /path/to/tomcat/webapps/manager/META-INF/context.xml, to one of the following values:
- none: The browser always sends cookies in cross-site requests
- lax: The browser sends cookies only in same-site requests and cross-site top-level GET requests
- strict: The browser never sends cookies in cross-site requests
  
  For example, the following line sets the value to none:
  <CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor" sameSiteCookies="none" />
  When you access Tomcat through HTTPS, the secure flag is automatically set on the cookie.
Restart Tomcat.

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:

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.

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 refer to the Load Balancing 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.

SAML in deployments with multiple instances of IG

IG uses the federation libraries from AM (also referred to as the Fedlet) to implement SAML. When IG acts as a SAML service provider, the session information is stored in the fedlet, not the session cookie. In deployments that use multiple instances of IG as a SAML service provider, it is therefore necessary to set up sticky sessions so that requests always hit the instance where the SAML interaction was started.

For information, refer to Session state considerations in AM’s SAML v2.0 guide.

IG 2023.6