Enable SSH Access to Workspaces in Citrix Secure Developer Spaces™
This guide describes how to configure the Citrix Secure Developer Spaces™ (SDS) platform to enable SSH access to Workspaces. SSH access allows developers to securely connect to the remote filesystem of a workspace and use remote IDE features in tools such as Visual Studio Code, JetBrains Gateway, Cursor, or Windsurf.
Note:
When using Kubernetes distributions such as MicroK8s, replace the deployment application with a
DaemonSet.
Overview
The SSH access feature is optional and must be enabled at multiple levels:
- Platform
- Organization
- Project
- Individual workspace
This guide walks through:
- Configuring the nginx load balancer to forward TCP requests for SSH access.
- Enabling SSH access in the platform, organization, and project settings.
- Using SSH to connect to Workspaces.
Configure NGINX for SSH Access
The nginx load balancer must be configured to handle SSH requests. This is a relatively quick process. You will need to:
-
Create a ConfigMap named ssh-mapping in the nginx namespace which maps the SSH port to the SSH port of the SN workspace service (designated 12345)
-
Edit the DeploymentApp of the nginx ingress controller so that it applies the new ConfigMap in the –tcp-services-configmap flag.
-
Expose port 12345 in the Service of the nginx ingress controller.
Create a ConfigMap
To create the ConfigMap, you first switch to the namespace of the nginx controller - by default it should be called nginx. Then, simply run the command to create the ConfigMap:
kubectl create configmap ssh-mapping
<!--NeedCopy-->
Edit the ConfigMap’s data field to include a mapping from the SSH port to your release’s workspace API (it’s listening on port 2222, which is hardcoded, please do not change this value). To do this, edit the config map:
kubectl edit configmap ssh-mapping
<!--NeedCopy-->
Update the data field:
apiVersion: v1
data:
"12345": default/release-workspace-api:2222
kind: ConfigMap
<!--NeedCopy-->
Important:
Port
2222is hardcoded in the Workspace API. Do not change this value.
Update the NGINX Ingress Controller Deployment
Edit the DeploymentApp if the nginx ingress controller deployment to include the --tcp-services-configmap argument:
kubectl edit deployment ingress-nginx-controller
<!--NeedCopy-->
Add the following to the Arguments of the controller (under the Args header):
spec:
--tcp-services-configmap=$(POD_NAMESPACE)/ssh-mapping
<!--NeedCopy-->
Expose Port in the Service
Expose the port in the service of the nginx controller. Add the following entry under the ports field of the service:
kubectl edit svc nginx-ingress-controller
<!--NeedCopy-->
Ports:
appProtocol: http
name: http
nodePort: 30875
port: 80
protocol: TCP
targetPort: http
appProtocol: https
name: https
nodePort: 31800
port: 443
protocol: TCP
targetPort: https
name: ssh
port: 12345
protocol: TCP
targetPort: 12345
<!--NeedCopy-->
Once complete, TCP requests to port 12345 will be forwarded to the workspace service.
Enable SSH Access in the Platform
SSH access must be enabled at the platform, organization, and project levels individually.
Platform Level
Required role: Administrator or Security Officer
To enable the feature, navigate to the Workspace Platform Settings page:
Platform Overview → Settings → Workspace Settings → Security Settings
- Locate the Remote Development Over SSH section.
- Toggle the feature on.
- Ensure the SSH port matches the exposed port in the nginx load balancer (
12345).
The administrator can also configure the validity period for public keys used in authentication with the Workspace.
When connecting to a workspace with SSH, the user will be given the following prompt:
When opening the provided, link they will reach the following page:
From here, the user can either allow or dismiss the request. Additionally, the user can choose to allow the public key provided during the authentication process to skip seeing the prompt in future authentication attempts. This key will only be valid for a set amount of time, which is configurable by the administrator through the validity of public keys setting.
Organization Level
Required role: Organization Owner or Administrator
To enable the feature, navigate to the Workspace Security Settings page:
Organization Overview → Settings → Workspace Settings → Security Settings
- Toggle Remote Development Over SSH to enable.
Project Level
Required role: Project Owner or Administrator
To enable the feature, navigate to the Workspace Security Settings page: Project Overview → Settings → Workspace Settings → Security Settings
- Toggle Remote Development Over SSH to enable.
- Optionally:
- Enable SSH as part of the default access item for new workspaces.
- Update all existing workspaces to include SSH access.
Use SSH to connect to Workspaces
Once enabled, developers can connect to running Workspaces via SSH.
Enable SSH on Individual Workspaces
With the SSH feature enabled, developers on the platform can make use of the feature. As an additional safety measure, the feature can also be enabled or disabled on each specific Workspace. By default, SSH is disabled on individual Workspaces. To enable:
- Edit the Workspace.
- On the Basic Info page, under Access, drag the SSH icon from Available to Selected.
- Click Apply.
On workspaces with SSH enabled, the owner of the workspace will be able to access the workspace using SSH when the workspace is in a running state. To do so, first open the Connect Via SSH modal by clicking the SSH icon on the workspace card:
This will open the Connect Via SSH modal. Here the user can either connect directly to their local VS Code Desktop and/or JetBrains Gateway editors, or copy the SSH command in the format:
ssh ws-{id}.ssh.proxy.{domain} -p {port}
<!--NeedCopy-->
You can then use this command to access the workspace as you would any ordinary SSH server.
The user can authenticate using a public key. To do this, the public key must be uploaded to the platform and authorized for use in the workspace. Uploading the key can be done on the profile page:
Clicking Authorize will allow the user to specify the key’s access to specific workspaces:
SSH to Workspace with Local IDEs
This feature can be used with VS Code Remote Development and/or Jetbrains Gateway to use an IDE on your local machine but the filesystem on the remote machine.