Kong API Gateway Integration - PingAccess

Kong API Gateway Integration - PingAccess - 7.2

PingAccess

bundle

pingaccess-72

ft:publication_title

PingAccess

Product_Version_ce

PingAccess 7.2

category

Product

pa-72

pingaccess

ContentType_ce

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 OAuthOAuth A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server. and OpenID Connect (OIDC)OpenID Connect (OIDC)OIDC An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management. protocols, making it easier to manage access control in your APIapplication programming interface (API) A specification of interactions available for building software to access an application or service.. 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.

The HTTP client sends an inbound request to the API gateway.
The API gateway sends a sideband request to PingAccess.
PingAccess evaluates the request and sends a response to the API gateway.
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.
The API sends an outbound response to the API gateway.
The API gateway passes the response to PingAccess for processing.
PingAccess sends a response to the API gateway.
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.

Note:

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

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

Install and start Kong Gateway. For more information, see the Kong Gateway documentation.
Install and start PingAccess. For more information, see Installing and Uninstalling PingAccess.
Verify that the sideband.http.enabled property is set to true in the configuration file. See the Configuration file reference for more information.

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

Download and extract the ping-auth plugin for Kong Gateway from https://luarocks.org/modules/pingidentity/kong-plugin-ping-auth.
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.
In Kong Manager, click your default workspace and then click Plugins.
For the ping-auth plugin, click Edit, and then click the toggle to enable the plugin.
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.
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.
  
  Note:
  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.
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.

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

Click Update and then click Update Plugin.

Kong Gateway is now configured to work with PingAccess.

Setting up Kong Gateway using the API

Install and start Kong Gateway. For more information, see the Kong Gateway documentation.
Install and start PingAccess. For more information, see Installing and Uninstalling PingAccess.

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

Download and extract the ping-auth plugin for Kong Gateway from https://luarocks.org/modules/pingidentity/kong-plugin-ping-auth.
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.

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>"
    }
}

Note:

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

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

In PingAccess, create an application for Kong.

For more information, see Adding an application.

Go to Applications > Applications and click +Add Application.
Enter the Name, Context Root, and Virtual Host(s) information to match how the application APIs are exposed.
In the Destination list, select Sideband.
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.

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.