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.
-
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.
The following are important usage notes for anyone trying to use the Kong plugin:
|
-
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
-
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 totrue
in the configuration file. See the Configuration file reference for more information.
About this task
To configure the ping-auth
plugin in Kong to set up a connection between PingAccess and Kong Gateway:
Steps
-
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 steps in Kong’s installation guide.
-
To install using LuaRocks, run the command:
luarocks install kong-plugin-ping-auth
-
After installation, load the plugin into Kong by editing the following property in
kong.conf:
plugins = bundled,ping-auth
. -
To confirm loading, look for the debug-level message
Loading plugin: ping-auth
in Kong’serror.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:
-
Configure a sideband client in PingAccess and copy the shared secret.
For more information, see Adding sideband clients.
-
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 forping-auth
to be able to communicate with PingAccess. -
Paste the shared secret into the Config.Shared Secret field in Kong Manager.
-
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 theerror.log
, you must setlog_level = debug
inkong.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.
Result:
Kong Gateway is now configured to work with PingAccess.
Setting up Kong Gateway using the API
Before you begin
-
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.
About this task
To configure the ping-auth
plugin in Kong to set up a connection between PingAccess and Kong Gateway:
Steps
-
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 steps in Kong’s installation guide.
-
To install using LuaRocks, run the command:
luarocks install kong-plugin-ping-auth
-
After installation, load the plugin into Kong by editing the following property in
kong.conf:
plugins = bundled,ping-auth
. -
To confirm loading, look for the debug-level message
Loading plugin: ping-auth
in Kong’serror.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>" } }
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 .konghq.com/gateway/2.8.x/admin-api///[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 theerror.log
, you must setlog_level = debug
inkong.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
-
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, setenable_debug_logging
to true, and setlog_level = debug
inkong.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.