Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Early Access
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 2.1.x (latest)
  • 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
  • 1.1.x
  • 1.0.x
    • Version Support Policy
    • Stages of Software Availability
    • Release notes
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • CentOS
    • Red Hat
    • Amazon Linux
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • License
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPAPolicy Support
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Set up tokens
    • Generate token for each zone
    • Add token to each zone configuration
    • Enable authentication on the global control plane
  • Additional security
  • Legacy Control Plane Token
Kong Mesh
1.8.x
  • Home
  • Kong Mesh
  • Features
  • Multi-zone authentication
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 authentication of zone control planes to the global control plane. Authentication is based on the Zone Token which is also used to authenticate the zone proxy. See zone proxy authentication to learn about token characteristics, revocation, rotation, and more.

Kong Mesh introduces additional cp scope. Only tokens with cp scope can be used to authenticate with the zone control plane.

Set up tokens

To generate the tokens you need and configure your clusters:

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

Generate token for each zone

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

kumactl generate zone-token --zone=west --scope=cp --valid-for=720h > /tmp/token

View the token:

cat /tmp/token

The generated token looks like:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJab25lIjoid2VzdCIsIlNjb3BlIjpbImNwIl0sImV4cCI6MTY2OTU0NjkzOSwibmJmIjoxNjY2OTU0NjM5LCJpYXQiOjE2NjY5NTQ5MzksImp0aSI6IjZiYWYyYzkwLTBlODYtNGM2Mi05N2E3LTc4MzU4NTU4MzRiYyJ9.DJfA0M6uUfO4oytp8jHtzngiVggQWQR88YQxWVU1ujc0Zv-XStRDwvpdEoFGOzWVn4EUfI3gcv9qS2MxqIzQjJ83k5Jq85w4hkPyLGr-0jNS1UZF6yXz7lB_As8f91gMVHbRAoFuoybV5ndDtfYzwZknyzott7doxk-SjTes2GDvpg0-kFNGc4MBR2EprGl7YKO0vhFxQjln5AyCAhmAA7-PM7WRCzhmS-pUXacfZtP2VulWYhmTAuLPnkJrJN-ZWPkIpnV1MZmsgWbzTpnW-PhmCMQfD5m2im1c_3OlFwa9P9rZQQhdhbTp0ofMvW-cdCAcG_lOJI5j60cqPh2DGg

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="eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJab25lIjoid2VzdCIsIlNjb3BlIjpbImNwIl0sImV4cCI6MTY2OTU0NjkzOSwibmJmIjoxNjY2OTU0NjM5LCJpYXQiOjE2NjY5NTQ5MzksImp0aSI6IjZiYWYyYzkwLTBlODYtNGM2Mi05N2E3LTc4MzU4NTU4MzRiYyJ9.DJfA0M6uUfO4oytp8jHtzngiVggQWQR88YQxWVU1ujc0Zv-XStRDwvpdEoFGOzWVn4EUfI3gcv9qS2MxqIzQjJ83k5Jq85w4hkPyLGr-0jNS1UZF6yXz7lB_As8f91gMVHbRAoFuoybV5ndDtfYzwZknyzott7doxk-SjTes2GDvpg0-kFNGc4MBR2EprGl7YKO0vhFxQjln5AyCAhmAA7-PM7WRCzhmS-pUXacfZtP2VulWYhmTAuLPnkJrJN-ZWPkIpnV1MZmsgWbzTpnW-PhmCMQfD5m2im1c_3OlFwa9P9rZQQhdhbTp0ofMvW-cdCAcG_lOJI5j60cqPh2DGg" \
./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 zone control plane is connected with authentication by looking at the global control plane logs:

2021-02-24T14:30:38.596+0100	INFO	kds.auth	Zone CP successfully authenticated	{"zone": "cluster-2"}

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.

Legacy Control Plane Token

You can still authenticate a control plane using the separate Control Plane Token, but it is deprecated and will be removed in the future.

Thank you for your feedback.
Was this page useful?
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023