Workspace containers may contain services that must be protected with authentication. Such protected services are called secure. For this purpose, a machine authentication mechanism should be used. Machine tokens avoid the need to pass Keycloak tokens to workspace containers (which can be insecure). Also, Keycloak tokens may have a relatively shorter lifetime and require periodic renewals or refreshes, which is difficult to manage and keep in sync with the same user session tokens on clients.

authentication inside the workspace
Figure 1. Authentication inside a workspace

Creating secure servers

To create secure servers in Che workspaces, set the secure attribute of the endpoint to true in the dockerimage type component in the devfile.

apiVersion: 1.0.0
metadata:
  name: petclinic-dev-environment
components:
  - type: dockerimage
    image: eclipse/maven-jdk8:latest
    volumes:
      - name: maven-repo
        containerPath: /root/.m2
        env:
      - name: ENV_VAR
        value: value
        endpoints:
      - name: maven-server
        port: 3101
        attributes:
        protocol: http
        secure: 'true'
        public: 'true'
        discoverable: 'false'
        memoryLimit: 1536M

Workspace JWT token

Workspace tokens are JSON web tokens (JWT) that contain the following information in their claims:

  • uid: The ID of the user who owns this token

  • uname: The name of the user who owns this token

  • wsid: The ID of a workspace which can be queried with this token

Every user is provided with a unique personal token for each workspace. The structure of a token and the signature are different than they are in Keycloak. The following is an example token view:

# Header
{
  "alg": "RS512",
  "kind": "machine_token"
}
# Payload
{
  "wsid": "workspacekrh99xjenek3h571",
  "uid": "b07e3a58-ed50-4a6e-be17-fcf49ff8b242",
  "uname": "john",
  "jti": "06c73349-2242-45f8-a94c-722e081bb6fd"
}
# Signature
{
  "value": "RSASHA256(base64UrlEncode(header) + . +  base64UrlEncode(payload))"
}

The SHA-256 cipher with the RSA algorithm is used for signing machine tokens. It is not configurable. Also, there is no public service that distributes the public part of the key pair with which the token is signed.

Machine token validation

The validation of machine tokens is performed using a dedicated per-workspace service with JWTProxy running on it in a separate pod. When the workspace starts, this service receives the public part of the SHA key from the Che server. A separate verification endpoint is created for each secure server. When traffic comes to that endpoint, JWTProxy tries to extract the token from the cookies or headers and validates it using the public-key part.

To query the Che server, a workspace server can use the machine token provided in the CHE_MACHINE_TOKEN environment variable. This token is the user’s who starts the workspace. The scope of such requests is restricted to the current workspace only. The list of allowed operations is also strictly limited.