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 authenticates 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 token that will be used to prove its identity.

The zone ingress token is a JWT token that contains:

• Zone in which the 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

Global vs zone control plane

We can generate the zone ingress token on both global and zone control planes. If the deployment pipeline is configured to generate the zone ingress token before running the proxy, it can rely on the zone CP. This way the global CP is not a single point of failure.

Usage

Generate the token with the REST API:

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

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 \
  --dataplane-file=ingress.yaml
  --cp-address=https://127.0.0.1:5678 \
  --dataplane-token-file=/tmp/kuma-ingress-token

You can also pass the token by setting the KUMA_DATAPLANE_RUNTIME_TOKEN environment variable.

Token Revocation

Kuma does not keep the list of issued tokens. Whenever a single token is compromised, we can add it to revocation list so that it becomes invalid.

Every token has its own ID which is available in the JWT payload under the jti key. You can extract this ID from the token using jwt.io or the jwt-cli tool.

Here is an example of a jti:

0e120ec9-6b42-495d-9758-07b59fe86fb9

Specify the 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
metadata:
  name: zone-ingress-token-revocations
  namespace: kuma-system
data:
  value: $REVOCATIONS
type: system.kuma.io/global-secret" | kubectl apply -f -

echo "
type: GlobalSecret
name: zone-ingress-token-revocations
data: " | kumactl apply --var revocations=$(echo '0e120ec9-6b42-495d-9758-07b59fe86fb9' | base64) -f -

Signing key rotation

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

1. Generate a 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.

   • Kubernetes
   • Universal

   Check what the current highest serial number is:

      kubectl get secrets -n kuma-system --field-selector='type=system.kuma.io/global-secret'
      NAME                               TYPE                           DATA   AGE
      zone-ingress-token-signing-key-1   system.kuma.io/global-secret   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
      data:
        value: $TOKEN
      kind: Secret
      metadata:
        name: zone-ingress-token-signing-key-2
        namespace: kuma-system
      type: system.kuma.io/global-secret
      " | kubectl apply -f -

   Check what the current highest serial number is:

      kumactl get global-secrets
      NAME                             AGE
      zone-ingress-token-signing-key-1   36m

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

      echo "
      type: GlobalSecret
      name: zone-ingress-token-signing-key-2
      data: " | kumactl apply --var key=$(kumactl generate signing-key) -f -

2. Create new zone ingress tokens. These tokens are automatically created with the signing key that’s assigned the highest serial number. In this case, that will be the new signing key. At this point, tokens signed by either the new or old signing key are valid.

3. Remove the old signing key:

   • Kubernetes
   • Universal

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

      kumactl delete global-secret zone-ingress-token-signing-key-1

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

None

You can turn off authentication by setting KUMA_DP_SERVER_AUTH_TYPE to none.