Deploying the PingIntelligence policy

Deploy the PingIntelligence plugin for the Kong API Gateway.

About this task

To deploy the PingIntelligence plugin for Kong API Gateway:

Steps

Download the PingIntelligence plugin for Kong and copy to the /opt/ directory on all the Kong nodes where you want to deploy the PingIntelligence plugin.
Untar the plugin file by entering the following command:
```
$ untar pi-api-kong-policy-4.1.0.tar.gz
```
Change the directory to /opt/pingidentity/kong-policy:
```
$ cd /opt/pingidentity/kong-policy
```
Run the LuaRocks command to deploy the PingIntelligence plugin:

This command installs the PingIntelligence plugin files at the /usr/local/share/lua/5.1/kong/plugins/pingintelligence/ location. This location may be different based on the version of LuaRocks.
```
$ luarocks make *.rockspec
```

Configure /opt/pingidentity/kong-policy/examples/kong.conf to provide the plugin name.

The default plugin name is pingintelligence. The plugin name that you configure in kong.conf is used in the kong.yml file. The following is a sample kong.conf file.

Edit your existing kong.conf file by copying the plugins = bundled,pingintelligence section.

#------------------------------
# Kong sample configuration file
# ------------------------------

log_level = debug
 plugins = bundled,pingintelligence
proxy_listen = 0.0.0.0:8000
admin_listen = 0.0.0.0:8001
database = off
declarative_config = /opt/pingidentity/kong-policy/examples/kong.yml
lua_ssl_trusted_certificate = /opt/pingidentity/kong-policy/certs/cacert.pem
lua_package_path = ./?.lua;./?/init.lua;

Optional: If you are running Kong in DB-less mode, configure the kong.yml file for deploying the PingIntelligence plugin.

The following table explains the variables of the file.

Variable Description

Variable	Description
Services
`name`	The name of the service or API.
`url`	The URL where the service or API is hosted.
`routes`	The subpaths of the service. A maximum of 3-subpaths are supported.
Plugins: Define the ASE specific variables for a service or API.
`name`	The name of the plugin. This name was configured in the `kong.conf` file.
`service`	The name of the service API. If you want to apply the plugin to more than one service, create a service section for each service as shown in the example `kong.yml` file. For example, if you have three services or APIs, your`kong.yml` file should have three `service` sections, one for each service. The example `kong.yml`file has two sample service names configured.
config
`ase_primary_host`	IP address of primary ASE node.
`ase_secondary_host`	IP address of the secondary ASE node.
`ase_port`	Port number of the ASE node
`ase_token`	The sideband ASE token that was generated as part of the prerequisites
`ase_timeout`	The time in milliseconds for which Kong waits for ASE to respond before trying the other host. The default value is 5,000 ms
`ase_keepalive`	The time in milliseconds for the keepalive connection. The default value is 60,000 ms.
`access_token`	If OAuth token is part of the query string, the `access_token` field allows you to set the query param key that holds OAuth token in the query string
`use_tls`	Configures a TLS connection between the API gateway and ASE. The default value is `false`.
`sni_name`	Fully qualified domain name (FQDN) of the certificate applied to ASE data port
`tls_verify`	When set to `true`, the API gateway verifies the certificate. If the certificate validation fails, the connection is closed. When set to `false`, the API gateway does not verify the certificate, however, the connection between the API gateway and ASE is encrypted.

Services

name

The name of the service or API.

url

The URL where the service or API is hosted.

routes

The subpaths of the service. A maximum of 3-subpaths are supported.

Plugins: Define the ASE specific variables for a service or API.

name

The name of the plugin. This name was configured in the kong.conf file.

service

The name of the service API. If you want to apply the plugin to more than one service, create a service section for each service as shown in the example kong.yml file. For example, if you have three services or APIs, yourkong.yml file should have three service sections, one for each service. The example kong.ymlfile has two sample service names configured.

config

ase_primary_host

IP address of primary ASE node.

ase_secondary_host

IP address of the secondary ASE node.

ase_port

Port number of the ASE node

ase_token

The sideband ASE token that was generated as part of the prerequisites

ase_timeout

The time in milliseconds for which Kong waits for ASE to respond before trying the other host. The default value is 5,000 ms

ase_keepalive

The time in milliseconds for the keepalive connection. The default value is 60,000 ms.

access_token

If OAuth token is part of the query string, the access_token field allows you to set the query param key that holds OAuth token in the query string

use_tls

Configures a TLS connection between the API gateway and ASE. The default value is false.

sni_name

Fully qualified domain name (FQDN) of the certificate applied to ASE data port

tls_verify

When set to true, the API gateway verifies the certificate. If the certificate validation fails, the connection is closed. When set to false, the API gateway does not verify the certificate, however, the connection between the API gateway and ASE is encrypted.

