You are browsing documentation for a version of Kuma that is not the latest release.

Looking for even older versions? Learn more.

Zone Ingress authentication

To obtain a configuration from the control-plane, a zone ingress must authenticate itself. There are several authentication methods availble.

Service Account Token

On Kubernetes, A zone-ingress proxy proves its identity by leveraging the ServiceAccountToken that is mounted in every pod.

Zone Ingress token

On Universal, a zone-ingress proxy must be explicitly configured with a unique security token (Zone Ingress token) that will be used to prove its identity.

The data plane proxy token is a JWT token that contains:

  • Zone in which zone ingress operates
  • Expiration date of the token (required, 10 years if not specified)

The Zone Ingress token is signed by a signing key that is autogenerated on first start of the control plane. Tokens are never stored in the control plane, the only thing that is stored are signing keys that are used to verify if a token is valid. The signing key is RSA256 encrypted.

You can check for the signing key:

kumactl get global-secrets

which returns something like:

NAME                               AGE
zone-ingress-token-signing-key-1   7s


Generate the token with the REST API:

curl -XPOST \
  -H "Content-Type: application/json" \
  --data '{"zone": "us-east", "validFor": "720h"}' \

or with kumactl:

kumactl generate zone-ingress-token \
  --zone us-east \
  --valid-for 720h > /tmp/kuma-ingress-token

The token should be stored in a file and then passed when you start kuma-dp:

kuma-dp run \
  --proxy-type=ingress \
  --cp-address= \

You can also pass the token as a KUMA_DATAPLANE_RUNTIME_TOKEN environment variable.

Token Revocation

Kuma does not keep the list of issued tokens. Whenever the single token is compromised, we can add it to revocation list, so it’s no longer valid.

Every token has its own ID which is available in payload under jti key. You can extract ID from token using or jwt-cli tool. Here is example of jti


Specify list of revoked IDs separated by , and store it as GlobalSecret named zone-ingress-token-revocations

REVOCATIONS=$(echo '0e120ec9-6b42-495d-9758-07b59fe86fb9' | base64) && echo "apiVersion: v1
kind: Secret
  name: zone-ingress-token-revocations
  namespace: kuma-system
type:" | kubectl apply -f -

Signing key rotation

If the signing key is compromised, we must rotate it and all the tokens that was signed by it.

  1. Generate new signing key The signing key is stored as a GlobalSecret with a name that looks like zone-ingress-token-signing-key-{serialNumber}.

    Make sure to generate the new signing key with a serial number greater than the serial number of the current signing key.

    Check what is the current highest serial number.

       kubectl get secrets -n kuma-system --field-selector=''
       NAME                               TYPE                           DATA   AGE
       zone-ingress-token-signing-key-1   1      25m

    In this case, the highest serial number is 1. Generate a new signing key with a serial number of 2

       TOKEN="$(kumactl generate signing-key)" && echo "
       apiVersion: v1
         value: $TOKEN
       kind: Secret
         name: zone-ingress-token-signing-key-2
         namespace: kuma-system
       " | kubectl apply -f -
  2. Regenerate tokens Create new Zone Ingress tokens. These tokens are automatically created with the signing key that’s assigned the highest serial number, so they’re created with the new signing key. At this point, tokens signed by either new or old signing key are valid.

  3. Remove the old signing key

       kubectl delete secret zone-ingress-token-signing-key-1 -n kuma-system

    All new connections to the control plane now require tokens signed with the new signing key.


When running in multizone, mode we can generate Zone Ingress token both on global and zone control plane. If the deployment pipeline is configured to generate data plane proxy token before running the proxy, it can rely on the Zone CP. This way Global CP is not a single point of failure.


You can turn off authentication by setting KUMA_DP_SERVER_AUTH_TYPE to none.

You should not disable authentication between the control plane and the data plane proxies in production. Disabling means that any data plane proxy can impersonate any service.

Last Updated: 1/16/2023, 13:14:43 PM