Configure zone proxy authentication

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

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

    The zone token used to identify zone proxies is a that contains:

    • Zone in which zone proxy operates
    • Expiration date of the token (required, 10 years if not specified)
    • Scope as a list of items where the token will be valid (required, egress, ingress if not specified)

    The zone token is signed by a signing key that is autogenerated during the 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:

    which returns something like:

    1. NAME                       AGE
    2. zone-token-signing-key-1   7s

    Generate the token with the REST API:

    1. curl -XPOST \
    2.   -H "Content-Type: application/json" \
    3.   --data '{"zone": "us-east", "validFor": "720h", "scope": ["egress", "ingress"]}' \
    4.   http://localhost:5681/tokens/zone

    or with kumactl:

    1. kumactl generate zone-token \
    2.   --zone us-east \
    3.   --valid-for 720h > /tmp/kuma-zone-proxy-token

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

    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 jwt.io or jwt-cli tool. Here is example of jti

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

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

    1. REVOCATIONS=$(echo '0e120ec9-6b42-495d-9758-07b59fe86fb9' | base64) && echo "apiVersion: v1
    2. kind: Secret
    3. metadata:
    4.   name: zone-token-revocations
    5.   namespace: kuma-system
    6. data:
    7.   value: $REVOCATIONS
    8. type: system.kuma.io/global-secret" | kubectl apply -f -
    1. echo "
    2. type: GlobalSecret
    3. name: zone-token-revocations
    4. data: " | kumactl apply --var revocations=$(echo '0e120ec9-6b42-495d-9758-07b59fe86fb9' | base64) -f -

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

    1. Generate new signing key The signing key is stored as a GlobalSecret with a name that looks like zone-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.

      2. data:
      3.   value: $TOKEN
      4. kind: Secret
      5. metadata:
      6.   name: zone-token-signing-key-2
      7.   namespace: kuma-system
      8. type: system.kuma.io/global-secret
      9. " | kubectl apply -f -

      Check what is the current highest serial number.

      1. kumactl get global-secrets
      2. NAME                       AGE
      3. zone-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

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

    2. Regenerate 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

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

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

    When running in multi-zone mode, we can generate zone tokens only on the global control plane. The zone control plane only has a public key of a signing key to verify tokens.

    You can turn off authentication by setting KUMA_DP_SERVER_AUTH_TYPE to .

    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.