Install IG

Download and start IG

Download the IG .zip file

The .zip file unpacks into a /path/to/identity-gateway directory with the following content:

bin: Start and stop executables
classes: Initially empty; used to install patches from ForgeRock support
docker/Dockerfile: Dockerfile and README to build an IG Docker image
legal-notices: Licenses and copyrights
lib: IG and third-party libraries

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

The installation directory should be a new, empty directory. Installing IG into an existing installation directory can cause errors.
Download IG-2023.6.0.zip from the ForgeRock BackStage download site, and copy the .zip file to the installation directory:
```
$ cp IG-2023.6.0.zip /path/to/IG-2023.6.0.zip
```
Unzip the file:
```
$ unzip IG-2023.6.0.zip
```
The directory /path/to/identity-gateway is created.

Start IG

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:
- Linux
- Windows
$ /path/to/identity-gateway/bin/start.sh ... ... started in 1234ms on ports : [8080 8443]
C:\path\to\identity-gateway\bin\start.bat
By default, IG configuration files are located under $HOME/.openig (on Windows appdata\OpenIG). For information about how to use a different location, refer to Change the base location of the IG configuration.
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, refer to AdminHttpApplication (admin.json).

Allow startup when there is an existing PID file

By default, if there is an existing PID file during startup the startup fails. Use one of the following ways to allow startup when there is an existing PID file. IG then removes the existing PID file and creates a new one during startup.

Add the following configuration to admin.json and restart IG:
```
{
  "pidFileMode": "override"
}
```

Define an environment variable for the configuration token ig.pid.file.mode, and then start IG in the same terminal:

Linux
Windows

$ IG_PID_FILE_MODE=override /path/to/identity-gateway/bin/start.sh

C:\IG_PID_FILE_MODE=override
C:\path\to\identity-gateway\bin\start.bat appdata\OpenIG

Define a system property for the configuration token ig.pid.file.mode when you start IG:
- Linux
- Windows
$HOME/.openig/env.sh
appdata\OpenIG\env.sh
```
export "IG_OPTS=-Dig.pid.file.mode=override"
```

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/bin/stop.sh $HOME/.openig

C:\path\to\identity-gateway\bin\stop.bat appdata\OpenIG

Configure IG for HTTPS (server-side)

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.

Using keys and certificates

The examples in this doc set use self-signed certificates, but your deployment is likely to use certificates issued by a certificate authority (CA certificates).

The way to obtain CA certificates depends on the certificate authority that you are using, and is not described in this document. As an example, refer to Let’s Encrypt.

Integrate CA certificates by using secret stores:

For PEM files, use a FileSystemSecretStore and PemPropertyFormat
For PKCS12 keystores, use a KeyStoreSecretStore

For examples, refer to Serve the same certificate for TLS connections to all server names.

Note the following points about using secrets:

When IG starts up, it listens for HTTPS connections, using the ServerTlsOptions configuration in admin.json. The keys and certificates are fetched at startup.
Keys and certificates must be present at startup.
If keys or certificates change, you must to restart IG.
When the autoRefresh property of FileSystemSecretStore or KeyStoreSecretStore is enabled, the secret store is automatically reloaded when the filesystem or keystore is changed.

For information about secret stores provided in IG, refer to Secrets object and secret stores.

Serve the same certificate for TLS connections to all server names

This example uses PEM files and a PKCS#12 keystore for self-signed certificates, but you can adapt it to use official (non self-signed) keys and certificates.

Before you start, install IG, as described in Download and start IG.

Locate a directory for the secrets, for example, /path/to/secrets.
Create self-signed keys in one of the following ways. If you have your own keys, use them and skip this step.

Use your own keys

