Kong Mesh exposes its API server on ports 5681 and 5682. An authenticated user can be authorized to execute administrative actions such as:
A user token is a signed JWT token that contains:
Groups in Kong Mesh allow you to manage API permissions for users. A user can be a part of multiple groups. Kong Mesh adds two groups to a user automatically:
mesh-system:authenticated.mesh-system:unauthenticated.Kong Mesh creates an admin user token on the first start of the control plane.
The admin user token is a user token issued for users in the mesh-system:admin group.
This group is authorized by default to execute all administrative operations.
To generate user tokens, you must provide the credentials of a user authorized to generate user tokens.
If you have configured kumactl with an admin user token, you can use the following command to create a user token:
kumactl generate user-token \
--name john \
--group team-a \
--valid-for 24h
With the API, you must provide a token in the Authorization header:
curl localhost:5681/tokens/user \
-H'authorization: Bearer eyJhbGc...' \
-H'content-type: application/json' \
--data '{"name": "john","groups": ["team-a"], "validFor": "24h"}'
Kong Mesh doesn’t keep a list of issued tokens. To invalidate a token, you must add it to the revocation list.
Every token has its own ID under the jti key.
You can extract the ID from the token using jwt.io or the jwt-cli tool.
To revoke user tokens, specify a comma-separated list of revoked IDs in a global secret named user-token-revocations.
A user token is signed by a signing key which is autogenerated on the first start of the control plane.
If the signing key is compromised, you must rotate it. You must also rotate all the tokens that were signed by it.
Generate a new signing key.
The signing key is stored as a global secret named in the following format: user-token-signing-key-<serial_number>.
When generating a new signing key, assign it a serial number greater than the current key’s serial number.
Generate new tokens. New tokens are generated with the signing key that has the highest serial number. At this point, tokens signed by either the new or old signing key are valid.
Remove the old signing key:
All new connections to the control plane now require tokens signed with the new signing key.
You can remove the default admin user token from storage and prevent it from being recreated. Keep in mind that removing the admin user token doesn’t remove the signing key. Anyone with access to the signing key can generate a new admin token.
In addition to the regular flow of generating signing keys, storing them in a secret, and using them to sign tokens on the control plane, Kong Mesh also offers offline signing of tokens.
In this flow, you can generate a pair of public and private keys and configure the control plane only with public keys for token verification. You can generate all the tokens without running the control plane.
The advantages of this mode are:
Here’s how to use offline issuing:
Generate a pair of signing keys:
kumactl generate signing-key --format=pem > /tmp/key-private.pem
kumactl generate public-key --signing-key-path=/tmp/key-private.pem > /tmp/key-public.pem
These commands generate standard RSA key of 2048 bits and outputs it in PEM-encoded format. You can use any external tool to generate a pair of keys. The result should look like this:
cat /tmp/key-private.pem /tmp/key-public.pem
-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEAsS61a79gC4mkr2Ltwi09ajakLyUR8YTkJWzZE805EtTkEn/r
...
htKtzsYA7yGlt364IuDybrP+PlPMSK9cQAmWRRZIcBNsKOODkAgKFA==
-----END RSA PRIVATE KEY-----
-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAsS61a79gC4mkr2Ltwi09ajakLyUR8YTkJWzZE805EtTkEn/rL2u/
...
se7sx2Pt/NPbWFFTMGVFm3A1ueTUoorW+wIDAQAB
-----END RSA PUBLIC KEY-----
Configure the control plane with the public key.
Configure a control plane with the following settings:
apiServer:
authn:
type: tokens
tokens:
enableIssuer: false # disable control plane token issuer that uses secrets
validator:
useSecrets: false # do not use signing key stored in secrets to validate the token
publicKeys:
- kid: "key-1"
key: |
-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEAsS61a79gC4mkr2Ltwi09ajakLyUR8YTkJWzZE805EtTkEn/rL2u/
...
se7sx2Pt/NPbWFFTMGVFm3A1ueTUoorW+wIDAQAB
-----END RSA PUBLIC KEY-----
Use the private key to issue tokens offline:
kumactl generate user-token \
--name john.doe@example.com \
--group users \
--valid-for 24h \
--signing-key-path /tmp/key-private.pem \
--kid key-1
The command is the same as with online signing, but with two additional arguments:
--kid: The ID of the key that should be used to validate the token. This should match kid specified in the control plane configuration.--signing-key-path: The path to a PEM-encoded private key.You can also use any external system that can issue JWT tokens using RS256 signing method with the following claims:
Name: The name of the user.Groups: The list of user groups.You can use both offline and online issuing by setting apiServer.authn.tokens.enableIssuer to true.
You can use both secrets and public key static config validators by setting apiServer.authn.tokens.validator.useSecrets to true.
Token revocation works the same when using both online and offline issuing.
Signing key rotation works similarly:
In multi-zone mode, users execute a majority of actions on the global control plane. However, some actions such as generating data plane tokens, are available on the zone control plane. The global control plane doesn’t propagate authentication credentials to the zone control plane. You can set up consistent user tokens across the whole environment by manually copying signing keys from the global control plane to zone control planes.