--- title: Deploying the PingIntelligence policy description: Deploy the PingIntelligence plugin for the Kong API Gateway. component: pingintelligence version: 5.2 page_id: pingintelligence:pingintelligence_integrations:pingintelligence_deploy_kong canonical_url: https://docs.pingidentity.com/pingintelligence/5.2/pingintelligence_integrations/pingintelligence_deploy_kong.html revdate: April 3, 2024 section_ids: about-this-task: About this task steps: Steps choose-from: Choose from: --- # 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 1. [Download](https://www.pingidentity.com/en/resources/downloads.html) the PingIntelligence plugin for Kong and copy to the `/opt/` directory on all the Kong nodes where you want to deploy the PingIntelligence plugin. 2. Untar the plugin file by entering the following command: ```shell $ untar pi-api-kong-policy-4.1.0.tar.gz ``` 3. Change the directory to `/opt/pingidentity/kong-policy`: ```shell $ cd /opt/pingidentity/kong-policy ``` 4. 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. ```shell $ luarocks make *.rockspec ``` 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 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; ``` 6. **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 | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | 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. | 1. 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: routes: - name: shop-books-route paths: - /shopapi-books - name: shop-electronics 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 ``` 2. 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: 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: ```shell $ 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. | 8. **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: ```shell curl --location --request POST ':/services//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: ```shell curl --location --request POST ':/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": } }' ```