# 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
1

which returns something like:

NAME                          AGE
user-token-signing-key-1   36m
1
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
      
      1

      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.

        1. Generate new signing key The signing key is stored as a GlobalSecret with a name that looks like user-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 tokens for users. 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

              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
            
            1

            which returns:

            eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ.eyJOYW1lIjoiam9obiIsIkdyb3VwcyI6WyJ0ZWFtLWEiXSwiZXhwIjoxNjM2ODExNjc0LCJuYmYiOjE2MzY3MjQ5NzQsImlhdCI6MTYzNjcyNTI3NCwianRpIjoiYmYzZDBiMmUtZDg0MC00Y2I2LWJmN2MtYjkwZjU0MzkxNDY4In0.XsaPcQ5wVzRLs4o1FWywf6kw4r2ceyLGxYO8EbyA0fAxU6BPPRsW71ueD8ZlS4JlD4UrVtQQ7LG-z_nIxlDRAYhx4mmHnSjtqWZIsVS13QRrm41zccZ0SKHYxGvWMW4IkGwUbA0UZOJGno8vbpI6jTGfY9bmof5FpJJAj_sf99jCaI1H_n3n5UxtwKVN7dXXD82r6axj700jgQD-2O8gnejzlTjZkBpPF_lGnlBbd39S34VNwT0UlvRJLmCRdfh5EL24dFt0tyzQqDG2gE1RuGvTV9LOT77ZsjfMP9CITICivF6Z7uqvlOYal10jd5gN0A6w6KSI8CCaDLmVgUHvAw
            
            1

            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
            
            1
            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. This will be removed in Kuma 1.5.0.

            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

            1. Generate client certificates by using kumactl

              kumactl generate tls-certificate --type=client \
                --cert-file=/tmp/tls.crt \
                --key-file=/tmp/tls.key
              
              1
              2
              3
            2. Configure the control plane with client certificates

              • Configure kumactl with valid client certificates

                kumactl 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.

              Last Updated: 11/22/2021, 4:36:48 PM