If you have your own keys, use them and skip this step.
Set up a self-signed certificate in a (PKCS#12) keystore
1. Create the keystore, replacing /path/to/secrets with your path:
  
  $ keytool \ -genkey \ -alias https-connector-key \ -keyalg RSA \ -keystore /path/to/secrets/IG-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.
2. In the secrets directory, add a file called keystore.pass, containing the keystore password password:
  
  $ cd /path/to/secrets/ $ echo -n 'password' > keystore.pass
  
  Make sure the password file contains only the password, with no trailing spaces or carriage returns.
Set up self-signed certificate stored in PEM file
1. Locate a directory for secrets, and go to it:
  
  $ cd /path/to/secrets
2. Create the following secret key and certificate pair as PEM files:
  
  $ openssl req \ -newkey rsa:2048 \ -new \ -nodes \ -x509 \ -days 3650 \ -subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \ -keyout ig.example.com-key.pem \ -out ig.example.com-certificate.pem
  
  Two PEM files are created, one for the secret key, and another for the associated certificate.
3. Map the key and certificate to the same secret ID in IG:
  
  $ cat ig.example.com-key.pem ig.example.com-certificate.pem > key.manager.secret.id.pem

Set up TLS on IG in one of the following ways:

Keys stored in a (PKCS#12) keystore

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"
    }
  ],
  "heap": [
    {
      "name": "ServerTlsOptions-1",
      "type": "ServerTlsOptions",
      "config": {
        "keyManager": {
          "type": "SecretsKeyManager",
          "config": {
            "signingSecretId": "key.manager.secret.id",
            "secretsProvider": "ServerIdentityStore"
          }
        }
      }
    },
    {
      "type": "FileSystemSecretStore",
      "name": "SecretsPasswords",
      "config": {
        "directory": "/path/to/secrets",
        "format": "PLAIN"
      }
    },
    {
      "name": "ServerIdentityStore",
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "/path/to/secrets/IG-keystore",
        "storePasswordSecretId": "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.

Keys stored in PEM file

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"
    }
  ],
  "heap": [
    {
      "name": "ServerTlsOptions-1",
      "type": "ServerTlsOptions",
      "config": {
        "keyManager": {
          "type": "SecretsKeyManager",
          "config": {
            "signingSecretId": "key.manager.secret.id",
            "secretsProvider": "ServerIdentityStore"
          }
        }
      }
    },
    {
      "name": "ServerIdentityStore",
      "type": "FileSystemSecretStore",
      "config": {
        "format": "PLAIN",
        "directory": "/path/to/secrets",
        "suffix": ".pem",
        "mappings": [{
          "secretId": "key.manager.secret.id",
          "format": {
            "type": "PemPropertyFormat"
          }
        }]
      }
    }
  ]
}

Notice how this file differs to that for the keystore-based approach:

The ServerIdentityStore is a FileSystemSecretStore.
The FileSystemSecretStore reads the keys that are stored as file in the PEM standard format.

Start IG:
- Linux
- Windows
$ /path/to/identity-gateway/bin/start.sh ... ... started in 1234ms on ports : [8080 8443]
C:\path\to\identity-gateway\bin\start.bat
By default, IG configuration files are located under $HOME/.openig (on Windows appdata\OpenIG). For information about how to use a different location, refer to Change the base location of the IG configuration.

Serve different certificates for TLS connections to different server names

This example uses PEM files for self-signed certificates, but you can adapt it to use official (non self-signed) keys and certificates.

Before you start, install IG, as described in Download and start IG.

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

Create the following secret key and certificate pair as PEM files:

For ig.example.com:

Create a key and certificate:

$ openssl req \
-newkey rsa:2048 \
-new \
-nodes \
-x509 \
-days 3650 \
-subj "/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \
-keyout ig.example.com-key.pem \
-out ig.example.com-certificate.pem

Two PEM files are created, one for the secret key, and another for the associated certificate.

Map the key and certificate to the same secret ID in IG:

$ cat ig.example.com-key.pem ig.example.com-certificate.pem > key.manager.secret.id.pem

For servers grouped by a wildcard:

Create a key and certificate:

$ openssl req \
-newkey rsa:2048 \
-new \
-nodes \
-x509 \
-days 3650 \
-subj "/CN=*.example.com/OU=example/O=com/L=fr/ST=fr/C=fr" \
-keyout wildcard.example.com-key.pem \
-out wildcard.example.com-certificate.pem

Map the key and certificate to the same secret ID in IG:

$ cat wildcard.example.com-key.pem wildcard.example.com-certificate.pem > wildcard.secret.id.pem

For other, unmapped servers

Create a key and certificate:

$ openssl req \
-newkey rsa:2048 \
-new \
-nodes \
-x509 \
-days 3650 \
-subj "/CN=un.mapped.com/OU=example/O=com/L=fr/ST=fr/C=fr" \
-keyout default.example.com-key.pem \
-out default.example.com-certificate.pem

Map the key and certificate to the same secret ID in IG:

$ cat default.example.com-key.pem default.example.com-certificate.pem > default.secret.id.pem

