RDP to a Windows server

Cushy can open a Remote Desktop session to a Windows Server it discovered in your cloud account — without exposing port 3389 to the internet and without Cushy ever holding a Windows password. It does this by brokering the session through [Devolutions Gateway](https://github.com/Devolutions/devolutions-gateway), an open-source (Apache-2.0) relay that you run inside your own network.

How it works

1. You run a Devolutions Gateway on a host that can reach your Windows servers on tcp/3389, and give it the public half of a key pair.
2. You paste the private half into Cushy once. It is encrypted at rest and never returned by the API.
3. When you click Connect via RDP, Cushy signs a JSON Web Token that authorizes exactly one destination, one protocol and one session id, for a few minutes.
4. Your browser downloads a small .rdp file that points at the gateway and carries that token. Remote Desktop (mstsc) or FreeRDP opens it.
5. The gateway verifies the token against the public key and relays the connection to the server. You authenticate to Windows yourself, as always.

Step 1 — generate the provisioner key pair

Do this once, on a trusted machine. RSA 2048+ (RS256, recommended) or EC P-256 (ES256) are supported.

openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out provisioner.key
openssl rsa -in provisioner.key -pubout -out provisioner.pub.key

• provisioner.pub.key — not a secret. It goes on the gateway.
• provisioner.key — the secret. It goes into Cushy, once. Delete your local copy afterwards.

Step 2 — install the gateway

On Windows (the common case)

Install the gateway as a Windows service on a management or jump host inside the same network as your servers. Devolutions ships an MSI and a PowerShell configuration module (DevolutionsGateway).

# Install the configuration module
Install-Module -Name DevolutionsGateway -Scope AllUsers

# One-time configuration
Set-DGatewayHostname 'gateway.corp.example'
Set-DGatewayListeners @(
  (New-DGatewayListener 'tcp://0.0.0.0:8181'  'tcp://*:8181'),
  (New-DGatewayListener 'http://0.0.0.0:7171' 'https://*:7171')
)

# Trust the provisioner: install the PUBLIC half only
Import-DGatewayProvisionerKey -PublicKeyFile .\provisioner.pub.key

Restart-Service DevolutionsGateway

On Linux (or in a container)

Devolutions publishes .deb/.rpm packages and the devolutions/devolutions-gateway container image. The configuration file lives at /etc/devolutions-gateway/gateway.json:

{
  "Id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
  "Hostname": "gateway.corp.example",
  "ProvisionerPublicKeyFile": "/etc/devolutions-gateway/provisioner.pub.key",
  "Listeners": [
    { "InternalUrl": "tcp://0.0.0.0:8181",  "ExternalUrl": "tcp://*:8181" },
    { "InternalUrl": "http://0.0.0.0:7171", "ExternalUrl": "https://*:7171" }
  ],
  "WebApp": { "Enabled": true, "Authentication": "Custom" }
}

Step 3 — network and firewall

Step 4 — point Cushy at the gateway

1. Open any resource from Inventory, then the Access tab.
2. Under Devolutions Gateway, choose Configure (you need the *manage cloud accounts* capability — Org Admin or SRE · Cloud Admin).
3. Enter the base URL (https://gateway.corp.example:7171), the RDP listener host and port (8181), optionally the gateway's Id — which pins every token to that one gateway — and the token lifetime (30–900 seconds, default 300).
4. Paste the contents of provisioner.key into Provisioner PRIVATE key and save.
5. Use Check reachability to confirm Cushy can see the gateway, and expand Provisioner PUBLIC key to confirm the fingerprint matches the key installed on the gateway.

Step 5 — connect

On a Windows instance's Access tab you now get Connect via RDP. It downloads a single-session .rdp file — open it with Remote Desktop and sign in to Windows as usual. The token inside is valid only for that one server, that one session and that one short window; downloading again mints a fresh one.

Open web client ↗ launches the gateway's own browser client (IronRDP, no plug-in) in a new tab. Note that it authenticates against the gateway, not Cushy — it mints its own session token there, under whatever WebApp.Authentication mode you configured. It is a convenience, not a Cushy-scoped session.

What you will see when something is missing

Security model

• No inbound RDP. Port 3389 stays closed to everything except the gateway host.
• No credentials in Cushy. The token carries no username or password, and the .rdp sets prompt for credentials:i:1. You authenticate to Windows directly.
• Least privilege per session. Each token names one destination (dst_hst), one protocol (jet_ap), one session (jet_aid), a unique id (jti), an expiry measured in minutes and — when you set a gateway Id — one gateway (jet_gw_id).
• Scoped to you. The download link is a signed capability pinned to your user and organization; another operator, or another organization, gets a 403.
• Audited. remote.gateway_configured, remote.gateway_probed, remote.session_started and remote.session_launched record who connected to what and when. Token values and key material never appear in the audit trail.
• Treat the downloaded file as a credential for its short lifetime — it is a bearer capability until it expires.

Current limits

• Windows only. The Linux GUI has its own path — see Linux desktop with KasmVNC. SSH is modelled in the same token seam but is refused with a clear "not wired yet" response.
• One gateway per organization.
• No session recording, no credential injection or vaulting, and no session shadowing.
• The browser web client is a separate sign-in against your gateway.
• A token cannot be revoked before it expires (the gateway's revocation list is not wired yet) — which is why the default lifetime is five minutes.