diff --git a/app/_landing_pages/admin-api.yaml b/app/_landing_pages/admin-api.yaml index 15552be05..7b14a3874 100644 --- a/app/_landing_pages/admin-api.yaml +++ b/app/_landing_pages/admin-api.yaml @@ -15,4 +15,138 @@ rows: - blocks: - type: text config: | - @todo \ No newline at end of file + The Admin API is an internal RESTful API designed for administration purposes. It provides full control over {{site.base_gateway}}. + + Requests to the Admin API can be sent to any node in the cluster, and Kong will keep the configuration consistent across all nodes. + + By default, the Admin API is exposed on the following ports: + * 8001 for HTTP + * 8444 for HTTPS + + This can be customized with the `admin_listen` parameter in in the [{{site.base_gateway}} configuration](/gateway/configuration/). + + - header: + text: "Specification" + type: h2 + columns: + - blocks: + - type: card + config: + title: API Specification + description: Learn how to use the Admin API. + icon: /assets/icons/service-document.svg + cta: + url: /api/gateway/admin-ee/3.9/ + align: end + - blocks: + - type: card + config: + title: Run in Insomnia + description: Open the Admin API specification in Insomnia. + icon: /assets/icons/insomnia/insomnia.svg + cta: + url: https://insomnia.rest/run/?uri=https%3A%2F%2Fraw.githubusercontent.com%2FKong%2Fdeveloper.konghq.com%2Fmain%2Fapi-specs%2Fgateway%2Fadmin-ee%2F3.9%2Fopenapi.yaml&label=Gateway+Admin+-+EE + align: end + + - header: + text: "Security" + type: h2 + columns: + - blocks: + - type: card + config: + title: Secure the Admin API + description: Learn how to secure the Admin API against unwanted access. + icon: /assets/icons/security.svg + cta: + url: /gateway/secure-the-admin-api/ + align: end + - blocks: + - type: card + config: + title: Enable RBAC + description: Use the Admin API to secure {{site.base_gateway}} with Role-Based Access Control. + icon: /assets/icons/lock.svg + cta: + url: /how-to/enable-rbac-with-admin-api/ + align: end + + - header: + type: h2 + text: "Supported content types" + columns: + - blocks: + - type: text + config: | + The Admin API accepts three content types on every endpoint: + - type: feature_table + config: + columns: + - title: Description + key: desc + - title: Example + key: example + features: + - title: | + `application/json` + desc: JSON representation of the data to send. This content type is useful for complex request bodies. + example: | + ```sh + curl -i -X POST http://localhost:8001/routes \ + -H "Content-Type: application/json" \ + -d '{"name": "test-route", "paths": [ "/path/one", "/path/two" ], "service": {"name": "test-service"}}' + ``` + - title: | + `application/x-www-form-urlencoded` + desc: | + Form representation of the data to send. This content type can be used in most cases. + * To specify nested objects us the `.` character. + * To specify array values, you can either send the values in order, or add an index in square brackets. + example: | + ```sh + curl -i -X POST http://localhost:8001/routes \ + -d "name=test-route" \ + -d "paths[]=/path/one" \ + -d "paths[]=/path/two" \ + -d "service.name=test-service" + ``` + - title: | + `multipart/form-data` + desc: | + For representation of the data to send. This content type is useful if you need to send binary data. + + It's similar to `application/x-www-form-urlencoded`, however: + * References to arrays must have indices. + * You can reference files using the `@` prefix. + example: | + ```sh + curl -i -X POST http://localhost:8001/services/plugin-testing/plugins \ + -F "name=pre-function" \ + -F "config.access=@custom-auth.lua" + ``` + + - header: + text: "Frequently Asked Questions" + type: h2 + columns: + - blocks: + - type: faqs + config: + - q: Can I use the Admin API in DB-less mode? + a: | + In DB-less mode, you configure {{site.base_gateway}} declaratively. The Admin API for each {{site.base_gateway}} node functions independently, reflecting the memory state of that particular node. + This is the case because there is no database coordination between nodes. Therefore, the Admin API is mostly read-only. + + When running {{site.base_gateway}} in DB-less mode, the Admin API can only perform tasks related to handling the declarative config: + * [Validating configurations against schemas](/api/gateway/admin-ee/3.9/#/operations/post-schemas-entity-validate) + * [Validating plugin configurations against schemas](/api/gateway/admin-ee/3.9/#/operations/post-schemas-plugins-validate) + * [Reloading the declarative configuration](/api/gateway/admin-ee/3.9/#/operations/post-config) + + - q: How can I send a request for a specific Workspace? + a: | + You can target a specific Workspace by prefixing any endpoint with the Workspace name or ID. For example, you can use the following command to get all services from a Workspace named `SRE`: + ```sh + curl -i -X GET http://localhost:8001/SRE/services + ``` + + If no Workspace is specified, the request applies to the `default` Workspace. diff --git a/app/gateway/secure-the-admin-api.md b/app/gateway/secure-the-admin-api.md index 5b3ef25e4..7a65a094a 100644 --- a/app/gateway/secure-the-admin-api.md +++ b/app/gateway/secure-the-admin-api.md @@ -6,13 +6,102 @@ layout: reference products: - gateway +tools: + - deck + description: placeholder related_resources: - text: "Secure {{site.base_gateway}}" url: /gateway/security/ + - text: "{{site.base_gateway}} Admin API" + url: /admin-api/ + - text: "Enable RBAC with the Admin API" + url: /how-to/enable-rbac-with-admin-api/ --- -@todo +{{site.base_gateway}}’s Admin API provides a RESTful interface for administration and configuration of Gateway Services, Routes, Plugins, Consumers, and credentials. Because this API allows full control of {{site.base_gateway}}, it's important to secure it against unwanted access. This document describes a few possible approaches to securing the Admin API. + +## Network layer access restriction + +Using the `admin_listen` parameter in the [{{site.base_gateway}} configuration](/gateway/configuration/), you can restrict access to the Admin to certain IPs. + +### Minimal listening footprint + +By default, {{site.base_gateway}} only accepts requests from the local interface (`127.0.0.0:8001`). If you change this value, make sure to keep the listening footprint to a minimum to avoid exposing your Admin API to third-parties, which could seriously compromise the security of your whole Kong cluster. For example, avoid using values such as `0.0.0.0:8001`. + +### Layer 3/4 network controls + +In cases where the Admin API must be exposed beyond a local interface, the best practice is to restrict network-layer access as much as possible. Consider an environment in which {{site.base_gateway}} listens on a private network interface, but should only be accessed by a small subset of an IP range. In this case, host-based firewalls (e.g. iptables) are useful in limiting input traffic ranges. For example: + +```sh +# assume that Kong is listening on the address defined below, 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 192.0.2.3:8001 + +# 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 192.0.2.3 -m tcp -p tcp --dport 8001 -j ACCEPT + +# explicitly allow TCP packets on port 8001 from the following addresses +iptables -A INPUT -s 192.0.2.4 -m tcp -p tcp --dport 8001 -j ACCEPT +iptables -A INPUT -s 192.0.2.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. + +## API loopback + +{{site.base_gateway}}’s routing design allows it to serve as a proxy for the Admin API itself. You can use {{site.base_gateway}} to provide fine-grained access control to the Admin API. To do this, you need to bootstrap a new Gateway Service that defines the `admin_listen` address as the Service’s url. + +For example, let’s assume that {{site.base_gateway}}'s `admin_listen` parameter is set to `127.0.0.1:8001`, so it is only available from localhost. The port `8000` is serving proxy traffic, exposed via `myhost.dev:8000`. + +We want to expose Admin API via the url `:8000/admin-api`, in a controlled way. We can do so by creating a Service and Route for it inside `127.0.0.1`: + +{% entity_examples %} +entities: + services: + - name: admin-api + url: http://127.0.0.1:8001 + routes: + - name: admin-api + service: + name: admin-api + paths: + - /admin-api +{% endentity_examples %} + +We can now reach the Admin API through the proxy server: +```sh +curl myhost.dev:8000/admin-api/services +``` + +Once the Service and Route are set up, you can apply security plugins as you would for any API. You can configure [authentication](/plugins/?category=authentication), [IP restriction](/plugins/ip-restriction/), or [access control lists](/plugins/acl/). For example: + +{% entity_examples %} +entities: + plugins: + - name: key-auth + service: admin-api + consumers: + - username: admin + keyauth_credentials: + - key: secret +{% endentity_examples %} + +With this configuration, the Admin API will be available through `/admin-api`, but only for requests containing the `?apikey=secret` query parameter. + +## Custom Nginx configuration + +{{site.base_gateway}} is tightly coupled with Nginx as an HTTP daemon, and can be integrated into environments with custom Nginx configurations. Use cases with complex security and access control requirements can use the full power of Nginx and 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 and complex security controls can be built. + +For more information on integrating Kong into custom Nginx configurations, see the [Nginx configuration directives](/gateway/configuration/). + +## Role-Based Access Control -Use content from https://docs.konghq.com/gateway/latest/production/running-kong/secure-admin-api/ \ No newline at end of file +You can configure [RBAC](/gateway/entities/rbac/) to secure access to the Admin API. RBAC allows for fine-grained control over resource access based on a model of user roles and permissions. Users are assigned to one or more roles, which possess one or more permissions granting or denying access to a particular resource. You can enforce fine-grained control over specific Admin API resources, while scaling to allow complex, case-specific uses. \ No newline at end of file diff --git a/tools/track-docs-changes/config/sources.yml b/tools/track-docs-changes/config/sources.yml index 14f2f1a52..8c32812a6 100644 --- a/tools/track-docs-changes/config/sources.yml +++ b/tools/track-docs-changes/config/sources.yml @@ -299,6 +299,8 @@ app/_landing_pages/gateway/secrets-management.yaml: - app/_src/gateway/kong-enterprise/secrets-management/secrets-rotation.md app/_landing_pages/gateway/authentication.yaml: - app/_src/gateway/kong-plugins/authentication/reference.md +app/_landing_pages/admin-api.yaml: + - app/_src/gateway/admin-api/index_latest.md # references app/deck/distributed-config.md: @@ -330,6 +332,8 @@ app/gateway/cp-dp-communication.md: - app/_src/gateway/production/networking/cp-dp-proxy.md app/konnect/network.md: - app/konnect/network.md +app/gateway/secure-the-admin-api.md: + - app/_src/gateway/production/running-kong/secure-admin-api.md # traffic control app/gateway/traffic-control/proxy.md: