Install IG in Standalone Mode

Download and Start IG in Standalone Mode

Consider the following best practices for installing and running IG:

  • Create a service account with which to install and run IG, for example, igadmin. Do not use the root account to install and run IG.

  • Allocate the following permissions to the account:

    • Read/write permissions on the installation directory, for example /path/to/identity-gateway.

    • Execute permissions on the scripts in the installation bin directory, for example /path/to/identity-gateway/bin.

The following sections describe how to install and start IG in standalone mode, from a .zip file.

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.1.0.zip from the ForgeRock BackStage download site, and copy the .zip file to the installation directory:

    $ cp IG-7.1.0.zip /path/to/IG-7.1.0.zip
  3. Unzip the file:

    $ unzip IG-7.1.0.zip

    The directory /path/to/identity-gateway 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:

    $ /path/to/identity-gateway/bin/start.sh
    
    ...
    ... started in 1234ms on ports : [8080]

    By default, the base location for IG configuration files is in $HOME/.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 /path/to/instance-dir:

    $ /path/to/identity-gateway/bin/start.sh /path/to/instance-dir
  2. Check that IG is running in one of the following ways:

    • Ping IG at http://openig.example.com:8080/openig/ping, and make sure an HTTP 200 is returned.

    • Access the IG welcome page at http://openig.example.com:8080.

    • When IG is running in development mode, display the product version and build information at http://openig.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

  1. In the terminal where IG is running, select CTRL+C to stop the service.

Configure IG For HTTPS (Server-Side) in Standalone Mode

This section describes how to set up IG in standalone mode to run as a server over HTTPS. IG uses a KeyManager and a private key to prove its identity to the client.

For information about the set up for HTTPS (client-side), see Configure IG For HTTPS (Client-Side).

Before you start, install IG in standalone mode, as described in Download and Start IG in Standalone Mode.

  1. Locate the keystore directory, ig_keystore_directory, and in a terminal create an environment variable for it:

    $ export ig_keystore_directory=/path/to/secrets
  2. Create a keystore holding a self-signed certificate:

    $ keytool \
    -genkey \
    -alias https-connector-key \
    -keyalg RSA \
    -keystore $ig_keystore_directory/IG-keystore \
    -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.
  3. In the secrets directory, add a file called keystore.pass, containing the keystore password password:

    $ cd $ig_keystore_directory
    $ echo -n 'password' > keystore.pass
    Make sure that the password file contains only the password, with no trailing spaces or carriage returns.
  4. Add the following line to $HOME/.openig/bin/env.sh, where $HOME/.openig is the instance directory, replacing the path with your path to the keystore directory:

    $ export IG_KEYSTORE_DIRECTORY='/path/to/secrets'
  5. Add the following file to IG:

    • Linux

    • Windows

    $HOME/.openig/config/admin.json
    appdata\OpenIG\config\admin.json
    {
      "connectors": [
        {
          "port": 8080
        },
        {
          "port": 8443,
          "tls": "ServerTlsOptions-1"
        }
      ],
      "heap": [
        {
          "name": "ServerTlsOptions-1",
          "type": "ServerTlsOptions",
          "config": {
            "keyManager": {
              "type": "SecretsKeyManager",
              "config": {
                "signingSecretId": "key.manager.secret.id",
                "secretsProvider": "ServerIdentityStore"
              }
            }
          }
        },
        {
          "type": "FileSystemSecretStore",
          "name": "SecretsPasswords",
          "config": {
            "directory": "&{ig_keystore_directory}/",
            "format": "PLAIN"
          }
        },
        {
          "type": "KeyStoreSecretStore",
          "name": "ServerIdentityStore",
          "config": {
            "file": "&{ig_keystore_directory}/IG-keystore",
            "storePassword": "keystore.pass",
            "secretsProvider": "SecretsPasswords",
            "mappings": [
              {
                "secretId": "key.manager.secret.id",
                "aliases": ["https-connector-key"]
              }
            ]
          }
        }
      ]
    }

    Notice the following features of the file:

    • IG starts on port 8080, and on 8443 over TLS.

    • IG’s private keys for TLS are managed by the SecretsKeyManager, which references the KeyStoreSecretStore that holds the keys.

    • The password of the KeyStoreSecretStore is provided by the FileSystemSecretStore.

    • The KeyStoreSecretStore maps the keystore alias to the secret ID for retrieving the private signing keys.

    • The path to the keystore is provided by an environment variable.

  6. Start IG:

    $ /path/to/identity-gateway/bin/start.sh
    
    ...
    ... started in 1234ms on ports : [8080 8443]
  7. Access the IG welcome page on https://openig.example.com:8443.

    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 Environment Variables and System Properties for IG in

Standalone Mode

Configure environment variables and system properties for IG in standalone mode, as follows:

  • By adding environment variables on the command line when you start IG.

  • By adding environment variables in $HOME/.openig/bin/env.sh, where $HOME/.openig is the instance directory.

Start IG With a Customized Router Scan Interval

By default, IG scans every 10 seconds for changes to the route configuration files. Any changes to the files are automatically loaded into the configuration without restarting IG. For more information about the router scan interval, see Router.

The following example overwrites the default value of the Router scan interval to two seconds when you start up IG:

$ IG_ROUTER_SCAN_INTERVAL='2 seconds' /path/to/identity-gateway/bin/start.sh
Specify Environment Variables for Key and JVM Options

The following example specifies environment variables in the IG env.sh file to customize JVM options and keys:

# Specify JVM options
JVM_OPTS="-Xms256m -Xmx2048m"

# Specify the DH key size for stronger ephemeral DH keys, and to protect against weak keys
JSSE_OPTS="-Djdk.tls.ephemeralDHKeySize=2048"

# Wrap them up into the JAVA_OPTS environment variable
export JAVA_OPTS="${JAVA_OPTS} ${JVM_OPTS} ${JSSE_OPTS}"

Add .jar Files for IG Extensions in Standalone Mode

IG includes a complete Java application programming interface for extending your deployment with customizations. For more information, see Extend IG Through the Java API

Create the directory $HOME/.openig/extra, where $HOME/.openig is the instance directory, and add .jar files for IG extensions to the directory.

When IG starts up, the JVM loads .jar files in $HOME/.openig/extra.