Entitlement Enforcement: Enforce entitlements by header, with a custom denial response - Plugin

Enforce entitlements by header, with a custom denial responsev3.16+

Use this configuration when your API clients pass a customer or tenant identifier in a request header, instead of authenticating as a Kong Gateway Consumer. This is common for machine-to-machine or multi-tenant SaaS traffic where you don’t create a Consumer per customer.

This example also overrides the default response for USAGE_LIMIT_REACHED, so you can return a status code and message that fit your API’s error format instead of the plugin’s defaults.

Prerequisites

Your API clients must pass the customer header on every request you want to enforce entitlements for.

Environment variables

ENTITLEMENT_ACCESS_ENDPOINT: The URL of your entitlement access service endpoint.
ENTITLEMENT_ACCESS_API_TOKEN: The bearer token used to authenticate with the entitlement access endpoint.
CUSTOMER_HEADER: The name of the request header that contains the customer identifier, for example x-customer-id.
FEATURE_KEY: The key identifying the feature to enforce.
USAGE_LIMIT_MESSAGE: The message to return when a customer has reached their usage limit for the feature.
REDIS_HOST: The hostname of your Redis instance used for caching enforcement state.

Set up the plugin

Add this section to your kong.yaml configuration file:

decK

kong.yaml

Copied!

_format_version: "3.0"
plugins:
  - name: entitlement-enforcement
    config:
      entitlement_access_endpoint: ${{ env "DECK_ENTITLEMENT_ACCESS_ENDPOINT" }}
      api_token: ${{ env "DECK_ENTITLEMENT_ACCESS_API_TOKEN" }}
      customer:
        look_up_value_in: header
        field: ${{ env "DECK_CUSTOMER_HEADER" }}
      feature:
        key: ${{ env "DECK_FEATURE_KEY" }}
      response_codes:
        USAGE_LIMIT_REACHED:
          http_status: 403
          message: ${{ env "DECK_USAGE_LIMIT_MESSAGE" }}
      redis:
        host: ${{ env "DECK_REDIS_HOST" }}

Make the following request:

curl -i -X POST http://localhost:8001/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
controlPlaneId: The id of the control plane.

See the Konnect Control Planes Config API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: entitlement-enforcement
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: 'true'
config:
  entitlement_access_endpoint: '$ENTITLEMENT_ACCESS_ENDPOINT'
  api_token: '$ENTITLEMENT_ACCESS_API_TOKEN'
  customer:
    look_up_value_in: header
    field: '$CUSTOMER_HEADER'
  feature:
    key: '$FEATURE_KEY'
  response_codes:
    USAGE_LIMIT_REACHED:
      http_status: 403
      message: '$USAGE_LIMIT_MESSAGE'
  redis:
    host: '$REDIS_HOST'
plugin: entitlement-enforcement
" | kubectl apply -f -

