PingIntelligence

Deploy PingIntelligence policy

Complete the following steps to deploy PingIntelligence plugin for Kong API gateway:

  1. Download the PingIntelligence plugin for Kong and copy to /opt/ directory on all the Kong nodes where you want to deploy PingIntelligence plugin.

  2. Untar the plugin file by entering the following command:

    $ untar pi-api-kong-policy-4.1.0.tar.gz

  3. Change directory to /opt/pingidentity/kong-policy

    $ cd /opt/pingidentity/kong-policy

  4. Run the luarocks command to deploy the PingIntelligence plugin

    $ luarocks make *.rockspec

    This command installs the PingIntelligence plugin files at /usr/local/share/lua/5.1/kong/plugins/pingintelligence/ location. This location may be different based on the version of Luarocks.

  5. 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 kong.yml file. 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;

  6. db-less mode: 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

    services

    • name

    • url

    • routes

    • name Name of the service or API

    • url The URL where the service or API is hosted

    • routesThe subpaths of the service. A maximum of 3-subpaths are supported

    plugins: In this section, define the ASE specific variables for a service or API.

    • name

    • service

    • name: The name of the plugin. This name was configured in 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.ymlfile has two sample service names configured.

    config

    • ase_primary_host

    • ase_secondary_host

    • ase_port

    • ase_token

    • ase_timeout

    • ase_keepalive

    • access_token

    • use_tls

    • sni_name

    • tls_verify

    • 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..

    • Apply plugin at a 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. 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

    • Apply plugin at the 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

  7. 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 kong.conf file.

Database mode

You can also optionally configure Kong to work in the database mode. If you are running Kong in the 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.

  • Apply plugin at 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":
    }
}'

  • Apply plugin at the 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":
    }
}'