Configuring workspace exposure strategies

The following section describes how to configure workspace exposure strategies of a Che server and ensure that applications running inside are not vulnerable to outside attacks.

Configuring workspace exposure strategies using an Operator

Operators are software extensions to Kubernetes or OpenShift that use Custom Resources to manage applications and their components.

Prerequisites

  • The kubectl tool is available.

Procedure

When deploying Che using the Operator, configure the intended strategy by modifying the spec.server.serverExposureStrategy property of the CheCluster Custom Resource object YAML file.

The supported values for spec.server.serverExposureStrategy are:

See Workspace exposure strategies for more detail about individual strategies.

To activate changes done to CheCluster YAML file, do one of the following:

  • Create a new cluster by executing the chectl command with applying a patch. For example:

    $ chectl server:deploy  --installer=operator --platform=<platform> \
  --che-operator-cr-patch-yaml=patch.yaml

    For a list of available Kubernetes or OpenShift deployment platforms, use chectl server:deploy --platform --help.

    • Use the following patch.yaml file:

      apiVersion: org.eclipse.che/v1
kind: CheCluster
metadata:
  name: eclipse-che
spec:
  server:
    serverExposureStrategy: '<exposure-strategy>' (1)
      1 - used workspace exposure strategy

  • Update the YAML file properties of an already running cluster by executing the kubectl patch command. For example:

    $ kubectl patch checluster/eclipse-che --type=json \
  -p '[{"op": "replace",
  "path": "/spec/server/serverExposureStrategy",
  "value": "<exposure-strategy>"}]' \ (1)
  -n eclipse-che
    1 - used workspace exposure strategy
Gateway single-host on Kubernetes

Single-host on Kubernetes has two implementations, native(default) and gateway. To deploy with gateway set the k8s.singleHostExposureType of CheCluster Custom Resource to gateway, or use this patch:

apiVersion: org.eclipse.che/v1
kind: CheCluster
metadata:
  name: eclipse-che
spec:
  server:
    serverExposureStrategy: 'single-host'
  k8s:
    singleHostExposureType: 'gateway'

Configuring workspace exposure strategies using a Helm chart

A Helm Chart is a Kubernetes extension for defining, installing, and upgrading Kubernetes applications.

Procedure

When deploying Che using the Helm chart, configure the workspace exposure strategy using the global.serverStrategy. For single-host, optional global.singleHostExposure and cheSinglehostGateway.deploy properties may be configured as well. To do so, add the following option to the helm install or helm upgrade command:

Example for native single-host strategy type and multi-host or default-host strategies:

$ helm install --set global.serverStrategy=<exposure-strategy>

or:

$ helm upgrade --set global.serverStrategy=<exposure-strategy>

The supported values for global.serverStrategy are:

Gateway single-host on Kubernetes

Single-host on Kubernetes has 2 implementations, native(default) and gateway. To deploy with gateway use:

$ helm install --namespace eclipse-che \
--set global.serverStrategy=single-host \
--set global.singleHostExposure=gateway \
--set cheSinglehostGateway.deploy=true

or:

$ helm upgrade --install che --namespace eclipse-che \
--set global.serverStrategy=single-host \
--set global.singleHostExposure=gateway \
--set cheSinglehostGateway.deploy=true

Alternatively, predefined values file can be used as follows:

$ helm upgrade --install che --namespace eclipse-che \
-f "${SOURCE_HOME_DIR}"/deploy/kubernetes/helm/che/values/single-host-gateway.yaml

Workspace exposure strategies

Specific components of workspaces need to be made accessible outside of the Kubernetes or OpenShift cluster. This is typically the user interface of the workspace’s IDE, but it can also be the web UI of the application being developed. This enables developers to interact with the application during the development process.

The supported way of making workspace components available to the users is referred to as a strategy. This strategy defines whether new subdomains are created for the workspace components and what hosts these components are available on.

Che supports:

  • multi-host strategy

  • single-host strategy

    • with the gateway subtype

    • with the native subtype

  • default-host strategy

Multi-host strategy

With multi-host strategy, each workspace component is assigned a new subdomain of the main domain configured for the Che server. This is the default strategy.

This strategy is the easiest to understand from the perspective of component deployment because any paths present in the URL to the component are received as they are by the component.

On a Che server secured using the Transport Layer Security (TLS) protocol, creating new subdomains for each component of each workspace requires a wildcard certificate to be available for all such subdomains for the Che deployment to be practical.

Single-host strategy

With single-host strategy, all workspaces are deployed to sub-paths of the main Che server domain.

This is convenient for TLS-secured Che servers because it is sufficient to have a single certificate for the Che server, which will cover all the workspace component deployments as well.