Copied!

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Copied!

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_entitlement_enforcement" "my_entitlement_enforcement" {
  enabled = true

  config = {
    entitlement_access_endpoint = var.entitlement_access_endpoint
    api_token = var.entitlement_access_api_token

    customer = {
      look_up_value_in = "header"
      field = var.customer_header
    }

    feature = {
      key = var.feature_key
    }

    response_codes = {

      USAGE_LIMIT_REACHED = {
        http_status = 403
        message = var.usage_limit_message
      }
    }

    redis = {
      host = var.redis_host
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
}

Copied!

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "entitlement_access_endpoint" {
  type = string
}
variable "entitlement_access_api_token" {
  type = string
}
variable "customer_header" {
  type = string
}
variable "feature_key" {
  type = string
}
variable "usage_limit_message" {
  type = string
}
variable "redis_host" {
  type = string
}

Copied!

Add this section to your kong.yaml configuration file:

decK

kong.yaml

Copied!

_format_version: "3.0"
plugins:
  - name: entitlement-enforcement
    service: serviceName|Id
    config:
      entitlement_access_endpoint: ${{ env "DECK_ENTITLEMENT_ACCESS_ENDPOINT" }}
      api_token: ${{ env "DECK_ENTITLEMENT_ACCESS_API_TOKEN" }}
      customer:
        look_up_value_in: header
        field: ${{ env "DECK_CUSTOMER_HEADER" }}
      feature:
        key: ${{ env "DECK_FEATURE_KEY" }}
      response_codes:
        USAGE_LIMIT_REACHED:
          http_status: 403
          message: ${{ env "DECK_USAGE_LIMIT_MESSAGE" }}
      redis:
        host: ${{ env "DECK_REDIS_HOST" }}

Make sure to replace the following placeholders with your own values:

serviceName|Id: The id or name of the service the plugin configuration will target.

Make the following request:

curl -i -X POST http://localhost:8001/services/{serviceName|Id}/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

serviceName|Id: The id or name of the service the plugin configuration will target.

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/services/{serviceId}/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
controlPlaneId: The id of the control plane.
serviceId: The id of the service the plugin configuration will target.

See the Konnect Control Planes Config API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: entitlement-enforcement
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  entitlement_access_endpoint: '$ENTITLEMENT_ACCESS_ENDPOINT'
  api_token: '$ENTITLEMENT_ACCESS_API_TOKEN'
  customer:
    look_up_value_in: header
    field: '$CUSTOMER_HEADER'
  feature:
    key: '$FEATURE_KEY'
  response_codes:
    USAGE_LIMIT_REACHED:
      http_status: 403
      message: '$USAGE_LIMIT_MESSAGE'
  redis:
    host: '$REDIS_HOST'
plugin: entitlement-enforcement
" | kubectl apply -f -

Copied!

Next, apply the KongPlugin resource by annotating the service resource:

kubectl annotate -n kong service SERVICE_NAME konghq.com/plugins=entitlement-enforcement

Copied!

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Copied!

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_entitlement_enforcement" "my_entitlement_enforcement" {
  enabled = true

  config = {
    entitlement_access_endpoint = var.entitlement_access_endpoint
    api_token = var.entitlement_access_api_token

    customer = {
      look_up_value_in = "header"
      field = var.customer_header
    }

    feature = {
      key = var.feature_key
    }

    response_codes = {

      USAGE_LIMIT_REACHED = {
        http_status = 403
        message = var.usage_limit_message
      }
    }

    redis = {
      host = var.redis_host
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  service = {
    id = konnect_gateway_service.my_service.id
  }
}

Copied!

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "entitlement_access_endpoint" {
  type = string
}
variable "entitlement_access_api_token" {
  type = string
}
variable "customer_header" {
  type = string
}
variable "feature_key" {
  type = string
}
variable "usage_limit_message" {
  type = string
}
variable "redis_host" {
  type = string
}

Copied!

Add this section to your kong.yaml configuration file:

decK

kong.yaml

Copied!

_format_version: "3.0"
plugins:
  - name: entitlement-enforcement
    route: routeName|Id
    config:
      entitlement_access_endpoint: ${{ env "DECK_ENTITLEMENT_ACCESS_ENDPOINT" }}
      api_token: ${{ env "DECK_ENTITLEMENT_ACCESS_API_TOKEN" }}
      customer:
        look_up_value_in: header
        field: ${{ env "DECK_CUSTOMER_HEADER" }}
      feature:
        key: ${{ env "DECK_FEATURE_KEY" }}
      response_codes:
        USAGE_LIMIT_REACHED:
          http_status: 403
          message: ${{ env "DECK_USAGE_LIMIT_MESSAGE" }}
      redis:
        host: ${{ env "DECK_REDIS_HOST" }}

Make sure to replace the following placeholders with your own values:

routeName|Id: The id or name of the route the plugin configuration will target.

Make the following request:

curl -i -X POST http://localhost:8001/routes/{routeName|Id}/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

routeName|Id: The id or name of the route the plugin configuration will target.

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/routes/{routeId}/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
controlPlaneId: The id of the control plane.
routeId: The id of the route the plugin configuration will target.

See the Konnect Control Planes Config API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: entitlement-enforcement
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  entitlement_access_endpoint: '$ENTITLEMENT_ACCESS_ENDPOINT'
  api_token: '$ENTITLEMENT_ACCESS_API_TOKEN'
  customer:
    look_up_value_in: header
    field: '$CUSTOMER_HEADER'
  feature:
    key: '$FEATURE_KEY'
  response_codes:
    USAGE_LIMIT_REACHED:
      http_status: 403
      message: '$USAGE_LIMIT_MESSAGE'
  redis:
    host: '$REDIS_HOST'
plugin: entitlement-enforcement
" | kubectl apply -f -

Copied!

Next, apply the KongPlugin resource by annotating the httproute or ingress resource:

kubectl annotate -n kong httproute  konghq.com/plugins=entitlement-enforcement

Copied!

kubectl annotate -n kong ingress  konghq.com/plugins=entitlement-enforcement

Copied!

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Copied!

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_entitlement_enforcement" "my_entitlement_enforcement" {
  enabled = true

  config = {
    entitlement_access_endpoint = var.entitlement_access_endpoint
    api_token = var.entitlement_access_api_token

    customer = {
      look_up_value_in = "header"
      field = var.customer_header
    }

    feature = {
      key = var.feature_key
    }

    response_codes = {

      USAGE_LIMIT_REACHED = {
        http_status = 403
        message = var.usage_limit_message
      }
    }

    redis = {
      host = var.redis_host
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  route = {
    id = konnect_gateway_route.my_route.id
  }
}

Copied!

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "entitlement_access_endpoint" {
  type = string
}
variable "entitlement_access_api_token" {
  type = string
}
variable "customer_header" {
  type = string
}
variable "feature_key" {
  type = string
}
variable "usage_limit_message" {
  type = string
}
variable "redis_host" {
  type = string
}

Copied!

Add this section to your kong.yaml configuration file:

decK

kong.yaml

Copied!

_format_version: "3.0"
plugins:
  - name: entitlement-enforcement
    consumer: consumerName|Id
    config:
      entitlement_access_endpoint: ${{ env "DECK_ENTITLEMENT_ACCESS_ENDPOINT" }}
      api_token: ${{ env "DECK_ENTITLEMENT_ACCESS_API_TOKEN" }}
      customer:
        look_up_value_in: header
        field: ${{ env "DECK_CUSTOMER_HEADER" }}
      feature:
        key: ${{ env "DECK_FEATURE_KEY" }}
      response_codes:
        USAGE_LIMIT_REACHED:
          http_status: 403
          message: ${{ env "DECK_USAGE_LIMIT_MESSAGE" }}
      redis:
        host: ${{ env "DECK_REDIS_HOST" }}

Make sure to replace the following placeholders with your own values:

consumerName|Id: The id or name of the consumer the plugin configuration will target.

Make the following request:

curl -i -X POST http://localhost:8001/consumers/{consumerName|Id}/plugins/ \
    --header "Accept: application/json" \
    --header "Content-Type: application/json" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

consumerName|Id: The id or name of the consumer the plugin configuration will target.

Make the following request:

curl -X POST https://{region}.api.konghq.com/v2/control-planes/{controlPlaneId}/core-entities/consumers/{consumerId}/plugins/ \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "entitlement-enforcement",
      "config": {
        "entitlement_access_endpoint": "'$ENTITLEMENT_ACCESS_ENDPOINT'",
        "api_token": "'$ENTITLEMENT_ACCESS_API_TOKEN'",
        "customer": {
          "look_up_value_in": "header",
          "field": "'$CUSTOMER_HEADER'"
        },
        "feature": {
          "key": "'$FEATURE_KEY'"
        },
        "response_codes": {
          "USAGE_LIMIT_REACHED": {
            "http_status": 403,
            "message": "'$USAGE_LIMIT_MESSAGE'"
          }
        },
        "redis": {
          "host": "'$REDIS_HOST'"
        }
      }
    }
    '

Copied!

Make sure to replace the following placeholders with your own values:

region: Geographic region where your Kong Konnect is hosted and operates.
KONNECT_TOKEN: Your Personal Access Token (PAT) associated with your Konnect account.
controlPlaneId: The id of the control plane.
consumerId: The id of the consumer the plugin configuration will target.

See the Konnect Control Planes Config API reference to learn about region-specific URLs and personal access tokens.

echo "
apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: entitlement-enforcement
  namespace: kong
  annotations:
    kubernetes.io/ingress.class: kong
config:
  entitlement_access_endpoint: '$ENTITLEMENT_ACCESS_ENDPOINT'
  api_token: '$ENTITLEMENT_ACCESS_API_TOKEN'
  customer:
    look_up_value_in: header
    field: '$CUSTOMER_HEADER'
  feature:
    key: '$FEATURE_KEY'
  response_codes:
    USAGE_LIMIT_REACHED:
      http_status: 403
      message: '$USAGE_LIMIT_MESSAGE'
  redis:
    host: '$REDIS_HOST'
plugin: entitlement-enforcement
" | kubectl apply -f -

Copied!

Next, apply the KongPlugin resource by annotating the KongConsumer resource:

kubectl annotate -n kong kongconsumer CONSUMER_NAME konghq.com/plugins=entitlement-enforcement

Copied!

Prerequisite: Configure your Personal Access Token

terraform {
  required_providers {
    konnect = {
      source  = "kong/konnect"
    }
  }
}

provider "konnect" {
  personal_access_token = "$KONNECT_TOKEN"
  server_url            = "https://us.api.konghq.com/"
}

Copied!

Add the following to your Terraform configuration to create a Konnect Gateway Plugin:

resource "konnect_gateway_plugin_entitlement_enforcement" "my_entitlement_enforcement" {
  enabled = true

  config = {
    entitlement_access_endpoint = var.entitlement_access_endpoint
    api_token = var.entitlement_access_api_token

    customer = {
      look_up_value_in = "header"
      field = var.customer_header
    }

    feature = {
      key = var.feature_key
    }

    response_codes = {

      USAGE_LIMIT_REACHED = {
        http_status = 403
        message = var.usage_limit_message
      }
    }

    redis = {
      host = var.redis_host
    }
  }

  control_plane_id = konnect_gateway_control_plane.my_konnect_cp.id
  consumer = {
    id = konnect_gateway_consumer.my_consumer.id
  }
}

Copied!

This example requires the following variables to be added to your manifest. You can specify values at runtime by setting TF_VAR_name=value.

variable "entitlement_access_endpoint" {
  type = string
}
variable "entitlement_access_api_token" {
  type = string
}
variable "customer_header" {
  type = string
}
variable "feature_key" {
  type = string
}
variable "usage_limit_message" {
  type = string
}
variable "redis_host" {
  type = string
}

Copied!

Entitlement Enforcement

Enforce entitlements by header, with a custom denial responsev3.16+

Prerequisites

Environment variables

Set up the plugin

Help us make these docs great!

Still need help?