Skip to main content
Version: 0.9.x

Configuring JWT tokens

The Tetrate platform provides two main authentication mechanisms:

  • Basic authentication
  • Bearer token authentication

Basic authentication validates the credentials against the supported authentication providers (currently LDAP is the only supported one), and upon successful authentication, JWT Bearer, and refresh tokens are issued with the details of the authenticated principal.

The Bearer token can be used in subsequent API calls to authenticate the user and avoid sending the credentials every time.

The Refresh token can be used to create a new Bearer token, to avoid re-sending the credentials in a short period of time. Typically, the Refresh tokens live 3 times longer than Bearer tokens.

The following sections describe the different configuration options that are available in the IAM service for the JWT token issuance and validation.

Configuration​

IAM and JWT token configuration are done in the TokenIssuer section of the install API. An example TokenIssuer stanza looks as follows:

apiVersion: install.tetrate.io/v1alpha1
kind: ManagementPlane
metadata:
  name: managementplane
  namespace: tsb
spec:
  tokenIssuer:
    jwt:
      expiration: 1h
      issuers:
        - name: https://jwt.tetrate.io
          algorithm: RS256
          signingKey: /etc/iam/jwt/tls.key
          audiences:
            - apis.tetrate.io

The JWT options are configured in the jwt element. The main elements that need to be configured are:

  • Token expiration.
  • Token issuers and their signing keys, algorithms used to sign tokens, etc.

The above example shows an configuration with one issuer that generates tokens valid for one hour and signs them using an RSA key.

For more details review the install API reference documentation.

Troubleshooting​

The IAM service prints detailed logs for the entire authentication process. If needed, debug logs can be enabled by starting the IAM service with the following startup flags:

--log-output-level "iam:debug,envoy-filter:debug,auth:debug,jwt:debug"
Signing key for JWT Tokens

TSB uses the private key of tcc-certs to sign the JWT tokens.