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
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
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
/path/to/tomcat/conf/server.xml. Search for the default value of
8080 and replace it with the new port number.
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
ROOTdirectory in Tomcat:
$ rm -rf /path/to/tomcat/webapps/ROOT
IG-2023.9.0.warfrom the ForgeRock BackStage download site.
IG-2023.9.0.warto the Tomcat
$ cp IG-2023.9.0.war /path/to/tomcat/webapps/ROOT.war
Tomcat automatically deploys IG in the root context on startup.
If necessary, make the startup scripts executable.
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, refer to 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, refer to JwtSession.
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:
Locate a directory for secrets, and go to it:
$ cd /path/to/secrets
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
Add an entry similar to the following in
/path/to/tomcat/conf/keystorewith 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>
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
<CookieProcessor className="org.apache.tomcat.util.http.Rfc6265CookieProcessor" sameSiteCookies="none" />
When you access Tomcat through HTTPS, the
secureflag is automatically set on the cookie.
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
<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
<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.
Tomcat can help with session stickiness, and a Tomcat cluster can handle session replication:
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.
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.