--- title: Install IG in Jetty (deprecated) description: Configure Jetty to use the same protocol as the application you are protecting with IG. If the protected application is on a remote system, configure Jetty to use the same port as the protected application. If the protected application listens on both an HTTP and an HTTPS port, configure Jetty to listen on both an HTTP and an HTTPS port. component: pinggateway version: 2023.11 page_id: pinggateway:installation-guide:install-jetty canonical_url: https://docs.pingidentity.com/pinggateway/2023.11/installation-guide/install-jetty.html revdate: 2025-07-07T17:48:46Z section_ids: starting-jetty: Download and start IG in Jetty jetty-cookie-domains: Configure cookie domains in Jetty jetty-https: Configure IG for HTTPS (server-side) in Jetty jetty-samesite: Configure SameSite for HTTP session cookies in Jetty jetty-mysql: Configure access to MySQL over JNDI in Jetty stickiness-jetty: About session stickiness and session replication for Jetty --- # Install IG in Jetty (deprecated) | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The delivery of a .war file was deprecated in IG 7. Consider installing IG from a .zip file, as described in [Set up environment variables and system properties](envvar-sysprop.html). For more information, refer to [Migrate from web container mode to standalone mode](../upgrade/upgrade-war-to-zip.html). | Configure Jetty to use the same protocol as the application you are protecting with IG. If the protected application is on a remote system, configure Jetty to use the same port as the protected application. If the protected application listens on both an HTTP and an HTTPS port, configure Jetty to listen on both an HTTP and an HTTPS port. To configure Jetty to use an HTTP port other than 8080, modify the defaults in `/path/to/jetty/etc/jetty.xml`. Search for the default value of 8080 and replace it with the new port number. | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | IG depends on javax.websocket-api version 1.1, which is a higher version than that provided by Jetty. To prevent errors related to WebSocket, do not include the websocket configuration modules when you configure Jetty.To change the default port for Jetty in HTTP, edit `http.ini`.To change the default port for Jetty in HTTPS, edit `server.ini`. | ## Download and start IG in Jetty The commands in this guide assume that you install Jetty to `/path/to/jetty`, and after installation, you have a directory `/path/to/jetty/webapps` in which you install IG. If you use another directory structure, substitute the commands. 1. Download a supported version of Jetty server from its [download page](http://www.eclipse.org/jetty/download.html), and install it to `/path/to/jetty`. 2. Download `IG-2023.11.2.war` from the [Ping Identity Product Downloads](https://product-downloads.pingidentity.com/). 3. Copy the .war file: ```bash $ cp IG-2023.11.2.war /path/to/jetty/webapps/IG-2023.11.2.war ``` Jetty automatically deploys IG in the root context on startup. 4. Start Jetty: * To start Jetty in the background, enter: ```bash $ /path/to/jetty/bin/jetty.sh start ``` * To start Jetty in the foreground, enter: ```bash $ cd /path/to/jetty/ $ java -jar start.jar ``` 5. Check that IG is running in one of the following ways: * Ping IG at , and make sure an `HTTP 200` is returned. * Access the IG welcome page at . * When IG is running in development mode, display the product version and build information at . ## Configure cookie domains in Jetty To use IG for multiple protected applications running on different hosts, set a cookie domain as follows: * For stateful sessions, add a session domain handler element that specifies the domain to `/path/to/jetty/etc/webdefault.xml`, as in the following example: ```xml org.eclipse.jetty.servlet.SessionDomain .example.com ``` Restart Jetty to read the configuration changes. If JwtSession is not configured, stateful sessions are created automatically. For more information, refer to [Sessions](../about/about-sessions.html). * 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](../reference/MiscellaneousConfigurationObjects.html#JwtSession). ## Configure IG for HTTPS (server-side) in Jetty This section describes how to set up Jetty to run IG over HTTPS. For information about the set up for HTTPS (client-side), refer to [Configure IG for HTTPS (client-side)](securing-connections.html#client-side-https). These instructions are for Jetty 9.4.21, and are not compatible with earlier versions of Jetty. For more information about Jetty and HTTPS, refer to . 1. Install Jetty, and set up the location for the Jetty distribution binaries: * Download a supported version of Jetty server from its [download page](http://www.eclipse.org/jetty/download.html), and install it to `/path/to/jetty`. * Set the environment variable JETTY\_HOME for `/path/to/jetty`: ```bash $ export JETTY_HOME=/path/to/jetty ``` 2. Set up the location for configurations and customizations to the Jetty distribution: * Create a directory `/path/to/jetty_base`. * Set the environment variable JETTY\_BASE for `/path/to/jetty_base`: ```bash $ export JETTY_BASE=/path/to/jetty_base ``` 3. Set up the keystore: * Remove the built-in keystore: ```bash $ rm $JETTY_HOME/modules/ssl/keystore ``` * Generate a key pair with a self-signed certificate in the keystore: ```bash $ keytool \ -genkey \ -alias jetty \ -keyalg RSA \ -keystore $JETTY_HOME/modules/ssl/keystore \ -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. | 4. Create a directory to store local server customization and configurations in $JETTY\_BASE: * Delete the global `start.ini`: ```bash $ rm $JETTY_HOME/start.ini ``` * From $JETTY\_BASE, create the `start.d` folder to hold the module `.ini` files: ```bash $ cd $JETTY_BASE $ java -jar $JETTY_HOME/start.jar --create-startd MKDIR : ${jetty.base}/start.d INFO : Base directory was modified ``` 5. From $JETTY\_BASE, add the following Jetty configuration modules: ```bash $ cd $JETTY_BASE $ java -jar $JETTY_HOME/start.jar \ --add-to-start=server,webapp,deploy,ssl,jstl,ext,jsp,resources,console-capture,http,https INFO : webapp initialized in ${jetty.base}/start.d/webapp.ini INFO : ext initialized in ${jetty.base}/start.d/ext.ini INFO : server initialized in ${jetty.base}/start.d/server.ini INFO : mail transitively enabled INFO : servlet transitively enabled INFO : jsp initialized in ${jetty.base}/start.d/jsp.ini INFO : annotations transitively enabled INFO : resources initialized in ${jetty.base}/start.d/resources.ini INFO : transactions transitively enabled INFO : threadpool transitively enabled, ini template available with --add-to-start=threadpool INFO : ssl initialized in ${jetty.base}/start.d/ssl.ini INFO : plus transitively enabled INFO : deploy initialized in ${jetty.base}/start.d/deploy.ini INFO : jstl initialized in ${jetty.base}/start.d/jstl.ini INFO : security transitively enabled INFO : apache-jsp transitively enabled INFO : jndi transitively enabled INFO : console-capture initialized in ${jetty.base}/start.d/console-capture.ini INFO : apache-jstl transitively enabled INFO : http initialized in ${jetty.base}/start.d/http.ini INFO : client transitively enabled INFO : https initialized in ${jetty.base}/start.d/https.ini INFO : bytebufferpool transitively enabled, ini template available with --add-to-start=bytebufferpool MKDIR : ${jetty.base}/lib MKDIR : ${jetty.base}/lib/ext MKDIR : ${jetty.base}/resources MKDIR : ${jetty.base}/etc COPY : ${jetty.home}/modules/ssl/keystore to ${jetty.base}/etc/keystore MKDIR : ${jetty.base}/webapps MKDIR : ${jetty.base}/logs INFO : Base directory was modified ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | IG depends on javax.websocket-api version 1.1, which is a higher version than that provided by Jetty. To prevent errors related to WebSocket, do not include the websocket configuration modules when you configure Jetty.To change the default port for Jetty in HTTP, edit `http.ini`.To change the default port for Jetty in HTTPS, edit `server.ini`. | 6. Replace `jetty-util-*.jar` with the version for your installation, and find the obfuscated form of the keystore password: ```bash $ cd $JETTY_HOME/lib $ ls jetty-util-*.jar ``` ```bash $ java -cp jetty-util-.jar org.eclipse.jetty.util.security.Password password* password OBF:1v2...v1v MD5:5f4...f99 ``` 7. In `$JETTY_BASE/start.d/ssl.ini`, uncomment the following lines, and update the passwords with the OBF password returned in the previous step: ```ini ## Connector port to listen on jetty.ssl.port=8443 ## Keystore file path (relative to $jetty.base) jetty.sslContext.keyStorePath=etc/keystore ## Keystore password jetty.sslContext.keyStorePassword=OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v ## KeyManager password jetty.sslContext.keyManagerPassword=OBF:1v2j1uum1xtv1zej1zer1xtn1uvk1v1v ``` 8. Copy the IG .war file to `$JETTY_BASE/webapps/IG-2023.11.2.war`. 9. Go to $JETTY\_BASE, and start Jetty: ```bash $ cd $JETTY_BASE $ java -jar $JETTY_HOME/start.jar ``` 10. Access the IG welcome page on . If you see warnings that the site is not secure, or that the self-signed certificate is not valid, respond to the warnings to access the site. ## Configure SameSite for HTTP session cookies in Jetty 1. Add a session `` element in `/path/to/jetty/WEB-INF/web.xml`, and configure the `` element with one of the following values: * `SAME_SITE_NONE`: The browser always sends cookies in cross-site requests * `SAME_SITE_LAX`: The browser sends cookies only in same-site requests and cross-site top-level GET requests * `SAME_SITE_STRICT`: The browser never sends cookies in cross-site requests The following example sets the value to `none`: ```bash IG_SESSIONID __SAME_SITE_NONE__ true ``` 2. Restart Jetty. ## Configure access to MySQL over JNDI in Jetty If IG accesses an SQL database, then you must configure Jetty to access the database over 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 . 2. Copy the driver .jar to `/path/to/jetty/lib/jndi/` so that it is on Jetty's class path. 3. Add a JNDI data source for your MySQL server and database in `/path/to/jetty/etc/jetty.xml`: ```xml jdbc/forgerock jdbc:mysql://localhost:3306/databasename mysqladmin password ``` 4. Add a resource reference to the data source in `/path/to/jetty/etc/webdefault.xml`: ```xml MySQL Connection jdbc/forgerock javax.sql.DataSource Container ``` 5. Restart Jetty to read the configuration changes. ## About session stickiness and session replication for Jetty Jetty has provisions for session stickiness, and also for session replication through clustering: * Jetty's persistent session mechanism appends a node ID to the session ID in the same way Tomcat appends the `jvmRoute` value to the session cookie. This can be useful for session stickiness if your load balancer examines the session ID. * [Session Clustering with a Database](http://www.eclipse.org/jetty/documentation/current/configuring-sessions-jdbc.html) describes how to configure Jetty to persist sessions over JDBC, allowing session replication. Unless it is set up to be highly available, the database can be a single point of failure in this case. * [Session Clustering with MongoDB](http://www.eclipse.org/jetty/documentation/current/configuring-sessions-mongo.html) describes how to configure Jetty to persist sessions in MongoDB, allowing session replication. The Jetty documentation recommends this implementation when session data is seldom written but often read.