Single-host strategy have two subtypes with different implementation methods. First subtype is named native. This strategy is available and default on Kubernetes, but not on OpenShift, since it uses Ingresses for servers exposing. The second subtype named gateway, works both on Kubernetes or OpenShift, and uses a special Pod with reverse-proxy running inside to route requests.

With gateway single-host strategy, cluster network policies has to be configured so that workspace’s services are reachable from reverse-proxy Pod (typically in Che namespace). These typically lives in different namespace.

To define how to expose the endpoints specified in the devfile, define the CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE environment variable in the Che instance. This environment variable is only effective with the single-host server strategy and is applicable to all workspaces of all users.

devfile endpoints: single-host

CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE: 'single-host'

This single-host configuration exposes the endpoints on subpaths, for example: https://<che-host>/serverihzmuqqc/go-cli-server-8080. This limits the exposed components and user applications. Any absolute URL generated on the server side that points back to the server does not work. This is because the server is hidden behind a path-rewriting reverse proxy that hides the unique URL path prefix from the component or user application.

For example, when the user accesses the hypothetical https://che-host:che-port/component-prefix-djh3d/app/index.php URL, the application sees the request coming to https://internal-host/app/index.php. If the application used the host in the URL that it generates in its UI, it would not work because the internal host is different from the externally visible host. However, if the application used an absolute path as the URL (for the example above, this would be /app/index.php), such URL would still not work. This is because on the outside, such URL does not point to the application, because it is missing the component-specific prefix.

Therefore, only applications that use relative URLs in their UI work with the single-host workspace exposure strategy.

devfile endpoints: multi-host

CHE_INFRA_KUBERNETES_SINGLEHOST_WORKSPACE_DEVFILE__ENDPOINT__EXPOSURE: 'multi-host'

This single-host configuration exposes the endpoints on subdomains, for example: http://serverihzmuqqc-go-cli-server-8080.<che-host>. These endpoints are exposed on an unsecured HTTP port. A dedicated Ingress or Route is used for such endpoints, even with gateway single-host setup.

This configuration limits the usability of previews shown directly in the editor page when Che is configured with TLS. Since https pages allow communication only with secured endpoints, users must open their application previews in another browser tab.

Default-host strategy

This strategy exposes the components to the outside world on the sub-paths of the default host of the cluster. It is similar to the single-host strategy. All the limitations and advantages of the single-host strategy applying to this strategy as well.

Security considerations

This section explains the security impact of using different Che workspace exposure strategies.

All the security-related considerations in this section are only applicable to Che in multiuser mode. The single user mode does not impose any security restrictions.

JSON web token (JWT) proxy

All Che plug-ins, editors, and components can require authentication of the user accessing them. This authentication is performed using a JSON web token (JWT) proxy that functions as a reverse proxy of the corresponding component, based on its configuration, and performs the authentication on behalf of the component.

The authentication uses a redirect to a special page on the Che server that propagates the workspace and user-specific authentication token (workspace access token) back to the originally requested page.

The JWT proxy accepts the workspace access token from the following places in the incoming requests, in the following order:

  1. The token query parameter

  2. The Authorization header in the bearer-token format

  3. The access_token cookie

Secured plug-ins and editors

Che users do not need to secure workspace plug-ins and workspace editors (such as Che-Theia). This is because the JWT proxy authentication is indiscernible to the user and is governed by the plug-in or editor definition in their meta.yaml descriptors.

Secured container-image components

Container-image components can define custom endpoints for which the devfile author can require Che-provided authentication, if needed. This authentication is configured using two optional attributes of the endpoint:

  • secure - A boolean attribute that instructs the Che server to put the JWT proxy in front of the endpoint. Such endpoints have to be provided with the workspace access token in one of the several ways explained in JSON web token (JWT) proxy. The default value of the attribute is false.

  • cookiesAuthEnabled - A boolean attribute that instructs the Che server to automatically redirect the unauthenticated requests for current user authentication as described in JSON web token (JWT) proxy. Setting this attribute to true has security consequences because it makes Cross-site request forgery (CSRF) attacks possible. The default value of the attribute is false.

Cross-site request forgery attacks

Cookie-based authentication can make an application secured by a JWT proxy prone to Cross-site request forgery (CSRF) attacks. See the Cross-site request forgery Wikipedia page and other resources to ensure your application is not vulnerable.

Phishing attacks

An attacker who is able to create an Ingress or route inside the cluster with the workspace that shares the host with some services behind a JWT proxy, the attacker may be able to create a service and a specially forged Ingress object. When such a service or Ingress is accessed by a legitimate user that was previously authenticated with a workspace, it can lead to the attacker stealing the workspace access token from the cookies sent by the legitimate user’s browser to the forged URL. To eliminate this attack vector, configure OpenShift to disallow setting the host of an Ingress.