Identity Gateway

Downloading, starting, and stopping IG

The following sections describe options for downloading and starting IG. For information about other installation options, such as setting the default location of the configuration folders, and configuring for HTTPS, see the Installation guide.

Download and start IG in standalone mode

Download the IG .zip file

  1. Create a local installation directory for IG. The examples in this section use /path/to.

  2. Download IG-7.2.0.zip from the Backstage download site, and copy the .zip file to the installation directory:

    $ cp IG-7.2.0.zip /path/to/IG-7.2.0.zip

  3. Unzip the file:

    $ unzip IG-7.2.0.zip

    The directory /path/to/identity-gateway-7.2.0 is created.

Start IG with default settings

Use the following step to start the instance of IG, specifying the configuration directory where IG looks for configuration files.

  1. Start IG:

    • Linux

    • Windows

    $ /path/to/identity-gateway-7.2.0/bin/start.sh

...
... started in 1234ms on ports : [8080 8443]
    C:\path\to\identity-gateway-7.2.0\bin\start.bat

    By default, the base location for IG configuration files is in %appdata%\OpenIG.

    To read the configuration from a different location, specify the base location as an argument. The following example reads the configuration from the config directory under the instance directory:

    • Linux

    • Windows

    $ /path/to/identity-gateway-7.2.0/bin/start.sh $HOME/.openig

...
... started in 1234ms on ports : [8080]
    C:\path\to\identity-gateway-7.2.0\bin\start.bat %appdata%\OpenIG

...
... started in 1234ms on ports : [8080]

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

Start IG with custom settings

By default, IG runs on HTTP, on port 8080, from the instance directory $HOME/.openig.

To start IG with custom settings, add the configuration file admin.json with the following properties, and restart IG:

  • vertx: Finely tune Vert.x instances.

  • connectors: Customize server port, TLS, and Vert.x-specific configurations. Each connectors object represents the configuration of an individual port.

  • prefix: Set the instance directory, and therefore, the base of the route for administration requests.

The following example starts IG on non-default ports, and configures Vert.x-specific options for the connection on port 9091:

{
  "connectors": [{
    "port": 9090
  },
  {
    "port": 9091,
    "vertx": {
      "maxWebSocketFrameSize": 128000,
      "maxWebSocketMessageSize": 256000,
      "compressionLevel": 4
    }
  }]
}

For more information, see AdminHttpApplication (admin.json).

Stop IG

Use the stop.sh script to stop an instance of IG, specifying the instance directory as an argument. If the instance directory is not specified, IG uses the default instance directory:

  • Linux

  • Windows

$ /path/to/identity-gateway-7.2.0/bin/stop.sh $HOME/.openig
C:\path\to\identity-gateway-7.2.0\bin\stop.bat %appdata%\OpenIG

Downloading and starting 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.

  1. Download a supported version of Tomcat server from its download page, and install it to /path/to/tomcat.

  2. Remove the ROOT directory in Tomcat:

    $ rm -rf /path/to/tomcat/webapps/ROOT

  3. Download IG-7.2.0.war from the Backstage download site.

  4. Copy the IG-7.2.0.war to the Tomcat webapps directory, as ROOT.war:

    $ cp IG-7.2.0.war /path/to/tomcat/webapps/ROOT.war

    Tomcat automatically deploys IG in the root context on startup.

  5. Start Tomcat:

    $ /path/to/tomcat/bin/startup.sh

    If necessary, make the startup scripts executable.

  6. Check that IG is running in one of the following ways:

Downloading and starting 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, and install it to /path/to/jetty.

  2. Download IG-7.2.0.war from the Backstage download site.

  3. Copy the .war file:

    $ cp IG-7.2.0.war /path/to/jetty/webapps/IG-7.2.0.war

    Jetty automatically deploys IG in the root context on startup.

  4. Start Jetty:

    • To start Jetty in the background, enter:

      $ /path/to/jetty/bin/jetty.sh start

    • To start Jetty in the foreground, enter:

      $ cd /path/to/jetty/
$ java -jar start.jar

  5. Check that IG is running in one of the following ways:

Downloading and starting 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 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:

    <server name="default-server">
  <host name="default-host" alias="localhost">
    <location name="/" handler="welcome-content"/> <!-- Delete this line -->

  3. Download IG-7.2.0.war from the Backstage download site.

  4. Copy the IG-7.2.0.war to the JBoss deployment directory:

    $ cp IG-7.2.0.war /path/to/jboss/standalone/deployments/IG-7.2.0.war

  5. Start JBoss as a standalone server:

    $ /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: