ping-auth Kong Gateway Plugin

Table of Contents

• Overview
• File Structure
• Installation
• Configuration
• Usage
  • Mutual TLS (mTLS)
  • Transfer-Encoding
• Useful links

Overview

Kong Gateway is a Lua module built on OpenResty, which is a Lua adaptation of NGINX. Kong allows granular control of the entire request/response cycle by allowing for the use of third-party Lua modules, which it refers to as "plugins". The ping-auth plugin was created to allow Kong deployments to utilize Ping products as policy providers via the Sideband API protocol.

The Kong Plugin Development Kit (PDK) allows plugins to interface with Kong at various stages in the request/response cycle by providing a set of callback functions that plugins can tie into. As an authentication plugin, ping-auth primarily acts in the access phase (after Kong recieves a request but before forwarding it to the API) and the response phase (after a response is received from the API but before sending it to the client). During these phases, ping-auth makes a sideband request to the Ping service, then receives and properly applies the response.

File Structure

• schema.lua - Defines plugin configuration fields and performs basic validation
• handler.lua - Entry point for Kong; provides callbacks to custom lifecycle functions
• access.lua/response.lua - Handling for specific lifecycle functions
• network_handler.lua - Utility class for network handling and helper functions

Installation

This plugin can be installed by following the LuaRocks or Manual Installation steps in Kong's Installation guide.

To install via LuaRocks, run the following command:

luarocks install kong-plugin-ping-auth

After installation, the plugin can be loaded into Kong by editing the following property in kong.conf:

plugins = bundled,ping-auth

Loading can be confirmed by looking for the debug-level message Loading plugin: ping-auth in Kong's error.log.

Some general tips for manual installation on RHEL8:

• The Kong configuration file is located at /etc/kong/kong.conf and the rest of the files (like the logs) are located at /usr/local/kong/
• Instead of modifying lua_package_path in the conf file, it may be easier to simply put the plugin directory into /usr/local/share/lua/5.1/kong/plugins/ with all the default plugins. This property must still be modified in the conf file: plugins = bundled,ping-auth

Configuration

One installed, the ping-auth plugin can be enabled and configured either via Kong's admin UI the API. It can be applied granularly to a specific Route or Service, or globally to apply sideband authentication to all Routes/Services.

Here's a description of all the currently provided configuration options:

• service_url (required) - The full URL of the Ping policy provider; this should not contain /sideband... in the path
• shared_secret (required) - The shared secret value to authenticate this plugin to the policy provider
• secret_header_name (required) - The header name in which the shared secret should be provided
• connection_timeout_ms (optional, default 10000) - The duration to wait before timing out a connection
• connection_keepAlive_ms (optional, default 60000) - The duration to keep a connection alive for reuse
• verify_service_certificate (optional, default true) - Controls whether the service certificate should be verified; intended for testing purposes
• enable_debug_logging (optional, default false) - Controls if requests/responses should be logged at the DEBUG level
  • NOTE: log_level = debug must be set in kong.conf in order for the log messages to appear in the error.log

Usage

Mutual TLS (mTLS)

This plugin does support client certificate authentication via mTLS, however this features requires using the mtls-auth plugin (only available in the Enterprise edition of Kong) in conjunction with ping-auth. Documentation for mtls-auth can be found here. When configured, this plugin will go through the mTLS dance in order to retrieve the client certificate, which then allows ping-auth to provide the certificate in the client_certificate field of the sideband requests.

Transfer-Encoding

Currently, due to an outstanding defect in Kong, ping-auth is unable to support the Transfer-Encoding header regardless of the value. This defect is being tracked on GitHub.

Useful links

• Kong Plugin Development Guide
• Kong PDK Reference
• OpenResty Lua NGINX Reference
• Lua Syntax Cheatsheet
• Lua Tutorial