{"id":18753336,"url":"https://github.com/pingidentity/kong-plugin-ping-auth","last_synced_at":"2025-04-13T00:31:38.218Z","repository":{"id":60514781,"uuid":"480914466","full_name":"pingidentity/kong-plugin-ping-auth","owner":"pingidentity","description":"This repository contains the source for the ping-auth Kong plugin.","archived":false,"fork":false,"pushed_at":"2025-03-14T18:56:31.000Z","size":14,"stargazers_count":1,"open_issues_count":1,"forks_count":5,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-26T18:57:24.588Z","etag":null,"topics":["kong-gateway","kong-plugin","lua"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pingidentity.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-12T17:44:44.000Z","updated_at":"2025-03-14T18:56:34.000Z","dependencies_parsed_at":"2023-12-21T20:07:02.738Z","dependency_job_id":"f29ccc69-de41-408f-859b-25de8ff3393c","html_url":"https://github.com/pingidentity/kong-plugin-ping-auth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fkong-plugin-ping-auth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fkong-plugin-ping-auth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fkong-plugin-ping-auth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pingidentity%2Fkong-plugin-ping-auth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pingidentity","download_url":"https://codeload.github.com/pingidentity/kong-plugin-ping-auth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650590,"owners_count":21139670,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kong-gateway","kong-plugin","lua"],"created_at":"2024-11-07T17:25:27.685Z","updated_at":"2025-04-13T00:31:37.867Z","avatar_url":"https://github.com/pingidentity.png","language":"Lua","readme":"# `ping-auth` Kong Gateway Plugin\n\n## Table of Contents\n* [Overview](#overview)\n* [File Structure](#file-structure)\n* [Installation](#installation)\n* [Configuration](#configuration)\n* [Usage](#usage)\n  * [Mutual TLS (mTLS)](#mutual-tls-mtls)\n  * [Transfer-Encoding](#transfer-encoding)\n* [Useful links](#useful-links)\n\n## Overview\n\n[Kong Gateway](https://docs.konghq.com/gateway/) is a [Lua](https://www.lua.org/) module built on \n[OpenResty](https://openresty.org/en/), which is a Lua adaptation of NGINX. Kong allows granular control of the \nentire request/response cycle by allowing for the use of third-party Lua modules, which it refers to as \n\"plugins\". The `ping-auth` plugin was created to allow Kong deployments to utilize Ping products as policy \nproviders via the Sideband API protocol.\n\nThe Kong Plugin Development Kit (PDK) allows plugins to interface with Kong at various stages in the \nrequest/response cycle by providing a set of callback functions that plugins can tie into. As an authentication \nplugin, `ping-auth` primarily acts in the `access` phase (after Kong recieves a request but before forwarding \nit to the API) and the `response` phase (after a response is received from the API but before sending it to \nthe client). During these phases, `ping-auth` makes a sideband request to the Ping service, then receives \nand properly applies the response.\n\n### File Structure\n\n* `schema.lua` - Defines plugin configuration fields and performs basic validation\n* `handler.lua` - Entry point for Kong; provides callbacks to custom lifecycle functions\n* `access.lua`/`response.lua` - Handling for specific lifecycle functions\n* `network_handler.lua` - Utility class for network handling and helper functions\n\n## Installation\n\nThis plugin can be installed by following the LuaRocks or Manual Installation steps in \n[Kong's Installation guide](https://docs.konghq.com/gateway-oss/2.5.x/plugin-development/distribution/#installing-the-plugin).\n\nTo install via LuaRocks, run the following command:\n```\nluarocks install kong-plugin-ping-auth\n```\nAfter installation, the plugin can be loaded into Kong by editing the following property in `kong.conf`:\n```\nplugins = bundled,ping-auth\n```\nLoading can be confirmed by looking for the debug-level message `Loading plugin: ping-auth` in Kong's `error.log`.\n\nSome general tips for manual installation on RHEL8:\n* The Kong configuration file is located at `/etc/kong/kong.conf` and the rest of the files (like the logs) are \nlocated at `/usr/local/kong/`\n* Instead of modifying `lua_package_path` in the conf file, it may be easier to simply put the plugin directory \ninto `/usr/local/share/lua/5.1/kong/plugins/` with all the default plugins. This property must still be modified in \nthe conf file: `plugins = bundled,ping-auth`\n\n## Configuration\n\nOne installed, the `ping-auth` plugin can be enabled and configured either via Kong's admin UI the API. \nIt can be applied granularly to a specific Route or Service, \nor globally to apply sideband authentication to all Routes/Services.\n\nHere's a description of all the currently provided configuration options:\n* `service_url` (*required*) - The full URL of the Ping policy provider; this should not contain `/sideband...` in the path\n* `shared_secret` (*required*) - The shared secret value to authenticate this plugin to the policy provider\n* `secret_header_name` (*required*) - The header name in which the shared secret should be provided\n* `connection_timeout_ms` (*optional*, default `10000`) - The duration to wait before timing out a connection\n* `connection_keepAlive_ms` (*optional*, default `60000`) - The duration to keep a connection alive for reuse\n* `verify_service_certificate` (*optional*, default `true`) - Controls whether the service certificate should be \nverified; intended for testing purposes\n* `enable_debug_logging` (*optional*, default `false`) - Controls if requests/responses should be logged at the DEBUG level\n  * NOTE: `log_level = debug` must be set in `kong.conf` in order for the log messages to appear in the `error.log`\n  \n\n## Usage\n\n### Mutual TLS (mTLS)\n\nThis plugin does support client certificate authentication via mTLS, however this features requires using\nthe `mtls-auth` plugin (only available in the Enterprise edition of Kong) in conjunction with `ping-auth`.\nDocumentation for `mtls-auth` can be found [here](https://docs.konghq.com/hub/kong-inc/mtls-auth/). When\nconfigured, this plugin will go through the mTLS dance in order to retrieve the client certificate, which\nthen allows `ping-auth` to provide the certificate in the `client_certificate` field of the sideband requests.\n\n### Transfer-Encoding\n\nCurrently, due to an outstanding defect in Kong, `ping-auth` is unable to support the `Transfer-Encoding`\nheader regardless of the value. This defect is being tracked on [GitHub](https://github.com/Kong/kong/issues/8083).\n\n## Useful links\n\n* [Kong Plugin Development Guide](https://docs.konghq.com/gateway/2.6.x/plugin-development/)\n* [Kong PDK Reference](https://docs.konghq.com/gateway/2.6.x/pdk/)\n* [OpenResty Lua NGINX Reference](https://openresty-reference.readthedocs.io/en/latest/Lua_Nginx_API/)\n* [Lua Syntax Cheatsheet](https://devhints.io/lua)\n* [Lua Tutorial](https://www.youtube.com/watch?v=iMacxZQMPXs)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingidentity%2Fkong-plugin-ping-auth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpingidentity%2Fkong-plugin-ping-auth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpingidentity%2Fkong-plugin-ping-auth/lists"}