Kong Manager configuration

If you’re running Kong Gateway on-prem with a database (either in traditional or hybrid mode), you can enable Kong Gateway’s graphical user interface (GUI), Kong Manager.

To enable Kong Manager, set the following Kong Manager parameters in kong.conf, then restart Kong Gateway:

If you’re running Kong Gateway in Docker, you can use the following example, making sure to replace the KONG_CONTAINER_ID with your own container:

docker exec -i $KONG_CONTAINER_ID /bin/sh -c \
"export KONG_ADMIN_GUI_PATH='/'; \
export KONG_ADMIN_GUI_URL='http://localhost:8002/manager'; \
kong reload; \
exit"

This example uses the default Kong Manager path and URL.

Note: If you run the Kong Gateway quickstart script, Kong Manager is automatically enabled.

To verify that Kong Manager is running, access it on port 8002 at the default URL: http://localhost:8002/workspaces.

By default, Kong Manager starts up without authentication (see admin_gui_auth), and it assumes that the Admin API is available on port 8001 of the same host that serves Kong Manager.

Here are some common configuration scenarios for Kong Manager:

To enable authentication for Kong Manager, configure the following properties (admin_gui_auth_conf is optional and enforce_rbac must be set to on):

admin_gui_session_conf = { "cookie_name": "kookie", \
                           "secret": "changeme" }

Important: When Kong Manager authentication is enabled, RBAC must be enabled to enforce authorization rules. Otherwise, anyone who can log in to Kong Manager can perform any operation available on the Admin API.

TLS Certificates

By default, if Kong Manager’s URL is accessed over HTTPS without a certificate issued by a CA, it will receive a self-signed certificate that modern web browsers will not trust. This prevents the application from accessing the Admin API.

To serve Kong Manager over HTTPS, use a trusted certificate authority to issue TLS certificates and have the resulting .crt and .key files ready for the next step.

1. Move .crt and .key files into the desired directory of the Kong Gateway node.

2. Point admin_gui_ssl_cert and admin_gui_ssl_cert_key at the absolute paths of the certificate and key.

   admin_gui_ssl_cert = ./test.crt
   admin_gui_ssl_cert_key = ./test.key
   

3. Ensure that admin_gui_url is prefixed with https to use TLS. For example:

   admin_gui_url = https://YOUR-DOMAIN.com:8445
   

Using https://localhost

If you’re serving Kong Manager on localhost, you might want to use HTTP as the protocol. If you’re also using RBAC, set cookie_secure=false in admin_gui_session_conf. Creating TLS certificates for localhost requires more effort and configuration, so you should only use TLS when:

• Data is in transit between hosts
• You’re testing an application with mixed content (which Kong Manager doesn’t use)

External CAs cannot provide a certificate since no one uniquely owns localhost, nor is it rooted in a top-level domain (for example, .com, .org). Likewise, self-signed certificates won’t be trusted in modern browsers. Instead, you must use a private CA that allows you to issue your own certificates. Also, ensure that the SSL state is cleared from the browser after testing to prevent stale certificates from interfering with future access to localhost.

To configure Kong Manager to be accessible from multiple domains, you can list the domains as comma-separated values in the admin_gui_url parameter in your Kong configuration. For example:

admin_gui_url = http://localhost:8002, http://127.0.0.1:8002

If the admin_gui_path is also set, update the Kong configuration:

admin_gui_url = http://localhost:8002/manager, http://127.0.0.1:8002/manager
admin_gui_path = /manager

Make sure that each domain has proper DNS records and that the Kong Gateway instance is accessible from all specified domains.

If your setup involves multiple domains or subdomains, we recommend removing the cookie_domain setting in the admin_gui_session_conf or admin_gui_auth_conf. When cookie_domain is not specified, cookies are set for the domain initiated in the request if admin_gui_api_url is not specified. This allows the browser to manage cookies correctly for each domain independently, avoiding conflicts or scope issues.

For example, a request to gui.konghq.com and other-gui.example.com will produce cookies for gui.konghq.com and other-gui.example.com respectively, instead of the root-level konghq.com domain when cookie_domain isn’t specified:

admin_gui_url = http://gui.konghq.com, http://other-gui.example.com
admin_gui_session_conf = {"secret":"Y29vbGJlYW5z","storage":"kong","cookie_secure":false} # omitted `cookie_domain`

Or, both requests to gui.konghq.com and other-gui.konghq.com will receive cookies for konghq.com, which makes the cookie shared across all subdomains besides konghq.com itself. This increases the cookie’s scope, which may lead to unintended side effects or security risks:

admin_gui_url = http://gui.konghq.com, http://other-gui.konghq.com
admin_gui_session_conf = {"secret":"Y29vbGJlYW5z","storage":"kong","cookie_secure":false,"cookie_domain":"konghq.com"}

You can customize various visual aspects of Kong Manager, like header and footer text and colors. Use the following kong.conf parameters to customize Kong Manager:

The Session configuration is secure by default, which may require alteration if using HTTP or different domains for the Admin API and Kong Manager. The encrypted session data may be stored either in Kong Gateway or the cookie itself. For more information on the Session plugin, review the plugin documentation