PingAccess

Kong API Gateway Integration

Ping Identity provides a Kong Gateway integration that enables PingAccess (and other Ping Identity products) to be used for policy decisions.

Integration with Kong Gateway allows PingAccess to handle the complexities of the OAuth and OpenID Connect (OIDC) protocols, making it easier to manage access control in your application programming interface (API). Rather than making access control configurations repeatedly, install and configure the Kong plugin once and manage your access control rules in PingAccess.

The following diagram explains how the traffic flow through Kong Gateway and PingAccess works.

Workflow diagram illustrating the API flow process from the HTTP client inbound request to the API gateway through the API gateway outbound response to the HTTP client.

  1. The HTTP client sends an inbound request to the API gateway.

  2. The API gateway sends a sideband request to PingAccess.

  3. PingAccess evaluates the request and sends a response to the API gateway.

  4. The API gateway will analyze the response from PingAccess to determine if the request should be allowed to the API, and if so, if there should be any modification to the request. Should the request be denied, then PingAccess will include directives to influence how the API gateway responds to the HTTP Client.

  5. The API sends an outbound response to the API gateway.

  6. The API gateway passes the response to PingAccess for processing.

  7. PingAccess sends a response to the API gateway.

  8. The API gateway processes the response from PingAccess. This will include directives for how to modify the response to the HTTP client if any modifications should be made.

The following are important usage notes for anyone trying to use the Kong plugin:

Mutual TLS (mTLS)

This plugin supports client certificate authentication using mTLS, however this feature requires using the mtls-auth plugin (only available in the Enterprise edition of Kong) in conjunction with ping-auth. For more information, see the Kong mTLS-auth documentation. When configured, this plugin uses the mTLS process to retrieve the client certificate, which allows ping-auth to provide the certificate in the client_certificate field of the sideband requests.

Transfer-encoding

Because of an outstanding defect in Kong, ping-auth is unable to support the Transfer-Encoding header, regardless of the value.

Logging limit

Because of OpenResty’s log level limit, log messages are limited to 2048 bytes by default, which is less than the size of many requests and responses. For more information, see the OpenResty reference documentation.

HTTP/2

The Kong Gateway does not support HTTP/2.

  • Setting up Kong Gateway

  • Setting up Kong Gateway using the API

Setting up Kong Gateway

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

Before you begin

About this task

To configure the ping-auth plugin in Kong to set up a connection between PingAccess and Kong Gateway:

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 plugin by following the LuaRocks or Manual Installation steps in Kong’s installation guide.

    1. To install using LuaRocks, run the command:

      luarocks install kong-plugin-ping-auth

    2. After installation, load the plugin into Kong by editing the following property in kong.conf: plugins = bundled,ping-auth.

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

  3. In Kong Manager, click your default workspace and then click Plugins.

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

  4. For the ping-auth plugin, click Edit, and then 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.

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

  6. Connect Kong Gateway to PingAccess:

    1. Configure a sideband client in PingAccess and copy the shared secret.

      For more information, see Adding sideband clients.

    2. Enter the URL for PingAccess into the Config.Service URL field, making sure to use the sideband port specified in the run.properties file.

      The default port is 3020.

      Enable the configuration in the run.properties file in order for ping-auth to be able to communicate with PingAccess.
      Screen capture illustrating the Config.Service URL and Config.Shared Secret fields in Kong Manager. The Config.Verify Service Certificate is enabled.

    3. Paste the shared secret into the Config.Shared Secret field in Kong Manager.

    4. Update the Config.Secret Header Name in Kong Manager if this value was changed in PingAccess.

  7. If needed, configure the rest of the optional fields in Kong Manager or the API.

    Option API Field Name Description

    Config.Connection KeepAlive Ms

    connection_keepAlive_ms

    The duration to keep the connection alive for reuse. The default is 6000.

    Config.Connection Timeout Ms

    connection_timeout_ms

    The duration to wait before the connection times out. The default is 10000.

    Config.Enable Debug Logging

    enable_debug_logging

    Controls if requests and responses are logged at the debug level. The default is false. For log messages to show in the error.log, you must set log_level = debug in kong.conf.

    Config.Verify Service Certificate

    verify_service_certificate

    Controls whether the service certificate is verified. This is intended for testing purposes and the default is true.

  8. Click Update and then click Update Plugin.

    Result:

    Kong Gateway is now configured to work with PingAccess.

Setting up Kong Gateway using the API

Before you begin

About this task

To configure the ping-auth plugin in Kong to set up a connection between PingAccess and Kong Gateway:

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 plugin by following the LuaRocks or Manual Installation steps in Kong’s installation guide.

    1. To install using LuaRocks, run the command:

      luarocks install kong-plugin-ping-auth

    2. After installation, load the plugin into Kong by editing the following property in kong.conf: plugins = bundled,ping-auth.

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

  3. Send the following 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>"
    }
}

    More information about the required fields are as follows:

    service_url

    The full URL of the Ping policy provider. This should not contain /sideband…​ in the path.

    shared_secret

    The shared secret value to authenticate this plugin to the policy provider.

    secret_header_name

    The header name in which the shared secret is provided.

    Additional configuration can be provided in accordance with the Kong API specification. For more information, see the Kong documentation.
    Option API Field Name Description

    Config.Connection KeepAlive Ms

    connection_keepAlive_ms

    The duration to keep the connection alive for reuse. The default is 6000.

    Config.Connection Timeout Ms

    connection_timeout_ms

    The duration to wait before the connection times out. The default is 10000.

    Config.Enable Debug Logging

    enable_debug_logging

    Controls if requests and responses are logged at the debug level. The default is false. For log messages to show in the error.log, you must set log_level = debug in kong.conf.

    Config.Verify Service Certificate

    verify_service_certificate

    Controls whether the service certificate is verified. This is intended for testing purposes and the default is true.

Creating an API application

About this task

To verify the connection by making an end-to-end request:

Steps

  1. In PingAccess, create an application for Kong.

    For more information, see Adding an application.

    1. Go to Applications → Applications and click +Add Application.

    2. Enter the Name, Context Root, and Virtual Host(s) information to match how the application APIs are exposed.

    3. In the Destination list, select Sideband.

    4. In the Sideband Client list, select the sideband client you created for Kong. Click Save.

      Troubleshooting:

      If the requests aren’t going through to the backend service as expected, debug logging can give a detailed breakdown of the request/response flow through Kong. In the ping-auth config, set enable_debug_logging to true, and set log_level = debug in kong.conf. These messages might contain sensitive request information and accumulate disk space, so you should disable debug logging after troubleshooting.

      The pingaccess.log on the PingAccess node can also provide useful debugging data. For more information, see Log configuration.

Next steps

After you create the application, you can assign rules to it to control access to APIs protected by the Kong gateway. See Rule management for more information about configuring rules.