Skip to content
Kong Logo | Kong Docs Logo
search
  • Docs
    • Explore the API Specs
      View all API Specs View all API Specs View all API Specs arrow image
    • Documentation
      API Specs
      Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Kong Gateway Operator
      Manage your Kong deployments on Kubernetes using YAML Manifests
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Mesh
1.3.x
  • Home icon
  • Kong Mesh
  • Features
  • Multi-zone authentication
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • dev
  • 2.5.x (latest)
  • 2.4.x
  • 2.3.x
  • 2.2.x
  • 2.1.x
  • 2.0.x
  • 1.9.x
  • 1.8.x
  • 1.7.x
  • 1.6.x
  • 1.5.x
  • 1.4.x
  • 1.3.x
  • 1.2.x
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Set up tokens
    • Generate token for each remote zone
    • Add token to each zone configuration
    • Enable authentication on the global control plane
  • Rotate tokens
    • Generate new signing key
    • Regenerate control plane tokens
    • Remove the old signing key
    • Restart the global control plane
  • Explore an example token
  • Additional security
You are browsing documentation for an outdated version. See the latest documentation here.

Multi-zone authentication

To add to the security of your deployments, Kong Mesh provides token generation for authenticating remote control planes to the global control plane.

The control plane token is a JWT that contains:

  • The name of the zone the token is generated for
  • The token’s serial number, used for token rotation

The control plane token is signed by a signing key that is autogenerated on the global control plane. The signing key is SHA256 encrypted.

You can check for the signing key:

$ kumactl get global-secrets

which returns something like:

NAME                             AGE
control-plane-signing-key-0001   36m

Set up tokens

To generate the tokens you need and configure your clusters:

  • Generate a token for each remote control plane.
  • Add the token to the configuration for each remote zone.
  • Enable authentication on the global control plane.

Generate token for each remote zone

On the global control plane, authenticate and run the following command:

$ kumactl generate control-plane-token --zone=west > /tmp/token
$ cat /tmp/token

The generated token looks like:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJab25lIjoid2VzdCIsIlRva2VuU2VyaWFsTnVtYmVyIjoxfQ.kIrS5W0CPMkEVhuRXcUxk3F_uUoeI3XK1Gw-uguWMpQ

For authentication to the global control plane on Kubernetes, you can port-forward port 5681 to access the API.

Add token to each zone configuration

Kubernetes with kumactl
Kubernetes with Helm
Universal

If you install the zone control plane with kumactl install control-plane, pass the --cp-token-path argument, where the value is the path to the file where the token is stored:

$ kumactl install control-plane \
  --mode=zone \
  --zone=<zone name> \
  --cp-token-path=/tmp/token \
  --ingress-enabled \
  --kds-global-address grpcs://`<global-kds-address>` | kubectl apply -f - 

Create a secret with a token in the same namespace where Kong Mesh is installed:

$ kubectl create secret generic cp-token -n kong-mesh-system --from-file=/tmp/token

Add the following to Values.yaml:

kuma:
  controlPlane:
    secrets:
      - Env: "KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_INLINE"
        Secret: "cp-token"
        Key: "token"

Either:

  • Set the token as an inline value in a KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_INLINE environment variable:
$ KUMA_MODE=zone \
  KUMA_MULTIZONE_ZONE_NAME=<zone-name> \
  KUMA_MULTIZONE_ZONE_GLOBAL_ADDRESS=grpcs://<global-kds-address> \
  KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_INLINE="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJab25lIjoid2VzdCIsIlRva2VuU2VyaWFsTnVtYmVyIjoxfQ.kIrS5W0CPMkEVhuRXcUxk3F_uUoeI3XK1Gw-uguWMpQ" \
  ./kuma-cp run

OR

  • Store the token in a file, then set the path to the file in a KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_INLINE environment variable.
    $ KUMA_MODE=zone \
    KUMA_MULTIZONE_ZONE_NAME=<zone-name> \
    KUMA_MULTIZONE_ZONE_GLOBAL_ADDRESS=grpcs://<global-kds-address> \
    KMESH_MULTIZONE_ZONE_KDS_AUTH_CP_TOKEN_PATH="/tmp/token" \
    ./kuma-cp run
    

Enable authentication on the global control plane

