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

Create a local installation directory for IG. The examples in this section use /path/to.
Download IG-7.1.2.zip from the ForgeRock BackStage download site, and copy the .zip file to the installation directory:
```
$ cp IG-7.1.2.zip /path/to/IG-7.1.2.zip
```
Unzip the file:
```
$ unzip IG-7.1.2.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.

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
```
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

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

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

When IG is server-side, applications send requests to IG or request services from IG. IG is acting as a server of the application, and the application is acting as a client.

To run IG as a server over HTTPS, you must configure connections to TLS-protected endpoints, based on ServerTlsOptions.

Serve the Same Certificate for TLS Connections to All Server Names

During a TLS handshake, IG accesses secret key and certificate pairs sychronously; they are loaded in memory at IG startup, and must be present. You must restart IG to update a secret key and certificate pair. For information about secret stores provided in IG, see Secrets.

This example uses a PKCS12 keystore, but you can adapt it to use other certificates.

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

Locate a directory for secrets, for example, /path/to/secrets, and go to it.

Create a keystore holding a self-signed certificate:

$ keytool \
-genkey \
-alias https-connector-key \
-keyalg RSA \
-keystore IG-keystore \
-storepass password \
-keypass password \
-dname "CN=openig.example.com,O=Example Corp,C=FR"

Because keytool converts all characters in its key aliases to lower case, use only lowercase in alias definitions of a KeyStore.

Add a file called keystore.pass, containing the keystore password password:
```
$ echo -n 'password' > keystore.pass
```
Make sure that the password file contains only the password, with no trailing spaces or carriage returns.

Set up TLS on IG:

Add the following file to IG, replacing /path/to/secrets with your path:

Linux
Windows

$HOME/.openig/config/admin.json

appdata\OpenIG\config\admin.json

{
  "connectors": [
    {
      "port": 8080
    },
    {
      "port": 8443,
      "tls": "ServerTlsOptions-1"
    }
  ],
  "properties": {
    "ig_keystore_directory": "/path/to/secrets"
  },
  "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, whose ServerIdentityStore references a KeyStoreSecretStore.
The KeyStoreSecretStore maps the keystore alias to the secret ID for retrieving the server keys (private key + certificate).
The password of the KeyStoreSecretStore is provided by the FileSystemSecretStore.

Start IG:

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

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

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. After changing env.sh, restart IG to load the new configuration.

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.

IG 7.1.2