--- title: Install IG in JBoss EAP (deprecated) description: This section installs JBoss to /path/to/jboss. If you use another directory structure, substitute the commands. component: pinggateway version: 2023.11 page_id: pinggateway:installation-guide:install-jboss canonical_url: https://docs.pingidentity.com/pinggateway/2023.11/installation-guide/install-jboss.html revdate: 2023-09-19T08:48:14Z section_ids: starting-jboss: Download and start IG in JBoss EAP jboss-cookie-domains: Configure cookie domains in JBoss EAP jboss-https: Configure IG for HTTPS (server-side) in JBoss EAP jboss-samesite: Configure SameSite for HTTP session cookies in JBoss --- # Install IG in JBoss EAP (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). | ## Download and start IG in JBoss EAP This section installs JBoss to `/path/to/jboss`. If you use another directory structure, substitute the commands. 1. Download a supported version of JBoss server from its [download page](https://developers.redhat.com/products/eap/download) and install it to `/path/to/jboss`. 2. In the JBoss configuration file `/path/to/jboss/standalone/configuration/standalone.xml`, delete the line for the JBoss welcome-content handler: ```xml ``` 3. Download `IG-2023.11.2.war` from the [Ping Identity Product Downloads](https://product-downloads.pingidentity.com/). 4. Copy the `IG-2023.11.2.war` to the JBoss deployment directory: ```bash $ cp IG-2023.11.2.war /path/to/jboss/standalone/deployments/IG-2023.11.2.war ``` 5. Start JBoss as a standalone server: ```bash $ /path/to/jboss/bin/standalone.sh ``` JBoss deploys IG in the root context. 6. 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 JBoss EAP To use IG to protect multiple applications running on different hosts, set a cookie domain as follows: * For stateful sessions, set a cookie domain in JBoss. For information, refer to the Red Hat documentation. 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 JBoss EAP This section describes how to set up JBoss to run IG over HTTPS. These instructions are for JBoss EAP 7.3, and are not compatible with earlier versions. For information about the set up for HTTPS (client-side), refer to [Configure IG for HTTPS (client-side)](securing-connections.html#client-side-https). The default ephemeral DH key size in the JVM is 1024-bit. To support stronger ephemeral DH keys, and protect against weak keys, set the following system property: `jdk.tls.ephemeralDHKeySize=2048`. Before you start, install IG in JBoss as described in the [Quick install](../getting-started/preface.html). JBoss is installed in `/path/to/jboss`. 1. Set the environment variable JBOSS\_HOME in two terminals: ```bash $ export JBOSS_HOME=/path/to/jboss ``` 2. In the first terminal, create a user with administrative permissions to run the setup: ```bash $ $JBOSS_HOME/bin/add-user.sh myadmin myadmin-password Added user 'myadmin' to file '$JBOSS_HOME/standalone/configuration/mgmt-users.properties' Added user 'myadmin' to file '$JBOSS_HOME/domain/configuration/mgmt-users.properties' ``` 3. Make a temporary directory for the settings and keystore: ```bash $ mkdir $JBOSS_HOME/tmp ``` 4. Create the following file as `$JBOSS_HOME/tmp/batch_settings`: ```none /socket-binding-group=standard-sockets/socket-binding=http/:write-attribute(name=port, value=8080) /socket-binding-group=standard-sockets/socket-binding=https/:write-attribute(name=port, value=8443) /socket-binding-group=standard-sockets/socket-binding=ajp/:write-attribute(name=port, value=8009) /socket-binding-group=standard-sockets/socket-binding=management-http/:write-attribute(name=port, value=9990) /socket-binding-group=standard-sockets/socket-binding=management-https/:write-attribute(name=port, value=9993) /subsystem=deployment-scanner/scanner=default/:write-attribute(name="scan-interval", value="2000") /interface=management/:write-attribute(name="inet-address", value="${jboss.bind.address:ig.example.com}") /interface=public/:write-attribute(name="inet-address", value="${jboss.bind.address:ig.example.com}") ``` 5. Generate a key pair with a self-signed certificate in the keystore: ```bash $ keytool \ -genkey \ -alias jboss \ -storetype PKCS12 \ -keyalg RSA \ -keystore $JBOSS_HOME/tmp/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. | 6. Start JBoss as a standalone server: ```bash $ $JBOSS_HOME/bin/standalone.sh ``` 7. While JBoss is running, in the second terminal, update the batch settings: ```bash $ $JBOSS_HOME/bin/jboss-cli.sh --connect \ --controller=ig.example.com:9990 command="run-batch -v \ --file=$JBOSS_HOME/tmp/batch_settings" ``` 8. Make sure IG is deployed on port `8080`: ```bash $ $JBOSS_HOME/bin/jboss-cli.sh --connect \ --controller=ig.example.com:9990 command="deployment list" ``` 9. Enable SSL: * Enable the SSL server: ```bash $ $JBOSS_HOME/bin/jboss-cli.sh --connect \ --controller=ig.example.com:9990 command="security enable-ssl-http-server \ --key-store-path=$JBOSS_HOME/tmp/keystore \ --key-store-password=password \ --key-store-type=PKCS12" Server reloaded. SSL enabled for default-server ssl-context is ssl-context-keystore key-manager is key-manager-keystore key-store is keystore ``` 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 JBoss | | | | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | JBoss supports SameSite from version 7.3.2. If you use an earlier version, and the following error occurs, upgrade to JBoss 7.3.2.```bash Error 'invalid token' during authentication because of 'The supplied token is invalid' ```For more information, refer to the JBoss documentation. | 1. Add a configuration element in `/path/to/jboss/webapps/ROOT/WEB-INF/undertow-handlers.conf`, to set one of the following values for the SameSite cookie `mode`: * `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 The following example sets the the SameSite cookie `mode` to `lax`: ```bash path(/)->samesite-cookie(Lax) ``` 2. Restart JBoss.