PingAccess

Configuring Kong Gateway for PingAccess integration

Download, install, and configure the ping-auth plugin to set up a connection between Kong Gateway and PingAccess.

Before you begin

Install and start Kong Gateway. Learn more in the Kong Gateway documentation.

Steps

  1. Download and extract the ping-auth plugin for Kong Gateway from https://luarocks.org/modules/pingidentity/kong-plugin-ping-auth.

  2. Install the ping-auth plugin using one of the following procedures:

    • Via LuaRocks from the created ‘rock’: If you use this procedure, run the luarocks install kong-plugin-ping-auth command to install the plugin.

    • Manually: Learn more in Kong’s installation guide.

  3. After installation, load the plugin into Kong:

    1. Edit the plugins property in the kong.conf file to include the ping-auth plugin.

      Example:

      plugins = bundled,ping-auth

    2. Restart Kong Gateway to apply your changes.

    3. To confirm that Kong loaded the plugin successfully, look for the debug-level message Loading plugin: ping-auth in Kong’s error.log file.

    You can find more information and configuration tips in Load the plugin and Verify loading the plugin in the Kong Gateway documentation.

  4. Use the Kong Gateway UI or API to complete the configuration.

  • Kong Gateway UI

  • Kong Gateway API

Setting up Kong Gateway

Steps

  1. In Kong Manager, select the Default workspace, then click Plugins.

    Screen capture illustrating the Kong Manager UI on the Plugins page.

  2. On the ping-auth line, click Edit

  3. On the Update ping-auth plugin page, click the toggle to enable the plugin.

    Screen capture that illustrates editing a plugin in Kong Manager. The toggle is blue to indicate it’s active, and the Global radio button is enabled.

  4. (Optional) If you want to enable the plugin for specific consumers, services, or routes, click Scoped and then enter Service, Route, and Consumer information as needed.

  5. In the Config.Service URL field, enter the full URL for PingAccess, using the https://<PINGACCESS_URL>:<SIDEBAND_PORT>/ format.

    Example:

    https://localhost:3020/

    • <PINGACCESS_URL> is the fully-qualified name of the machine running PingAccess.

    • Don’t include /sideband…​ in the path.

    • The default sideband port is 3020, but you should check the sideband.http.port property in the PingAccess run.properties file to confirm that you haven’t configured a different value. Learn more in the Configuration file reference.

    • The sideband.http.enabled property must be set to true in the PingAccess run.properties file for the ping-auth plugin to communicate with PingAccess successfully.
    Screen capture illustrating the Config.Service URL and Config.Shared Secret fields in Kong Manager. The Config.Verify Service Certificate is enabled.

  6. In the Config.Shared Secret field, paste the shared secret you created in Configuring PingAccess for Kong Gateway integration.

    Version 1.2.0 of the ping-auth plugin supports referenceable secrets. For security reasons, store the shared secret in a vault supported by Kong. Learn more in Secrets Management and Environment Variables Vault in the Kong documentation.

  7. In the Config.Secret Header Name field, enter the name of the header that provides the shared secret.

    The default value is CLIENT-TOKEN.

  8. (Optional) Configure additional options in Kong Manager or the API:

    You can find information on using the API to configure these fields in Create a plugin in the Kong Gateway admin API documentation.
    Option API Field Name Description

    Config.Connection KeepAlive Ms

    connection_keepAlive_ms

    The duration to keep the connection alive for reuse.

    The default value is 6000.

    Config.Connection Timeout Ms

    connection_timeout_ms

    The duration to wait before the connection times out.

    The default value is 10000.

    Config.Enable Debug Logging

    enable_debug_logging

    Controls if requests and responses are logged at the debug level. The default value is false.

    For log messages to show in the error.log, you must set log_level = debug in the kong.conf file.

    Config.Verify Service Certificate

    verify_service_certificate

    Controls whether the service certificate is verified.

    This configuration option is intended for testing purposes. The default value is true.

  9. Click Update, then click Update Plugin.

Next steps

Create a PingAccess application for the protected API and verify the connection between PingAccess and Kong Gateway.

Setting up Kong Gateway using the API

Steps

  1. Include the following JSON object in a POST request to https://<KONG_URL>/plugins:

    {
    "name": "ping-auth",
    "enabled": true,
    "config": {
        "service_url": "https://<PINGACCESS_URL>:3020/",
        "shared_secret": "<SHARED_SECRET>",
        "secret_header_name": "<HEADER_NAME>"
    }
}

    Use the following information to fill out the required fields in the Config section:

    • service_url: The full URL of the Ping policy provider, using the https://<PINGACCESS_URL>:<SIDEBAND_PORT>/ format. The default value is https://localhost:3020/.

      • <PINGACCESS_URL> is the fully-qualified name of the machine running PingAccess.

      • Don’t include /sideband…​ in the path.

      • The default sideband port is 3020, but you should check the sideband.http.port property in the PingAccess run.properties file to confirm that you haven’t configured a different value. Learn more in the Configuration file reference.

      • The sideband.http.enabled property must be set to true in the PingAccess run.properties file for the ping-auth plugin to communicate with PingAccess successfully.

    • shared_secret: The shared secret used to authenticate this plugin to the policy provider. Paste the shared secret you created in Configuring PingAccess for Kong Gateway integration.

      Version 1.2.0 of the ping-auth plugin supports referenceable secrets. For security reasons, store the shared secret in a vault supported by Kong. Learn more in Secrets Management and Environment Variables Vault in the Kong documentation.

    • secret_header_name: The name of the header that provides the shared secret. The default value is CLIENT-TOKEN.

  2. (Optional) Include additional fields in the POST request, making sure to adhere to the Kong API specification.

    Learn more in Create a plugin in the Kong Gateway admin API documentation.

    Option API Field Name Description

    Config.Connection KeepAlive Ms

    connection_keepAlive_ms

    The duration to keep the connection alive for reuse.

    The default value is 6000.

    Config.Connection Timeout Ms

    connection_timeout_ms

    The duration to wait before the connection times out.

    The default value is 10000.

    Config.Enable Debug Logging

    enable_debug_logging

    Controls if requests and responses are logged at the debug level. The default value is false.

    For log messages to show in the error.log, you must set log_level = debug in the kong.conf file.

    Config.Verify Service Certificate

    verify_service_certificate

    Controls whether the service certificate is verified.

    This configuration option is intended for testing purposes. The default value is true.

Next steps

Create a PingAccess application for the protected API and verify the connection between PingAccess and Kong Gateway.