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
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-7.1.2.warfrom the ForgeRock BackStage download site.
IG-7.1.2.warto the Tomcat
$ cp IG-7.1.2.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, 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.
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
<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
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.
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.