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.0.x (latest)
  • 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
    • Introduction to Kong Mesh
    • What is Service Mesh?
    • How Kong Mesh works
    • Deployments
    • Version support policy
    • Stability
    • Release notes
    • Installation Options
    • Kubernetes
    • Helm
    • OpenShift
    • Docker
    • Amazon ECS
    • Amazon Linux
    • Red Hat
    • CentOS
    • Debian
    • Ubuntu
    • macOS
    • Windows
    • Explore Kong Mesh with the Kubernetes demo app
    • Explore Kong Mesh with the Universal demo app
    • Standalone deployment
    • Multi-zone deployment
    • License
    • Overview
    • Data plane proxy
    • Data plane on Kubernetes
    • Data plane on Universal
    • Gateway
    • Zone Ingress
    • Zone Egress
    • CLI
    • GUI
    • Observability
    • Inspect API
    • Kubernetes Gateway API
    • Networking
    • Service Discovery
    • DNS
    • Kong Mesh CNI
    • Transparent Proxying
    • IPv6 support
    • Secure access across Kong Mesh components
    • Secrets
    • Kong Mesh API Access Control
    • API server authentication
    • Data plane proxy authentication
    • Zone proxy authentication
    • Data plane proxy membership
    • Dataplane Health
    • Fine-tuning
    • Control Plane Configuration
    • Upgrades
    • Requirements
    • Introduction
    • General notes about Kong Mesh policies
    • Applying Policies
    • How Kong Mesh chooses the right policy to apply
    • Policy matching
    • Protocol support in Kong Mesh
    • Mesh
    • Mutual TLS
    • Traffic Permissions
    • Traffic Route
    • Traffic Metrics
    • Traffic Trace
    • Traffic Log
    • Locality-aware Load Balancing
    • Fault Injection
    • Health Check
    • Circuit Breaker
    • Proxy Template
    • External Service
    • Retry
    • Timeout
    • Rate Limit
    • Virtual Outbound
    • MeshGateway
    • MeshGatewayRoute
    • Service Health Probes
    • MeshTrace (Beta)
    • MeshAccessLog (Beta)
    • MeshTrafficPermission (Beta)
    • Overview
    • HashiCorp Vault CA
    • Amazon ACM Private CA
    • cert-manager Private CA
    • OPA policy support
    • Multi-zone authentication
    • FIPS support
    • Certificate Authority rotation
    • Role-Based Access Control
    • UBI Images
    • Windows Support
    • Auditing
    • HTTP API
    • Annotations and labels in Kubernetes mode
    • Kong Mesh data collection
      • Mesh
      • CircuitBreaker
      • ExternalService
      • FaultInjection
      • HealthCheck
      • MeshGateway
      • MeshGatewayRoute
      • ProxyTemplate
      • RateLimit
      • Retry
      • Timeout
      • TrafficLog
      • TrafficPermission
      • TrafficRoute
      • TrafficTrace
      • VirtualOutbound
      • Dataplane
      • ZoneEgress
      • ZoneIngress
      • kuma-cp
      • kuma-dp
      • kumactl
    • Kuma-cp configuration reference

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Service Account Token
  • Data plane proxy token
    • Usage
    • Data Plane Proxy Token boundary
    • Token Revocation
    • Signing key rotation
    • Token rotation
    • Multizone
  • None
Kong Mesh
2.0.x (latest)
  • Home
  • Kong Mesh
  • Security
  • Data plane proxy authentication

Data plane proxy authentication

To obtain a configuration from the control-plane, a data plane proxy must authenticate itself. There are several authentication methods availble.

Service Account Token

On Kubernetes, a data plane proxy proves its identity with the Service Account Token that is mounted in every pod.

Keep in mind that if you don’t explicitly specify serviceAccountTokenName in Deployment, the Pod is run with the default Service Account Token in the Namespace. This means that authentication scope is bound to a Namespace, so any Pod in the Namespace can authenticate as any other Pod in a Namespace.

To have a strict security bound to a Deployment, every Deployment should use unique Service Account Token. On top of that, users should not be able to modify serviceAccountTokenName in Deployment. This can be achieved for example with OPA Gatekeeper.

Service Account Token is not bound to a mesh, see data plane proxy membership how to restrict which Pods can join a mesh.

Data plane proxy token

On Universal, a data plane proxy must be explicitly configured with a unique security token (data plane proxy token) that will be used to prove its identity.

The data plane proxy token is a JWT token that contains:

  • Mesh to which data plane belongs (required)
  • The name of a data plane proxy (optional)
  • List of tags that are permitted to use (optional)
  • Expiration date of the token (required, 10 years if not specified)

The Data plane proxy token is signed by a signing key that is autogenerated when Mesh is created. 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 secrets

which returns something like:

MESH      NAME                                    AGE
default   dataplane-token-signing-key-default-1   49s

Usage

You can generate token either by REST API

curl -XPOST \
  -H "Content-Type: application/json" \
  --data '{"name": "dp-echo-1", "mesh": "default", "tags": {"kuma.io/service": ["backend", "backend-admin"]}, "validFor": "720h"}' \
  http://localhost:5681/tokens/dataplane

or by using kumactl

kumactl generate dataplane-token \
  --name dp-echo-1 \
  --mesh default \
  --tag kuma.io/service=backend,backend-admin \
  --valid-for 720h > /tmp/kuma-dp-echo1-token

The token should be stored in a file and then used when starting kuma-dp

kuma-dp run \
  --cp-address=https://127.0.0.1:5678 \
  --dataplane-file=dp-backend.yaml \
  --dataplane-token-file=/tmp/kuma-dp-echo-1-token

You can also pass Dataplane Token inline as KUMA_DATAPLANE_RUNTIME_TOKEN Environment Variable.

Data Plane Proxy Token boundary

As we can see in the example above, we can generate a token by passing a name, mesh, and a list of tags. The control plane will then verify the data plane proxy resources that are connecting to it against the token. This means we can generate a token by specifying:

  • Only mesh. By doing so we can reuse the token for all dataplanes in a given mesh.
  • mesh + tag (ex. kuma.io/service). This way we can use one token across all instances/replicas of the given service. Please keep in mind that we have to specify to include all the services that a data plane proxy is in charge of. For example, if we have a Dataplane with two inbounds, one valued with kuma.io/service: backend and one with kuma.io/service: backend-admin, we need to specify both values (--tag kuma.io/service=backend,backend-admin).
  • mesh + name + tag (ex. kuma.io/service). This way we can use one token for one instance/replica of the given service.

Token Revocation

Kong Mesh 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 Secret named dataplane-token-revocations-{mesh}

Universal
Kubernetes
echo "
type: Secret
mesh: default
name: dataplane-token-revocations-default
data: " | kumactl apply --var revocations=$(echo '0e120ec9-6b42-495d-9758-07b59fe86fb9' | base64) -f -
REVOCATIONS=$(echo '0e120ec9-6b42-495d-9758-07b59fe86fb9' | base64) && echo "apiVersion: v1
kind: Secret
metadata:
  name: dataplane-token-revocations-default
  namespace: kong-mesh-system
data:
  value: $REVOCATIONS
type: system.kuma.io/secret" | kubectl apply -f -

Signing key rotation

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

  1. Generate new signing key The signing key is stored as a Secret with a name that looks like dataplane-token-signing-key-{mesh}-{serialNumber}.

    Make sure to generate the new signing key with a serial number greater than the serial number of the current signing key.

    <div class="navtabs code">
    
    Universal
    Kubernetes

    Check what is the current highest serial number.

       kumactl get secrets
        MESH      NAME                                    AGE
        default   dataplane-token-signing-key-default-1   49s
     

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

       echo "
        type: Secret
        mesh: default
        name: dataplane-token-signing-key-default-2
        data: " | kumactl apply --var key=$(kumactl generate signing-key) -f -
     

    Check what is the current highest serial number.

       kubectl get secrets -n kong-mesh-system --field-selector='type=system.kuma.io/secret'
        NAME                                 TYPE                    DATA   AGE
        dataplane-token-signing-key-mesh-1   system.kuma.io/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: dataplane-token-signing-key-mesh-2
          namespace: kong-mesh-system
        type: system.kuma.io/secret
        " | kubectl apply -f -
     

    </div>

  2. Regenerate tokens Create new data plane proxy 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

    <div class="navtabs code">
    
    Universal
    Kubernetes
       kumactl delete secret dataplane-token-signing-key-default-1 --mesh=default
     
       kubectl delete secret dataplane-token-signing-key-default-1 -n kong-mesh-system
     

    </div>

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

Token rotation

If you need to generate a new token for a Dataplane or you are using service account token projection on Kubernetes, it’s possible to configure dynamic token reloading. To enable this behaviour, set the kuma-cp configuration property dpServer.auth.useTokenPath to true. When you enable the property, kuma-dp detects changes to the token file, reloads the token and uses the new value when establishing a new connection to kuma-cp.

Multizone

When running in multizone, mode we can generate data plane proxy token both on global and zone control plane. If the deployment pipeline is configured to generate data plane proxy token before running the proxy, it can rely on the Zone CP. This way Global CP is not a single point of failure. Signing key rotation or token revocation should be performed on the global control plane.

None

We can turn off the authentication by setting KUMA_DP_SERVER_AUTH_TYPE to none.

If we disable the authentication between the control plane and the data plane proxies, any data plane proxy will be able to impersonate any service, therefore this is not recommended in production.

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