PingGateway route properties

Properties simplify deploying PingGateway to different environments without changing route configurations. You store the configuration centrally with properties variables set differently for each installation.

You can declare properties variables in the PingGateway configuration or in an external file and use them in expressions in routes and in config.json to set configuration parameters.

All the routes in a Router inherit the properties variables you declare. You can use a property defined in config.json in any of the routes in the configuration.

Usage

Simple property configured inline

{
  "properties": {
    "<variable-name>": "valid JSON value"
  }
}

Group property configured inline

{
  "properties": {
    "<group-name>": {
      "<variable-name>": "valid JSON value",
      "<other-variable-name>": "valid JSON value"
    }
  }
}

Properties configured in one or more external files

{
  "properties": {
    "$location": "<expression>"
  }
}

In this example, description1 and description2 prefix the variable names contained in the external file.

{
  "properties": {
    "description1": {
      "$location": "<expression>"
    },
    "description2": {
      "$location": "<expression>"
    }
  }
}

Reloadable properties in an external file

PingGateway can reload the properties from a local file.

This format uses an ID for location:

{
  "properties": {
    "$location:<_id>": "<expression>"
  }
}

You can define multiple reloadable properties files by using different IDs.

Properties

"<variable-name>": configuration expression<string>

Named variable to use in the PingGateway configuration.

Use the variable in expressions to set configuration parameters in config.json and in routes.

The variable takes any valid JSON value: string, number, boolean, array, object, or null.

This example declares appLocation in config.json and uses it to set the baseURI parameter of the handler:

{
  "properties": {
    "appLocation": "https://app.example.com:8444"
  },
  "handler": {
    "type": "Router",
    "baseURI": "${appLocation}",
    "capture": "all"
  }
}

This example defines a ports variable and uses it in an appLocation variable:

{
  "properties": {
    "ports": [8444, 8445, 8446],
    "appLocation": "https://app.example.com:${ports[1]}"
  },
  "handler": {
    "type": "Router",
    "baseURI": "${appLocation}",
    "capture": "all"
  }
}

This example defines the request path in a route condition using the variable uriPath:

{
  "properties": {
    "uriPath": "hello"
  },
  "handler": {
    "type": "StaticResponseHandler",
    "config": {
      "status": 200,
      "headers": {
        "Content-Type": [ "text/plain; charset=UTF-8" ]
      },
      "entity": "Hello world!"
    }
  },
  "condition": "${matchesWithRegex(request.uri.path, '^/welcome') or matchesWithRegex(request.uri.path, '&{uriPath}')}"
}

"<group-name>": <object>, required

Named group of variables to use in the PingGateway configuration.

This example defines a directories group in config.json for use in route configurations:

{
  "properties": {
    "directories": {
      "config": "${openig.configDirectory.path}",
      "auditlog": "/tmp/logs"
    }
  }
}

Combine the group name and variable name with dot notation in your expressions, such as ${directories.auditlog}:

{
  "type": "AuditService",
  "config": {
    "eventHandlers": [
      {
        "class": "org.forgerock.audit.handlers.csv.CsvAuditEventHandler",
        "config": {
          "name": "csv",
          "logDirectory": "${directories.auditlog}"
        }
      }
    ]
  }
}

"$location": configuration expression<string>, required

Location and name of one or more local JSON files containing property variables.

The expression resolves to a local file. Using a file:// URL in the configuration is deprecated.

PingGateway expects .json files and with property variables in a key/value format. The key mustn’t contain the dot (.) separator.

By default, the files use ISO-8859-1 encoding (deprecated in favor of UTF-8). To use UTF-8 encoding, set the system property org.forgerock.config.resolvers.properties.encoding to UTF-8.

For example, this file uses the correct format:

{
  "openamLocation": "https://am.example.com:8443/am/",
  "portNumber": 8444
}

This file causes an error due to the . separators in the key names:

{
  "openam.location": "https://am.example.com:8443/am/",
  "port.number": 8444
}

