docs(admin-api) securing the admin api

app/_data/docs_nav_0.10.x.yml

@@ -41,6 +41,9 @@
     - text: Public Lua API reference
       url: /lua-reference/
 
+    - text: Securing the Admin API
+      url: /secure-admin-api
+
     - text: Plugin Development Guide
       url: /plugin-development
       items:

app/docs/0.10.x/admin-api.md

@@ -68,6 +68,11 @@ keep the configuration consistent across all nodes.
 - `8001` is the default port on which the Admin API listens.
 - `8444` is the default port for HTTPS traffic to the Admin API.
 
+This API is designed for internal use and provides full control over Kong, so
+care should be taken when setting up Kong environments to avoid undue public
+exposure of this API. See [this document][secure-admin-api] for a discussion
+of methods to secure the Admin API.
+
 ## Supported Content Types
 
 The Admin API accepts 2 content types on every endpoint:
@@ -1878,3 +1883,4 @@ HTTP 204 No Content
 
 [clustering]: /docs/{{page.kong_version}}/clustering
 [cli]: /docs/{{page.kong_version}}/cli
+[secure-admin-api]: /docs/{{page.kong_version}}/secure-admin-api

app/docs/0.10.x/secure-admin-api.md

@@ -0,0 +1,142 @@
+---
+title: Securing the Admin API
+---
+
+# Overview
+
+Kong's Admin API provides a RESTful interface for administration and
+configuration of APIs, plugins, consumers, and credentials. Because this
+API allows full control of Kong, it is important to secure this API against
+unwanted access. This document describes a few possible approaches to securing
+the Admin API.
+
+## Table of Contents
+
+- [Network Layer Access Restrictions](#network-layer-access-restrictions)
+  - [Reduce Listening Footprint](#reduce-listening-footprint)
+  - [Layer 3/4 Network Controls](#layer-34-network-controls)
+- [Kong API Loopback](#kong-api-loopback)
+- [Custom Nginx Configuration](#custom-nginx-configuration)
+
+## Network Layer Access Restrictions
+
+### Reduce Listening Footprint
+
+By default, Kong will accept requests for both the public-facing entrypoint, and
+the Admin API, on `0.0.0.0`, which will bind to all available interfaces on the
+host. Reducing this exposure footprint by limiting the interfaces by which the
+Admin API can be accessed is a foundational step. This setting can be adjusted
+via the `admin_listen` Kong configuration directive. For example:
+
+`admin_listen 127.0.0.1:8001`
+
+This will define the Nginx `listen` directive used by Kong to the prescribed
+value, instructing Kong to only respond to requests received on the localhost
+interface.
+
+[Back to TOC](#table-of-contents)
+
+### Layer 3/4 Network Controls
+
+In cases where the Admin API must be exposed beyond a localhost interface,
+network security best practices dictate that network-layer access be restricted
+as much as possible. Consider an environment in which Kong listens on a private
+network interface, but should only be accessed by a small subset of an IP range.
+In such a case, host-based firewalls (e.g. iptables) are useful in limiting
+input traffic ranges. For example:
+
+
+```bash
+# assume that Kong is listening on the address defined below, as defined as a
+# /24 CIDR block, and only a select few hosts in this range should have access
+
+$ grep admin_listen /etc/kong/kong.conf
+admin_listen 10.10.10.3
+
+# explicitly allow TCP packets on port 8001 from the Kong node itself
+# this is not necessary if Admin API requests are not sent from the node
+$ iptables -A INPUT -s 10.10.10.3 -m tcp -p tcp --dport 8001 -j ACCEPT
+
+# explicitly allow TCP packets on port 8001 from the following addresses
+$ iptables -A INPUT -s 10.10.10.4 -m tcp -p tcp --dport 8001 -j ACCEPT
+$ iptables -A INPUT -s 10.10.10.5 -m tcp -p tcp --dport 8001 -j ACCEPT
+
+# drop all TCP packets on port 8001 not in the above IP list
+$ iptables -A INPUT -m tcp -p tcp --dport 8001 -j DROP
+
+```
+
+Additional controls, such as similar ACLs applied at a network device level, are
+encouraged, but fall outside the scope of this document.
+
+[Back to TOC](#table-of-contents)
+
+## Kong API Loopback
+
+Kong's routing design allows it to serve as a proxy for the Admin API itself. In
+this manner, Kong itself can be used to provide fine-grained access control to
+the Admin API. Such an environment requires bootstrapping a new API that defines
+the `admin_listen` address as the API's `upstream_url`. For example:
+
+```bash
+# assume that Kong has defined admin_listen as 127.0.0.1:8001, and we want to
+# reach the Admin API via the url `/admin-api`
+
+$ curl http://localhost:8001/apis \
+  --data name=admin-api \
+  --data uris=/admin-api \
+  --data upstream_url=http://localhost:8001
+
+# we can now transparently reach the Admin API through the proxy server
+$ curl localhost:8000/admin-api/apis
+{  
+   "data":[  
+      {  
+         "uris":[  
+            "\/admin-api"
+         ],
+         "id":"653b21bd-4d81-4573-ba00-177cc0108dec",
+         "upstream_read_timeout":60000,
+         "preserve_host":false,
+         "created_at":1496351805000,
+         "upstream_connect_timeout":60000,
+         "upstream_url":"http:\/\/localhost:8001",
+         "strip_uri":true,
+         "https_only":false,
+         "name":"admin-api",
+         "http_if_terminated":true,
+         "upstream_send_timeout":60000,
+         "retries":5
+      }
+   ],
+   "total":1
+}
+```
+
+From here, simply apply desired Kong-specific security controls (such as
+[basic][basic-auth] or [key authentication][key-auth],
+[IP restrictions][ip-restriction], or [access control lists][acl]) as you would
+normally to any other Kong API.
+
+[Back to TOC](#table-of-contents)
+
+## Custom Nginx Configuration
+
+Kong is tightly coupled with Nginx as an HTTP daemon, and can thus be integrated
+into environments with custom Nginx configurations. In this manner, use cases
+with complex security/access control requirements can use the full power of
+Nginx/OpenResty to build server/location blocks to house the Admin API as
+necessary. This allows such environments to leverage native Nginx authorization
+and authentication mechanisms, ACL modules, etc., in addition to providing the
+OpenResty environment on which custom/complex security controls can be built.
+
+For more information on integrating Kong into custom Nginx configurations, see
+[Custom Nginx configuration & embedding Kong][custom-configuration].
+
+[Back to TOC](#table-of-contents)
+
+[acl]: /plugins/acl
+[basic-auth]: /plugins/basic-authentication/
+[custom-configuration]: /docs/{{page.kong_version}}/configuration/#custom-nginx-configuration
+[ip-restriction]: /plugins/ip-restriction
+[key-auth]: /plugins/key-authentication