Careful!
You are browsing documentation for a version of Kuma that is not the latest release.
Looking for even older versions? Learn more.
Zone Egress authentication
To obtain a configuration from the control plane, a zone egress must authenticate itself. There are several authentication methods available.
Service Account Token
On Kubernetes, A ZoneEgress proxy proves its identity by leveraging the ServiceAccountToken that is mounted in every pod.
Zone Token
On Universal, a ZoneEgress proxy must be explicitly configured with a unique
security token (Zone token) with appropriate scope (egress
), that will be used
to prove its identity.
The zone token used to identify zone egresses is a JWT token that contains:
- Zone in which zone egress 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
if not specified)
A zone token can currently be used only to identify zone egresses, which means
the only valid scope is egress
. In the future zone tokens will be used also
to identify data plane proxies (scope: dataplane
) and zone ingresses
(scope: ingress
).
When this happens, zone ingress tokens and dataplane tokens will become deprecated.
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:
kumactl get global-secrets
which returns something like:
NAME AGE
zone-token-signing-key-1 7s
Usage
Generate the token with the REST API:
curl -XPOST \
-H "Content-Type: application/json" \
--data '{"zone": "us-east", "validFor": "720h", "scope": ["egress"]}' \
http://localhost:5681/tokens/zone
or with kumactl
:
kumactl generate zone-token \
--zone us-east \
--scope egress \
--valid-for 720h > /tmp/kuma-egress-token
The token should be stored in a file and then passed when you start kuma-dp
:
kuma-dp run \
--proxy-type=egress \
--dataplane-file=egress.yaml
--cp-address=https://127.0.0.1:5678 \
--dataplane-token-file=/tmp/kuma-egress-token
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 jwt.io or
jwt-cli
tool.
Here is example of jti
0e120ec9-6b42-495d-9758-07b59fe86fb9
Specify list of revoked IDs separated by ,
and store it as GlobalSecret
named zoneegress-token-revocations
REVOCATIONS=$(echo '0e120ec9-6b42-495d-9758-07b59fe86fb9' | base64) && echo "apiVersion: v1
kind: Secret
metadata:
name: zone-token-revocations
namespace: kuma-system
data:
value: $REVOCATIONS
type: system.kuma.io/global-secret" | kubectl apply -f -
Signing key rotation
If the signing key is compromised, we must rotate it and all the tokens that were signed by it.
-
Generate new signing key The signing key is stored as a
GlobalSecret
with a name that looks likezone-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='type=system.kuma.io/global-secret' NAME TYPE DATA AGE zone-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 of2
TOKEN="$(kumactl generate signing-key)" && echo " apiVersion: v1 data: value: $TOKEN kind: Secret metadata: name: zone-token-signing-key-2 namespace: kuma-system type: system.kuma.io/global-secret " | kubectl apply -f -
-
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.
-
Remove the old signing key
kubectl delete secret zone-token-signing-key-1 -n kuma-system
All new connections to the control plane now require tokens signed with the new signing key.
Multi-zone
When running in multi-zone mode, we can generate zone tokens only on the global control plane.
None
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.