# API Server Authentication
By default, Kuma exposes API Server on ports 5681
and 5682
(protected by builtin TLS). This server is used for actions like
- Accessing policies and objects
- Managing policies and objects (on Universal)
- Accessing GUI
Authenticated user can be authorized to execute administrative actions such as
- Managing Kuma Secrets (on Universal)
- Generating Dataplane Tokens
- Generating User Tokens
# User Token
User Token is a JWT token that contains
- The name of the user
- The list of groups that user belongs to
- Expiration date of the token
The User Token is signed by a signing key that is autogenerated on the 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
user-token-signing-key-1 36m
2
# Implicit groups
A user can be a part of many groups. On top of that, Kuma adds two groups automatically.
- Every authenticated user is a part of
mesh-system:authenticated
- Every user that do not provide authentication data is a part of
mesh-system:unauthenticated
.
# Usage
# Bootstrap of admin user token
To generate user tokens, we need to first access control plane as admin. Like we saw in previous section, Kuma creates admin user token when control plane starts. If you want to remove default admin user token.
# 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 user 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
(opens new window) tool. Here is example of jti
0e120ec9-6b42-495d-9758-07b59fe86fb9
Specify list of revoked IDs separated by ,
and store it as GlobalSecret
named user-token-revocations
# Signing key rotation
If the signing key is compromised, we must rotate it and all the tokens that was signed by it.
Generate new signing key The signing key is stored as a
GlobalSecret
with a name that looks likeuser-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.
Regenerate user tokens Create new user 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
All new connections to the control plane now require tokens signed with the new signing key.
# Explore an example token
You can decode the tokens to validate the signature or explore details.
For example, run:
kumactl generate user-token --name=john --group=team-a --valid-for=24h
which returns:
eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJOYW1lIjoiam9obiIsIkdyb3VwcyI6WyJ0ZWFtLWEiXSwiZXhwIjoxNjM2ODExNjc0LCJuYmYiOjE2MzY3MjQ5NzQsImlhdCI6MTYzNjcyNTI3NCwianRpIjoiYmYzZDBiMmUtZDg0MC00Y2I2LWJmN2MtYjkwZjU0MzkxNDY4In0.XsaPcQ5wVzRLs4o1FWywf6kw4r2ceyLGxYO8EbyA0fAxU6BPPRsW71ueD8ZlS4JlD4UrVtQQ7LG-z_nIxlDRAYhx4mmHnSjtqWZIsVS13QRrm41zccZ0SKHYxGvWMW4IkGwUbA0UZOJGno8vbpI6jTGfY9bmof5FpJJAj_sf99jCaI1H_n3n5UxtwKVN7dXXD82r6axj700jgQD-2O8gnejzlTjZkBpPF_lGnlBbd39S34VNwT0UlvRJLmCRdfh5EL24dFt0tyzQqDG2gE1RuGvTV9LOT77ZsjfMP9CITICivF6Z7uqvlOYal10jd5gN0A6w6KSI8CCaDLmVgUHvAw
Paste the token into the UI at jwt.io, or use jwt-cli
(opens new window) tool
kumactl generate user-token --name=john --group=team-a --valid-for=24h | jwt
To verify on jwt.io:
https://jwt.io/#id_token=eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJOYW1lIjoiam9obiIsIkdyb3VwcyI6WyJ0ZWFtLWEiXSwiZXhwIjoxNjM2ODExNjc0LCJuYmYiOjE2MzY3MjQ5NzQsImlhdCI6MTYzNjcyNTI3NCwianRpIjoiYmYzZDBiMmUtZDg0MC00Y2I2LWJmN2MtYjkwZjU0MzkxNDY4In0.XsaPcQ5wVzRLs4o1FWywf6kw4r2ceyLGxYO8EbyA0fAxU6BPPRsW71ueD8ZlS4JlD4UrVtQQ7LG-z_nIxlDRAYhx4mmHnSjtqWZIsVS13QRrm41zccZ0SKHYxGvWMW4IkGwUbA0UZOJGno8vbpI6jTGfY9bmof5FpJJAj_sf99jCaI1H_n3n5UxtwKVN7dXXD82r6axj700jgQD-2O8gnejzlTjZkBpPF_lGnlBbd39S34VNwT0UlvRJLmCRdfh5EL24dFt0tyzQqDG2gE1RuGvTV9LOT77ZsjfMP9CITICivF6Z7uqvlOYal10jd5gN0A6w6KSI8CCaDLmVgUHvAw
✻ Header
{
"alg": "RS256",
"kid": "1",
"typ": "JWT"
}
✻ Payload
{
"Name": "john",
"Groups": [
"team-a"
],
"exp": 1636811674,
"nbf": 1636724974,
"iat": 1636725274,
"jti": "bf3d0b2e-d840-4cb6-bf7c-b90f54391468"
}
Issued At: 1636725274 11/12/2021, 2:54:34 PM
Not Before: 1636724974 11/12/2021, 2:49:34 PM
Expiration Time: 1636811674 11/13/2021, 2:54:34 PM
✻ Signature XsaPcQ5wVzRLs4o1FWywf6kw4r2ceyLGxYO8EbyA0fAxU6BPPRsW71ueD8ZlS4JlD4UrVtQQ7LG-z_nIxlDRAYhx4mmHnSjtqWZIsVS13QRrm41zccZ0SKHYxGvWMW4IkGwUbA0UZOJGno8vbpI6jTGfY9bmof5FpJJAj_sf99jCaI1H_n3n5UxtwKVN7dXXD82r6axj700jgQD-2O8gnejzlTjZkBpPF_lGnlBbd39S34VNwT0UlvRJLmCRdfh5EL24dFt0tyzQqDG2gE1RuGvTV9LOT77ZsjfMP9CITICivF6Z7uqvlOYal10jd5gN0A6w6KSI8CCaDLmVgUHvAw
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Admin Client Certificates
This section describes alternative way of authenticating to API Server. Admin client certificates are deprecated. If you are using it, please migrate to user token described above.
To use admin client certificates, set KUMA_API_SERVER_AUTHN_TYPE
to adminClientCerts
.
All users that provides client certificate are authenticated as user with name admin
that belongs to group admin
.
# Usage
Generate client certificates by using kumactl
kumactl generate tls-certificate --type=client \ --cert-file=/tmp/tls.crt \ --key-file=/tmp/tls.key
1
2
3Configure the control plane with client certificates
Configure
kumactl
with valid client certificateskumactl config control-planes add \ --name=<NAME> --address=https://<KUMA_CP_DNS_NAME>:5682 \ --client-cert-file=/tmp/tls.crt \ --client-key-file=/tmp/tls.key \ --ca-cert-file=/tmp/ca.crt # CA cert used in "Encrypted communication" section
1
2
3
4
5
6
# Multizone
In multizone setup, the majority of actions are executed on the global control plane. However, some actions like generating dataplane tokens are available on zone control planes. Authentication credentials are not propagated from global control plane to zone control planes. Consistent user tokens across the whole setup can be achieved by manually synchronizing signing key from global to zone control planes.