"$location:<_id>": configuration expression<string>, required

Location with a unique ID, whose value is a local JSON or Java properties file defining property variables.

The expression resolves to a local file PingGateway can read from and write to.

Using a file:// URL in the configuration is deprecated.
Update the file with an HTTP PUT request to the routes REST API.

The body of the request must use JSON-format properties, even if the local file is a Java properties file.

When the local file is a Java properties file, PingGateway writes a comment header with a timestamp for the change.
When changes to the properties prevent a route from reloading, PingGateway reverts to the previous state of the properties.
When you define multiple reloadable properties files with different IDs, use different property names in each file.

PingGateway doesn’t guarantee the order in which it resolves a property with the same name in different files.
Although you can define reloadable properties files as properties in admin.json and config.json, PingGateway only reloads those files at startup time.
By default, the files use ISO-8859-1 encoding (deprecated in favor of UTF-8). To use UTF-8 encoding, set the system property org.forgerock.config.resolvers.properties.encoding to UTF-8.

Find an example in Reloadable properties.

Examples

Property variables configured in one file

This example uses an expression to set the location of the file with property variables:

{
  "properties": {
    "$location": "${openig.configDirectory}/myProperties.json"
  }
}

This example uses a string to set the location of the file with property variables:

{
  "properties": {
    "$location": "/Users/user-id/.openig/config/myProperties.json"
  }
}

The file location takes any real URL.

The file myProperties.json contains the base URL for AM and the port number of an application:

{
  "openamLocation": "https://am.example.com:8443/am/",
  "appPortNumber": 8444
}

Property variables configured in multiple files

This example uses two files with property variables:

{
  "properties": {
    "urls": {
      "$location": "/path/to/myUrlProperties.json"
    },
    "ports": {
       "$location": "/path/to/myPortProperties.json"
    }
  }
}

The file myUrlProperties.json contains the base URL of the sample application:

{
  "appUrl": "https://app.example.com"
}

The file myPortProperties.json contains the port number of an application:

{
  "appPort": 8444
}

The base config file config.json can use the properties as follows:

{
  "properties": {
    "urls": {
      "$location": "/Users/user-id/.openig/config/myUrlProperties.json"
    },
    "ports": {
      "$location": "/Users/user-id/.openig/config/myPortProperties.json"
    }
  },
  "handler": {
    "type": "Router",
    "name": "_router",
    "baseURI": "${urls.appUrl}:${ports.appPort}"
  }
}

Reloadable properties

This example test route stores a baseURI property in a local props.json file. Notice the "$location:<_id>" format, where <_id> is props:

{
  "properties": {
    "$location:props": "&{ig.instance.dir}/props.json"
  },
  "baseURI": "&{baseURI}",
  "handler": "ReverseProxyHandler"
}

The props.json file contains the baseURI property:

{
    "baseURI": "http://localhost:8081"
}

When you make changes to the properties, PingGateway reloads this route with the new baseURI value:

Get the props property resource for the route to check the current properties values.

The resource _id matches the ID in the "$location:<_id>" property:
```
$ curl 'localhost:8085/api/system/objects/_router/routes/test/resources/props'
```
Output
```
{"_id":"props","format":"JSON","content":{"baseURI": "http://localhost:8081"}}
```
To read all the property resources for the test route, get localhost:8085/api/system/objects/_router/routes/test/resources?_queryFilter=true instead.

Update the props property by modifying the resource with an HTTP PUT request.

The body of the request is the "content" of the resource with the changes:

$ curl \
--request PUT \
--url 'http://localhost:8085/api/system/objects/_router/routes/test/resources/props' \
--header 'Content-Type: application/json' \
--data '{"baseURI":"http://localhost:8080"}'

Output

{"_id":"props","format":"JSON","content":{"baseURI":"http://localhost:8080"}}

PingGateway rewrites the props.json file, then reloads this route with the new baseURI value.