kong-admin-proxy []

A web proxy microservice that proxies requests to the native Kong's Admin API, while extending it by providing helpful methods for integration.

Summary

• Prerequisites
• Installation
• Configuration
• Usage
• License

Prerequisites

• A running Kong installation
• Nodejs
• Npm
• Sailsjs

Installation

With npm

# Install
npm install -g kong-admin-proxy

# Start service
kong-admin-proxy start

# To start kong-admin-proxy on a custom port
kong-admin-proxy start -p [port]

From source

$ git clone https://github.com/pantsel/kong-admin-proxy.git
$ cd kong-admin-proxy
$ npm install
$ npm start

Configuration

There is an example configuration file on following path.

/config/local_example.js

Just copy this to /config/local.js and make necessary changes to it. Note that this local.js file is in .gitignore so it won't go to VCS at any point.

Usage

kong-admin-proxy proxies requests to all Kong's admin routes

The microservice registers itself to Kong and can be accessed like:

$ curl -X (GET,POST,PATCH,PUT,DELETE) http://kong:8000/kong-proxy/{any-kong-admin-api-route}

Request Headers

Header	Default	Description
apikey (required)	-	The key-auth credential assigned to a registered consumer.
kong-admin-url (optional)	The kong_admin_url specified in /config/local.js configuration.	The URL of Kong's admin API.

Extended methods

Create Consumer POST

$ curl -X POST http://kong:8000/kong-proxy/consumers

Create a consumer while associating it with groups and authorizations all at once.

Request Body

Attribute	Description
username (semi-optional)	The consumer's username.
custom_id (semi-optional)	The consumer's custom_id.
acls (optional)	An array of group names to assign to the consumer.
authorizations (optional)	An array of Authorization credentials to assign to the consumer.

Example

{
    "username"  : "testio",
    "custom_id" : "qwerty",
    "acls" : ["group1","group2","group3"],
    "authorizations" : [{
        "name" : "basic-auth",
        "config" : {
            "username" : "testio",
            "password" : "secret"
        }
    },{
        "name" : "hmac-auth",
        "config" : {
            "username" : "testio",
            "secret" : "secret"
        }
    },{
        "name" : "jwt" // Default configuration will be used
    },{
        "name" : "key-auth" // Default configuration will be used
    },{
        "name" : "oauth2",
        "config" : {
            "name" : "testio",
            "redirect_uri" : "http://testio.com/authorize"
        }	
    }]
}

Register API POST

$ curl -X POST http://kong:8000/kong-proxy/apis

Register an API while adding required plugins to it as well.

You can also update an already registered API and it's associated plugins by including the API's id property to the request.

#####Request Body

Attribute	Description
name optional	The API name. If none is specified, will default to the request_host or request_path.
request_host semi-optional	The public DNS address that points to your API. For example, mockbin.com. At least request_host or request_path or both should be specified.
request_path semi-optional	The public path that points to your API. For example, /someservice. At least request_host or request_path or both should be specified.
strip_request_path optional	Strip the request_path value before proxying the request to the final API. For example a request made to /someservice/hello will be resolved to upstream_url/hello. By default is false.
preserve_host optional	Preserves the original Host header sent by the client, instead of replacing it with the hostname of the upstream_url. By default is false.
upstream_url	The base target URL that points to your API server, this URL will be used for proxying requests. For example, https://mockbin.com.
plugins	An array of plugin configurations to add to the API.

Example

{
	"name" : "testapi",
	"request_path" : "/testapi",
	"strip_request_path" : true,
	"preserve_host" : false,
	"upstream_url" : "http://testapi.io",
	"plugins" : [{
		"name" : "hmac-auth",
		"config.hide_credentials" :false
	},{
		"name" : "acl",
		"config.blacklist" : "192.168.1.2,192.168.1.3"
		
	},{
		"name" : "jwt" // Default configuration will be used
	}]
	
}

Retrieve consumer credentials GET

$ curl -X GET http://kong:8000/kong-proxy/consumers/{id or username}/credentials

Retrieve all credentials assigned to the specified consumer

Example response

HTTP 200 OK

{
  "credentials": [
    {
      "name": "jwt",
      "data": [
        {
          "secret": "5e107841ab65444b936c45013723c377",
          "id": "6c5431ca-b311-4111-aea4-b4d57a61d5c4",
          "created_at": 1479414037000,
          "key": "87aacc4f613447ed9f8bcec05f787a34",
          "algorithm": "HS256",
          "consumer_id": "8c669088-796b-46f2-aaa5-f403760811f0"
        }
      ],
      "total": 1
    },
    {
      "name": "key-auth",
      "data": [
        {
          "created_at": 1479327062000,
          "consumer_id": "8c669088-796b-46f2-aaa5-f403760811f0",
          "key": "17cd7df14bc24dc385d7e40fdeb25714",
          "id": "a7e22f17-c738-4a53-b994-d2921255936e"
        }
      ],
      "total": 1
    },
    ...
  ],
  "total": 5
}

Author

Panagis Tselentis

License

The MIT License (MIT)
=====================

Copyright (c) 2015 Panagis Tselentis

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.