Add the following file to IG, replacing /path/to/secrets with your path, and then restart 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": {
        "sni": {
          "serverNames": {
            "ig.example.com": "key.manager.secret.id",
            "*.example.com": "wildcard.secret.id"
          },
          "defaultSecretId" : "default.secret.id",
          "secretsProvider": "ServerIdentityStore"
        }
      }
    },
    {
      "name": "ServerIdentityStore",
      "type": "FileSystemSecretStore",
      "config": {
        "format": "PLAIN",
        "directory": "path/to/secrets",
        "suffix": ".pem",
        "mappings": [
          {
            "secretId": "key.manager.secret.id",
            "format": {
              "type": "PemPropertyFormat"
            }
          },
          {
            "secretId": "wildcard.secret.id",
            "format": {
              "type": "PemPropertyFormat"
            }
          },
          {
            "secretId": "default.secret.id",
            "format": {
              "type": "PemPropertyFormat"
            }
          }
        ]
      }
    }
  ]
}

Notice the following features of the file:

The ServerTlsOptions object maps two servers to secret IDs, and includes a default secret ID
The secret IDs correspond to the secret IDs in the FileSystemSecretStore, and the PEM files generated in an earlier step.

Run the following commands to request TLS connections to different servers, using different certificates:

Connect to ig.example.com, and note that the certificate subject corresponds to the certificate created for ig.example.com:

$ openssl s_client -connect localhost:8443 -servername ig.example.com

...
Server certificate
-----BEGIN CERTIFICATE-----
MII...dZC
-----END CERTIFICATE-----
subject=/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr
issuer=/CN=ig.example.com/OU=example/O=com/L=fr/ST=fr/C=fr

Connect to other.example.com, and note that the certificate subject corresponds to the certificate created with the wildcard, *.example.com:

$ openssl s_client -connect localhost:8443 -servername other.example.com

...
Server certificate
-----BEGIN CERTIFICATE-----
MII...fY=
-----END CERTIFICATE-----
subject=/CN=*.example.com/OU=example/O=com/L=fr/ST=fr/C=fr
issuer=/CN=*.example.com/OU=example/O=com/L=fr/ST=fr/C=fr

Connect to unmapped.site.com, and note that the certificate subject corresponds to the certificate created for the default secret ID:

$ openssl s_client -connect localhost:8443 -servername unmapped.site.com

...
Server certificate
-----BEGIN CERTIFICATE-----
MII..rON
-----END CERTIFICATE-----
subject=/CN=un.mapped.com/OU=example/O=com/L=fr/ST=fr/C=fr
issuer=/CN=un.mapped.com/OU=example/O=com/L=fr/ST=fr/C=fr

Configure environment variables and system properties

Configure environment variables and system properties 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, refer to Router.

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

Linux
Windows

$ IG_ROUTER_SCAN_INTERVAL='2 seconds' /path/to/identity-gateway/bin/start.sh

C:\IG_ROUTER_SCAN_INTERVAL='2 seconds'
C:\start.bat appdata\OpenIG

Define environment variables for startup, runtime, and stop

IG provides the following environment variables for Java runtime options:

IG_OPTS

(Optional) Java runtime options for IG and its startup process, such as JVM memory sizing options.

Include all options that are not shared with the stop script.

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

Linux
Windows

# 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 IG_OPTS environment variable
export IG_OPTS="${IG_OPTS} ${JVM_OPTS} ${JSSE_OPTS}"

C:\set "JVM_OPTS=-Xms256m -Xmx2048m"
C:\set "JSSE_OPTS=-Djdk.tls.ephemeralDHKeySize=2048"
C:\set "IG_OPTS=%IG_OPTS% %JVM_OPTS% %JSSE_OPTS%"

JAVA_OPTS

(Optional) Java runtime options for IG include all options that are shared by the start and stop script.

Add .jar files for IG extensions

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

Create a directory to hold .jar files for IG extensions:

Linux
Windows

$HOME/.openig/extra

appdata\OpenIG\extra

When IG starts up, the JVM loads .jar files in the extra directory.

IG 2023.6

Install IG

Download and start IG

Download the IG .zip file

Start IG

Start IG with default settings

Start IG with custom settings

Allow startup when there is an existing PID file

Stop IG

Configure IG for HTTPS (server-side)

Using keys and certificates

Serve the same certificate for TLS connections to all server names

Serve different certificates for TLS connections to different server names

Configure environment variables and system properties

Start IG with a customized router scan interval

Define environment variables for startup, runtime, and stop

Add .jar files for IG extensions