If you are starting from scratch and not securing existing Kong Mesh deployment, you can do this as a first step.

Kubernetes with kumactl
Kubernetes with Helm
Universal

If you install the zone control plane with kumactl install control-plane, pass the --cp-auth argument with the value cpToken:

$ kumactl install control-plane \
  --mode=global \
  --cp-auth=cpToken | kubectl apply -f -

Add the following to Values.yaml:

kuma:
  controlPlane:
    envVars:
      KMESH_MULTIZONE_GLOBAL_KDS_AUTH_TYPE: cpToken

Set KMESH_MULTIZONE_GLOBAL_KDS_AUTH_TYPE to cpToken:

$ KUMA_MODE=global \
  KMESH_MULTIZONE_GLOBAL_KDS_AUTH_TYPE=cpToken \
  ./kuma-cp run

Verify the remote control plane is connected with authentication by looking at the global control plane logs:

2021-02-24T14:30:38.596+0100	INFO	kds.auth	Remote CP successfully authenticated using Control Plane Token	{"tokenSerialNumber": 1, "zone": "cluster-2"}

Rotate tokens

If a control plane token or signing key is compromised, you must rotate all tokens.

Generate new signing key

The signing key is stored as a GlobalSecret with a name that looks like control-plane-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 is the current highest serial number.

$ kubectl get secrets -n kong-mesh-system --field-selector='type=system.kuma.io/global-secret'
NAME                             TYPE                           DATA   AGE
control-plane-signing-key-0001   system.kuma.io/global-secret   1      25m

In this case, the highest serial number is 0001. Generate a new Signing Key with a serial number of 0002

$ TOKEN="$(kumactl generate signing-key)" && echo "
apiVersion: v1
data:
  value: $TOKEN
kind: Secret
metadata:
  name: control-plane-signing-key-0002
  namespace: kong-mesh-system
type: system.kuma.io/global-secret
" | kubectl apply -f - 

Check what is the current highest serial number.

$ kumactl get global-secrets
NAME                             AGE
control-plane-signing-key-0001   36m

In this case, the highest serial number is 0001. Generate a new Signing Key with a serial number of 0002

echo "
type: GlobalSecret
name: control-plane-signing-key-0002
data: 
" | kumactl apply --var key=$(kumactl generate signing-key) -f -

Regenerate control plane tokens

Create and add a new token for each zone control plane. 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.

Make sure the new signing key is available; otherwise old and new tokens are created with the same signing key and can both provide authentication.

Remove the old signing key

Kubernetes
Universal
$ kubectl delete secret control-plane-signing-key-0001 -n kong-mesh-system
$ kumactl delete global-secret control-plane-signing-key-0001

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

Restart the global control plane

Restart all instances of the global control plane. All connections are now authenticated with the new tokens.

Explore an example token

You can decode the tokens to validate the signature or explore details.

For example, run:

$ kumactl generate control-plane-token --zone=west

which returns:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJab25lIjoid2VzdCIsIlRva2VuU2VyaWFsTnVtYmVyIjoxfQ.kIrS5W0CPMkEVhuRXcUxk3F_uUoeI3XK1Gw-uguWMpQ

Paste the token into the UI at jwt.io, or run

$ kumactl generate control-plane-token --zone=west | jwt

The result looks like:

JWT token decoded

Additional security

By default, a connection from the zone control plane to the global control plane is secured with TLS. You should also configure the zone control plane to [verify the certificate authority (CA) of the global control plane]((/mesh/latest/production/secure-deployment/certificates/#control-plane-to-control-plane-multizone){:target=”_blank”}.

Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    Powering the API world

    Increase developer productivity, security, and performance at scale with the unified platform for API management, service mesh, and ingress controller.

    • Products
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • Product Updates
      • Get Started
    • Documentation
      • Kong Konnect Docs
      • Kong Gateway Docs
      • Kong Gateway Enterprise Docs
      • Kong Mesh Docs
      • Kong Insomnia Docs
      • Kong Konnect Plugin Hub
    • Open Source
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kong Community
    • Company
      • About Kong
      • Customers
      • Careers
      • Press
      • Events
      • Contact
  • Terms• Privacy• Trust and Compliance
© Kong Inc. 2023