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.
-
The
kubectl
tool is available.
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
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'
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
Multihost strategy
With multihost 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 to the component in the URL 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 |
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.
Security considerations
This section explains the security impact of using different Che workspace exposure strategies.
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:
-
The token query parameter
-
The Authorization header in the bearer-token format
-
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 isfalse
. -
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 totrue
has security consequences because it makes Cross-site request forgery (CSRF) attacks possible. The default value of the attribute isfalse
.
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.