We launched new developer portal. For the latest documentation visit developer.cloudentity.com

Protecting APIs exposed on Kong API Gateways

Learn how to apply access control to protect APIs deployed behind Kong API Gateways. Install necessary plugins in your Gateway. Deploy ACP's Kong Authorizer to enforce policies applied to your discovered APIs.

About Kong Gateways

KongHQ provides you with two versions of a self-hosted Kong Gateway: Kong Gateway (Enterprise) and Kong Gateway (Open-sourced). Both gateways are designed to be a part of decentralized architectures that leverage automation and modern GitOps practices. With their features, you can:

  • Decentralize applications/services and transition to microservices

  • Identify API-related anomalies and threats

  • Secure and govern your APIs and services

With Authorization Control Plane and its Kong Authorizer and plugin, you can successfully integrate your Kong Gateway with Cloudentity solutions for authorization no matter whether it is an Enterprise or Open-Sourced Kong Gateway or which deployment type you chose for your gateway.

Learn more

You can learn more about ACP integration with Kong Gateways by checking out the Dynamic Authorization and API Discovery for Kong documentation.

Integration components

Kong integration components

In the diagram above, you can see that ACP is responsible for OAuth authorization for client applications and providing them with access tokens. It also provides policies and keys to the Kong Authorizer. Behind the Kong Gateway, you can have a number of services deployed that are protected by the Kong Authorizer. You need to have the ACP Kong Plugin attached to the service that you wish to protect. The plugin is responsible for calling the /authorize endpoint of the Kong Authorizer. It also allows the authorizer to fetch Kong Gateway services that can be later on passed to ACP so that you are able to assign authorization policies to the APIs of your choice.

When a client application calls a protected service and its request contains an access token dervied from ACP, Kong Gateway invokes the ACP Kong Plugin so that it can communicate with the Kong Authorizer to authorize the client’s request. The authorizer validates all authorization policies that it fetched from ACP for the given API. After a successful authorization, the Kong Gateway executes the API from the protected service.

The Kong Gateway itself can also be protected with RBAC, Basic Auth, or OAuth 2.0, depending on your Kong subscription and security requirements. For details, read Authenticating to the Kong Admin API.

ACP Kong Plugin

ACP Kong plugin is a LuaRocks plugin that is executed during the HTTP request/response lifecycle.

This plugin, in particular, is responsible for authorizing access to an upstream service. When you add the ACP Kong plugin to your service, every request made by a client application to this service runs the plugin. The plugin assembles the request data and sends a query to ACP’s Kong Authorizer that is responsible for comparing the request against an authorization policy defined for a given endpoint. After policy validation, the authorizer can respond whether the request should be allowed or denied.

Integration with Kong Gateways

KongHQ provides several possibilities for deployment of their gateway, but you can integrate ACP and its Kong Authorizer with Kong Gateway no matter which deployment type you chose for your gateway. The requirement is that your Kong Authorizer deployment can communicate successfully with your Kong Gateway, whether it is, for example, deployed in a Docker container or in Kubernetes with Helm Charts.

This article is based on Docker container deployment both for the Kong Gateway and the Kong Authorizer. Your ACP instance, however, can be deployed anywhere. It can be, for example, ACP SaaS solution, Docker deployment, or kubernetes deployment with Helm Charts.

Kong Authorizer Helm Chart

You can find a Helm Chart for the Kong Authorizer in a dedicated ACP Helm Charts GitHub repository.

To integrate your Kong Gateway with ACP and Kong Authorizer, you will install the ACP Kong plugin for your Kong Gateway and assign it to your service or a particular route. Then, you will create a Kong Authorizer in your ACP instance and deploy it to a Docker container. Once the authorizer successfully discover your services exposed by your gateway, you will be able to apply access control to your APIs.


  1. Docker v1.19+ and Docker Compose installed.

  2. Access to an ACP SaaS tenant

  3. Service to be protected by Kong Authorizer is deployed (this instruction allows you to deploy a mock service for testing purposes).

Build Kong with ACP plugin

  1. Clone the docker-kong project.

  2. Add the following steps to your Kong Gateway’s Dockerfile to make sure the kong-acp-plugin is installed.

    USER root
    RUN  luarocks install kong-plugin-acp

    As a result, the content in the customize/Dockerfile file should look as follows:

    FROM kong/kong-gateway: AS build
    ARG TEMPLATE=empty_file
    ARG ROCKS_DIR=empty_file
    COPY $TEMPLATE /plugins/custom_nginx.conf
    COPY $ROCKS_DIR /rocks-server
    COPY packer.lua /packer.lua
    USER root
    RUN /usr/local/openresty/luajit/bin/luajit /packer.lua -- "$INJECTED_PLUGINS"
    FROM kong/kong-gateway:
    COPY --from=build /plugins /plugins
    USER root
    RUN  luarocks install kong-plugin-acp
    RUN /plugins/install_plugins.sh
    HEALTHCHECK --interval=10s --timeout=10s --retries=10 CMD kong health
    USER kong
  3. In terminal, navigate to the /customize directory within your cloned project and build your image with the following command:

    docker build \
    --build-arg PLUGINS="kong-http-to-https,kong-upstream-jwt,kong-plugin-acp" \
    --tag "kong-acp" .


    As you can see in the command above, the kong-plugin-acp is included in the PLUGINS build argument for your image. You can, of course, define more plugins for your deployment here. After the scripts from the Dockerfile are executed, the kong-plugin-acp is installed within your image and kong-plugin-acp is present in the list of your plugins in the kong.conf file for your Docker deployment.

Once your image is ready and built, you can deploy it to a container, expose services, and add routes to them.

