Secure connections

IG is often deployed to replay credentials or other security information. In a real world deployment, this information must be communicated over a secure connection using HTTPS, meaning HTTP over encrypted Transport Layer Security (TLS). Never send real credentials, bearer tokens, or other security information unprotected over HTTP.

This guide describes how to install self-signed certificates for trying out the software or for deployments where you manage all clients that access IG. For information about how to use well-known CA-signed certificates, refer to the documentation for the Java Virtual Machine (JVM).

After installing certificates for client-server trust, consider which cipher suites to use. IG inherits the list of cipher suites from the underlying Java environment.

IG uses the JSSE to secure connections. You can set security and system properties to configure the JSSE. For a list of properties to customize the JSSE in Oracle Java, refer to the Customization section of the JSSE Reference guide.

Configure IG for HTTPS (client-side)

When IG sends requests over HTTP to a proxied application, or requests services from a third-party application, IG is acting as a client of the application, and the application is acting as a server. IG is client-side.

When IG sends requests securely over HTTPS, IG must be able to trust the server. By default, IG uses the Java environment truststore to trust server certificates. The Java environment truststore includes public key signing certificates from many well-known Certificate Authorities (CAs).

When servers present certificates signed by trusted CAs, then IG can send requests over HTTPS to those servers, without any configuration to set up the HTTPS client connection. When server certificates are self-signed or signed by a CA whose certificate is not automatically trusted, the following objects can be required to configure the connection:

KeyStoreSecretStore, to manage a secret store for cryptographic keys and certificates, based on a standard Java keystore.
SecretsTrustManager, to manage trust material that verifies the credentials presented by a peer.
(Optional) SecretsKeyManager, to manage keys that authenticate a TLS connection to a peer.
ClientHandler and ReverseProxyHandler reference to ClientTlsOptions, for connecting to TLS-protected endpoints.

The following procedure describes how to set up IG for HTTPS (client-side), when server certificates are self-signed or signed by untrusted CAs.

Set up IG for HTTPS (client-side) for untrusted servers

Locate or set up the following directories:
- Directory containing the sample application .jar: sampleapp_install_dir
- Directory to store the sample application certificate and IG keystore: /path/to/secrets

Extract the public certificate from the sample application:

$ cd /path/to/secrets

$ jar --verbose --extract \
--file sampleapp_install_dir/IG-sample-application-2023.11.0.jar tls/sampleapp-cert.pem

inflated: tls/sampleapp-cert.pem

The file /path/to/secrets/tls/sampleapp-cert.pem is created.

From the same directory, import the certificate into the IG keystore, and answer yes to trust the certificate:
```
$ keytool -importcert \
-alias ig-sampleapp \
-file tls/sampleapp-cert.pem \
-keystore reverseproxy-truststore.p12 \
-storetype pkcs12 \
-storepass password

...
Trust this certificate? [no]: yes

Certificate was added to keystore
```
Because keytool converts all characters in its key aliases to lowercase, use only lowercase in alias definitions of a keystore.

List the keys in the IG keystore to make sure that a key with the alias ig-sampleapp is present:

$ keytool -list \
-v \
-keystore /path/to/secrets/reverseproxy-truststore.p12 \
-storetype pkcs12 \
-storepass password

Keystore type: PKCS12
Keystore provider: SUN
Your keystore contains 1 entry
Alias name: ig-sampleapp
...

In the terminal where you run IG, create an environment variable for the value of the keystore password:
```
$ export KEYSTORE_SECRET_ID='cGFzc3dvcmQ='
```
The password is retrieved by the SystemAndEnvSecretStore, and must be base64-encoded.

Add the following route to IG to serve the sample application .css and other static resources:

Linux
Windows

$HOME/.openig/config/routes/00-static-resources.json

appdata\OpenIG\config\routes\00-static-resources.json

{
  "name" : "00-static-resources",
  "baseURI" : "http://app.example.com:8081",
  "condition": "${find(request.uri.path,'^/css') or matchesWithRegex(request.uri.path, '^/.*\\\\.ico$') or matchesWithRegex(request.uri.path, '^/.*\\\\.gif$')}",
  "handler": "ReverseProxyHandler"
}

Add the following route to IG:

Linux
Windows

$HOME/.openig/config/routes/client-side-https.json

appdata\OpenIG\config\routes\client-side-https.json

{
  "name": "client-side-https",
  "condition": "${find(request.uri.path, '/home/client-side-https')}",
  "baseURI": "https://app.example.com:8444",
  "heap": [
    {
      "name": "Base64EncodedSecretStore-1",
      "type": "Base64EncodedSecretStore",
      "config": {
        "secrets": {
          "keystore.secret.id": "cGFzc3dvcmQ="
        }
      }
    },
    {
      "name": "KeyStoreSecretStore-1",
      "type": "KeyStoreSecretStore",
      "config": {
        "file": "/path/to/secrets/reverseproxy-truststore.p12",
        "storeType": "PKCS12",
        "storePasswordSecretId": "keystore.secret.id",
        "secretsProvider": "Base64EncodedSecretStore-1",
        "mappings": [
          {
            "secretId": "trust.manager.secret.id",
            "aliases": [ "ig-sampleapp" ]
          }
        ]
      }
    },
    {
      "name": "SecretsTrustManager-1",
      "type": "SecretsTrustManager",
      "config": {
        "verificationSecretId": "trust.manager.secret.id",
        "secretsProvider":"KeyStoreSecretStore-1"
      }
    },
    {
      "name": "ReverseProxyHandler-1",
      "type": "ReverseProxyHandler",
      "config": {
        "tls": {
          "type": "ClientTlsOptions",
          "config": {
            "trustManager": "SecretsTrustManager-1"
          }
        },
        "hostnameVerifier": "ALLOW_ALL"
      },
      "capture": "all"
    }
  ],
  "handler": "ReverseProxyHandler-1"
}

Notice the following features of the route:

The route matches requests to /home/client-side-https.
The baseURI changes the request URI to point to the HTTPS port for the sample application.
The Base64EncodedSecretStore provides the keystore password.
The SecretsTrustManager uses a KeyStoreSecretStore to manage the trust material.
The KeyStoreSecretStore points to the sample application certificate. The password to access the keystore is provided by the SystemAndEnvSecretStore.
The ReverseProxyHandler uses the SecretsTrustManager for the connection to TLS-protected endpoints. All hostnames are allowed.

Test the setup:
1. Start the sample application
  $ java -jar sampleapp_install_dir/IG-sample-application-2023.11.0.jar
2. Go to http://ig.example.com:8080/home/client-side-https.
  
  The request is proxied transparently to the sample application, on the TLS port 8444.
3. Check the route log for a line like this:
  GET https://app.example.com:8444/home/client-side-https

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.

For more information, refer to About keys and certificates.

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 the Install.

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 Configuration location.

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 the Install.

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

IG 2023.11

Secure connections

Configure IG for HTTPS (client-side)

Configure IG for HTTPS (server-side)

Serve the same certificate for TLS connections to all server names

Serve different certificates for TLS connections to different server names