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.

The workspace exposure strategy is configured per Che server, using the che.infra.kubernetes.server_strategy configuration property or the CHE_INFRA_KUBERNETES_SERVER__STRATEGY environment variable.

The possible values are respectively:

  • multi-host

  • single-host

  • default-host

In case of the multi-host strategy, you must set the che.infra.kubernetes.ingress.domain (or the CHE_INFRA_KUBERNETES_INGRESS_DOMAIN environment variable) configuration property to the domain name that should host subdomains of the workspace components.

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.

Che supports three ways to make workspace components available to the users, also referred to as strategies:

  • multi-host strategy

  • single-host strategy

  • default-host strategy

The strategies define whether new subdomains are created for components of the workspace, and what hosts these components are available on.

Multi-host strategy

With this strategy, each workspace component is assigned a new subdomain of the main domain configured for the Che server. On OpenShift, this is the only possible strategy, and manual configuration of the workspace exposure strategy is therefore always ignored.

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

This strategy is available on Kubernetes, but not on OpenShift. When it is used, all workspaces are deployed to subpaths 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.

This strategy 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 Ingress that hides the workspace and the component-specific URL prefix from the server.

For example, when the user accesses the hypothetical http(s)://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.

Default-host strategy

This strategy exposes the components to the outside world on the subpaths 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.

Configuring workspace exposure strategies using a Helm chart and an Operator

The following section describes how to configure workspace exposure strategies of a Che server using the Helm chart and the Operator.

Using a Helm chart

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

When deploying Che using the Helm chart, configure the workspace exposure strategy using the global.serverStrategy property. To do so, add the following option to the helm install or helm upgrade command:

$ helm install --set global.serverStrategy=<single-host>


$ helm upgrade --set global.serverStrategy=<single-host>

Depending on the strategy used, replace the <single-host> option in the above example with multi-host or default-host.

Using an Operator

Operators are software extensions to Kubernetes that use custom resources to manage applications and their components.

When deploying Che using the Operator, configure the intended strategy by modifying the spec.k8s.ingressStrategy property of the CheCluster custom resource object YAML file. To activate changes done to CheCluster YAML file, do one of the following:

  • Create a new cluster by executing the kubectl apply command. For example:

    $ kubectl apply -f <my-cluster.yaml>
  • 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/k8s/ingressStrategy", "value": "single-host"}]'

Depending on the strategy used, replace the single-host option in the above example with multi-host or default-host.

Security considerations

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

All the security-related considerations below are only applicable to Che in multi-user 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 respective 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 transparent 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 of the 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.