Deploy Kong with ACP plugin

Use the following Kong documents to quickly deploy Kong Gateway and attach a service and route to it.

  • For detailed instructions on how to run Docker images for Kong Gateway working with a PostgreSQL database, visit Install Kong Gateway on Docker

    If you chose to build your image as shown in the examples above, keep in mind that the image from the example above is tagged kong-acp, so please adapt the example from Kong docs accordingly. Also, with the instructions from KongHQ you create a network for your Docker containers. Keep in mind that all componenets - Kong Gateway, Kong Authorizer, as well as your service, must run on the same network.

  • To learn how to expose services and add routes on a mock service, see the Expose your Services with Kong Gateway documentation. If you already have a service, make sure it’s on the correct Docker network.

Kong Docker images

For technical details on Docker images for Kong Gateway, visit:

Assign ACP Kong Plugin to your service

Having deployed Kong Gateway and a service, it’s time to assign the ACP Kong Plugin to your service, use the Kong Gateway Admin API:

curl -sSk -X POST https://{ADMIN-URL}/services/{NAME-OF-YOUR-SERVICE}/plugins \
     --data 'name=acp' \
     --data 'config.api_group_id={ID-OF-YOUR-API-GROUP}' \
     --data 'config.auth_url=https://kong-authorizer:9003/authorize'

Protected Kong Admin API

If Kong Admin API is protected, the request must be correctly authenticated. For more information, read Authenticating to the Kong Admin API.

As you can see, the curl request contains the following variables:

  • {ADMIN-URL} which should point to the URL of your Kong Gateway Admin API

  • {NAME-OF-YOUR-SERVICE} which should point to the name of the service to which you wish to assign the plugin

  • {ID-OF-YOUR-API-GROUP} which should point to the identifier of your API group in Kong Gateway

The request also contains the --data 'name=acp' argument, which is assigns the acp plugin to the service. Additionally, it contains also the --data 'config.auth_url=https://kong-authorizer:9003/authorize' argument which points to the URL under which your Kong Authorizer will be running.

Below, you can find an example of a request that assigns the acp plugin to an httpbin service exposed by a locally deployed Kong Gateway:

curl -sSk -X POST http://localhost:8001/services/httpbin-service/plugins \
     --data 'name=acp' \
     --data 'config.api_group_id=httpbin-service' \
     --data 'config.auth_url=https://kong-authorizer:9003/authorize'

Declarative configuration for DB-less setup

If your Kong Gateway is running without a database, you can use declarative configuration for your service to assign the acp plugin to your service as illustrated below:

- name: httpbin-service
   url: https://httpbin.org
   - name: anything
      hosts: [ "httpbin.org" ]
      paths: [ "/anything" ]
      methods: [ "GET", "PATCH", "PUT", "POST", "DELETE" ]
      strip_path: false
   - name: acp
      api_group_id: httpbin-service
      auth_url: https://kong-authorizer:9003/authorize

Create Kong Authorizer

  1. In your ACP tenant, go to the workspace of your choice.

  2. Select Enforcement > Authorizers > CREATE GATEWAY > Kong.

  3. Provide a name and a description for your Kong Authorizer.

  4. Optionally, enable the Create and bind services automatically check box.


    When enabled, all services protected by your Kong Authorizer instance are discovered and added to the ACP service list automatically when the Kong authorizer is connected to ACP. Otherwise, you need to add them manually.

  5. Follow the Quick Start instruction. Download the package for your Authorizer and check the instructions in the section below.

Deploy Kong Authorizer

  1. Unzip the package with the downloaded Kong Authorizer.

  2. In the .env file, set the KONG_ADMIN_URL to the URL of your Kong Admin API.


    If you are testing it locally in your Docker deployment, the URL contains the name of the container where your Kong Gateway is running and the port number like shown below:


    Note that, by default, the port for HTTPS connection to the Kong Admin API is 8444.

  3. In the terminal, navigate to the directory with your Kong Authorizer and execute the following commands:

    cat credentials.txt | docker login docker.cloudentity.io --username acp --password-stdin


    docker-compose up

    The first command logins to Cloudentity docker with the credentials provided in the credentials.txt file in your Kong Authorizer package.

    The docker-compose up spins up a Docker container with the Kong Authorizer for you. In the logs for the Kong Authorizer, you should see that it starts the authorizer reload. At this point, however, your authorizer is not yet running in the same network as your Kong Gateway, so it is not possible for the authorizer to communicate with the gateway.

  4. Connect your authorizer to the same network that your Kong Gateway uses.

    In general, you can use a method of your choice to connect your authorizer to the network. You can, for example, execute the following command when the container with your Kong Authorizer is running:

    docker network connect {network} {container}

    For example: docker network kong-network 1babdf8b72a6


    Once the authorizer is successfully assigned to the same network as your gateway, you can see in the authorizer’s logs that the authorization configuration was reloaded.

    In ACP APIs Management View, you can see APIs that were discovered by your Kong Authorizer. You can now apply access control to them.

Apply a sample policy

  1. In ACP, create a policy.

  2. Go to Enforcement > APIs > AUTHORIZATION.

  3. Select a service protected by the Kong Authorizer and any API with authorization status Unrestricted.

  4. In the Edit API popup window, select Policy from the list and click Update to proceed.


You have successfully assigned a policy to your API.

Test integration

To test if your integration was successful and that your APIs are protected, you can, for example, create a simple Cloudentity or REGO policy that will always pass. Call your protected endpoint and check if the response is successful.

curl -i --request GET http://localhost:8000/anything

If yes, change your policy so that it blocks APIs. The next request to your protected endpoint should be blocked with the unauthorized access error.