Per-service level: Configure the kong.yml file as described in the table above with the service name of all the API or services to which you want to apply the plugin.

The following is a sample kong.yml file:

# ------------------------------------------------------------------------------
# This is an example file to get you started with using
# declarative configuration in Kong.
# ------------------------------------------------------------------------------

# Metadata fields start with an underscore (_)
# Fields that do not start with an underscore represent Kong entities and attributes

# _format_version is mandatory,
# it specifies the minimum version of Kong that supports the format

_format_version: "1.1"

# Each Kong entity (core entity or custom entity introduced by a plugin)
# can be listed in the top-level as an array of objects:

services:
  - name: shop-books
    url: <your_service_url>
    routes:
      - name: shop-books-route
        paths:
          - /shopapi-books

  - name: shop-electronics
    url: <your_service_url>
    routes:
      - name: shop-electronics-route
        paths:
          - /shopapi-electronics

plugins:
  - name: pingintelligence
    service: shop-books
    _comment: "An example configuration of pingintelligence plugin"
    config:
      ase_primary_host: localhost
      ase_secondary_host: localhost

      ase_port: "8000"
      ase_token: 1ebd5fde1b0b4373a1ad8b8724d13813
      ase_timeout: "5000"
      ase_keepalive: "60000"
      access_token: access_token
      use_tls: false
      sni_name: test.ase.pi
      tls_verify: false
    tags:
      - api_security

  - name: pingintelligence
    service: shop-electronics
    _comment: "An example configuration of pingintelligence plugin"
    config:
      ase_primary_host: 172.16.40.220
      ase_secondary_host: 172.16.40.220
      ase_port: "8000"
      ase_token: 1ebd5fde1b0b4373a1ad8b8724d13813
      ase_timeout: "5000"
      ase_keepalive: "60000"
      access_token: access_token
      use_tls: false
      sni_name: test.ase.pi
      tls_verify: false
    tags:
      - api_security

Global level: To apply the plugin at the global level, remove the service name from the kong.yml file as shown in the sample file below:

# ------------------------------------------------------------------------------
# This is an example file to get you started with using
# declarative configuration in Kong.
# ------------------------------------------------------------------------------

# Metadata fields start with an underscore (_)
# Fields that do not start with an underscore represent Kong entities and attributes

# _format_version is mandatory,
# it specifies the minimum version of Kong that supports the format

_format_version: "1.1"

# Each Kong entity (core entity or custom entity introduced by a plugin)
# can be listed in the top-level as an array of objects:

services:
    url: <your_service_url>
    routes:
      paths:


plugins:
  - name: pingintelligence
     _comment: "An example configuration of pingintelligence plugin"
    config:
      ase_primary_host: localhost
      ase_secondary_host: localhost

      ase_port: "8000"
      ase_token: 1ebd5fde1b0b4373a1ad8b8724d13813
      ase_timeout: "5000"
      ase_keepalive: "60000"
      access_token: access_token
      use_tls: false
      sni_name: test.ase.pi
      tls_verify: false
    tags:
      - api_security

Start the API gateway after the plugin has been deployed:
```
$ kong start -c kong.conf
```
By default, Kong is configured to run its services on 8000 port and admin API on 8001 port. You can change these default ports in the kong.conf file.

Optional: Configure Kong to work in database mode. If you are running Kong in database mode, use the following curl commands to apply the plugin at a per-service level or global level.

You can refer the config section in step 6 above for more details on the parameters sent as part of the request in the curl commands. Make sure that Kong is running when you are applying the plugin in database mode.

Choose from:

Service level: Run the following command to apply the plugin at a per service level:

curl --location --request POST '<kong_ip>:<kong_admin_port>/services/<service_name>/plugins' \
--header 'Content-Type: application/json' \
--data-raw '{
	"name": "pingintelligence",
    "config": {
        "tls_verify": ,
        "sni_name": "",
        "ase_port": "",
        "ase_primary_host": "",
        "ase_token": "",
        "ase_timeout": "",
        "ase_keepalive": "",
        "ase_secondary_host": "",
        "access_token": "",
        "use_tls":
    }
}'

Global level: Run the following curl command to apply the plugin at the global level:

curl --location --request POST '<kong_ip>:<kong_admin_port>/plugins' \
--header 'Content-Type: application/json' \
--data-raw '{
	"name": "pingintelligence",
      "config": {
        "tls_verify": ,
        "sni_name": "",
        "ase_port": "",
        "ase_primary_host": "",
        "ase_token": "",
        "ase_timeout": "",
        "ase_keepalive": "",
        "ase_secondary_host": "",
        "access_token": "",
        "use_tls":
    }
}'