Skip to content
Portal

RD Gateway

The Remote Desktop Gateway (RD Gateway) role service enables users to connect to internal network resources (computers, VMs) from any internet-connected device that can run the Remote Desktop Connection (RDC) client.

This guide describes how to set up an RD Gateway in a Cloudspace and configure your VDI Profile to use it.

This page explains the Microsoft Windows RD Gateway role. If your VDI profile uses the Linux VDI RD Gateway binary from the portal, use Linux VDI RD Gateway instead.

Prerequisites

  • Cloudspace: You must have a Cloudspace created to host the RD Gateway VM.
  • Windows Server VM: A Virtual Machine running Windows Server (2016, 2019, or 2022) deployed in your Cloudspace.
  • Domain: An Active Directory domain is recommended (e.g., yourdomain.example).
  • User Privileges: You must be logged in as a Domain Administrator or equivalent on the Gateway VM.
  • SSL Certificate: A valid SSL certificate (PFX format with private key) for your RD Gateway hostname (e.g., gateway.example.com).

Cloudspace & Network Setup

Note: The following steps apply if you are deploying the RD Gateway server within a Cloudspace in our portal. You can use any infrastructure for your RD Gateway, provided it meets the network requirements.

If deploying in a Cloudspace, you must prepare the network before configuring the software:

  1. Deploy Gateway VM: Create a Windows Server VM in your Cloudspace. This VM will act as the RD Gateway.
  2. Public IP & DNS:
    • Ensure your Cloudspace has a Public IP address.
    • Configure a DNS record (e.g., gateway.example.com) pointing to this Public IP.
  3. Port Forwarding:
    • In your Cloudspace network settings, create Port Forwards to allow traffic to reach the Gateway VM.
    • HTTPS (TCP 443): Forward Public Port 443 to the Gateway VM's Private IP on Port 443.
    • UDP (3391): Forward Public Port 3391 to the Gateway VM's Private IP on Port 3391 (required for better performance).
    • Security Warning: Do NOT expose port 3389 directly to the internet.

1. Create Domain Groups and Users

It is best practice to use a specific security group to control who can access the gateway.

  1. Open Active Directory Users and Computers (dsa.msc).
  2. Create a Security Group:
    • Right-click your desired OU > New > Group.
    • Name: RDG-CAP-Users.
    • Scope: Global. Type: Security.
  3. Create/Add Users:
    • Create your user accounts if they don't exist.
    • Add these users to the RDG-CAP-Users group.

2. Install RD Gateway Role

  1. Log in to your Gateway VM via the Console or a temporary RDP connection.
  2. Open Server Manager > Manage > Add Roles and Features.
  3. Select Role-based or feature-based installation.
  4. Select the local server.
  5. In Server Roles, expand Remote Desktop Services and check Remote Desktop Gateway.
    • Accept the prompt to add required features (IIS, etc.).
  6. Click Next through the wizard and click Install. Restart if prompted.

3. Obtain and Install SSL Certificate

You need a valid SSL certificate so clients trust the gateway.

Step 1: Obtain the Certificate

Option A: From the Pilvio.pro Portal

If you manage your certificates through the Pilvio.pro portal:

  1. Navigate to Admin > Certificate Store.
  2. Select your certificate and download the files (typically cert.pem and secret.pem).

  3. Convert to PFX: Windows requires the PFX format. Use OpenSSL to convert your PEM files:

    # Convert PEM files to PFX
# You can use OpenSSL on Windows or WSL
openssl pkcs12 -export -in cert.pem -inkey secret.pem -out gateway.pfx

Option B: From an External Source

If you have obtained a certificate from a third-party provider, ensure you have the .pfx file (containing the private key) ready.

Step 2: Import the Certificate

  1. On the Gateway VM, run mmc.exe.
  2. Go to File > Add/Remove Snap-in > Certificates > Add.
  3. Select Computer account > Local computer > Finish > OK.
  4. Navigate to Certificates (Local Computer) > Personal > Certificates.
  5. Right-click > All Tasks > Import....
  6. Select your .pfx file, enter the password, and finish.

Step 3: Bind the Certificate

  1. Open Remote Desktop Gateway Manager (from Administrative Tools).
  2. Right-click your server name > Properties > SSL Certificate tab.
  3. Click Select an existing certificate....
  4. Choose the certificate you just imported.
  5. Click Apply and OK. The status should read "Installed" or "Valid".

Certificate Auto-Renewal

For certificates that need periodic renewal, you can automate the process. See Certificate Auto-Renewal below.

4. Configure Authorization Policies

You need two policies to allow connections: a Connection Authorization Policy (CAP) and a Resource Authorization Policy (RAP).

  1. In RD Gateway Manager, right-click the server > Create New Authorization Policies.
  2. CAP (Connection Authorization Policy) - Who can connect?:
    • Name: Default-CAP.
    • User Groups: Add your RDG-CAP-Users group.
    • Authentication: Ensure "Password" is checked.
  3. RAP (Resource Authorization Policy) - What can they reach?:
    • Name: Default-RAP.
    • User Groups: Add your RDG-CAP-Users group.
    • Network Resource: Select Allow users to connect to any network resource (simplest for starting). For higher security, create a specific computer group later.
    • Allowed Ports: Allow connections only to port 3389.
  4. Finish the wizard.

5. Enable Firewall Listeners

Ensure the Windows Firewall on the Gateway VM allows the traffic.

  1. Open Windows Firewall with Advanced Security.
  2. Locate the Inbound Rules.
  3. Find and Enable these rules:
    • Remote Desktop Gateway HTTP Listener (TCP 443)
    • Remote Desktop Gateway UDP Listener (UDP 3391) - Optional

6. Connect from a Client

Once the RD Gateway is set up and the network is configured, you must configure your VDI Profile to use it.

Configure VDI Profile (Admin)

  1. Open VDI in the Admin group of the sidebar (tab VDI Profiles).
  2. Create a new profile or edit an existing one.
  3. Connection Mode: Select RD Gateway.
  4. RD Gateway Hostname: Enter the DNS name you configured earlier (e.g., gateway.example.com).
    • Note: This hostname must resolve to the Cloudspace Public IP where port forwards are active.
  5. Save the profile.

User Connection

  1. The user opens the VDI profile's landing page (the link the administrator shared with them).
  2. They click Start RDP Session and wait for the session to become ready.
  3. The .rdp file, pre-configured with the Gateway settings, downloads automatically once the session is ready — a Re-download RDP File button is also available if needed again later.
  4. The user opens the .rdp file to connect. The connection will be routed securely through the RD Gateway (over HTTPS/443) to the VDI machine.

Certificate Auto-Renewal

If you are using certificates from the Pilvio.pro portal, you can automate the renewal process on your Gateway VM. The general workflow is: 1. Check if the current certificate is expiring. 2. Fetch the new certificate from the Pilvio.pro API. 3. Convert the downloaded PEM files to PFX. 4. Import the PFX and update the RD Gateway service.

Guideline Script

You can use the following PowerShell script as a template. You will need to implement the API call to fetch the certificate from the Pilvio.pro portal.

# RD Gateway Certificate Auto-Renewal Template

$gatewayHostname = "gateway.example.com"
$certStorePath = "Cert:\LocalMachine\My"
$portalDomain = "portal.example.com" # Replace with your Pilvio.pro portal domain
$jwt = "YOUR_JWT_TOKEN" # Replace with your JWT token (Get from **APIs** in the sidebar)

# 1. Check Expiry
$currentCert = Get-ChildItem $certStorePath | Where-Object { $_.Subject -like "*$gatewayHostname*" } | Sort-Object NotAfter -Descending | Select-Object -First 1
$daysUntilExpiry = ($currentCert.NotAfter - (Get-Date)).Days

if ($daysUntilExpiry -gt 30) {
    Write-Output "Certificate is valid for $daysUntilExpiry days."
    exit 0
}

# 2. Fetch New Certificate
    $headers = @{ "Authorization" = "Bearer $jwt" }
    $apiBase = "https://$portalDomain/api/1"

    # Get Customer ID from current user info
    try {
        $me = Invoke-RestMethod -Uri "$apiBase/me" -Headers $headers
        $customerId = $me.customers[0].customer_id
        if (-not $customerId) { throw "No customer ID found for user." }
    } catch {
        Write-Error "Failed to get user info: $_"
        exit 1
    }

    # List certificates to find the one matching the hostname
    try {
        $certs = Invoke-RestMethod -Uri "$apiBase/customers/$customerId/certificates/ssl" -Headers $headers
        $targetCert = $certs | Where-Object { $_.domain -eq $gatewayHostname } | Select-Object -First 1

        if (-not $targetCert) {
            Write-Error "Certificate for $gatewayHostname not found in portal."
            exit 1
        }
    } catch {
        Write-Error "Failed to list certificates: $_"
        exit 1
    }

    # Download certificate content
    try {
        $certInfo = Invoke-RestMethod -Uri "$apiBase/customers/$customerId/certificates/ssl/$($targetCert.id)/download" -Headers $headers

        # Save to files
        $certInfo.crt | Out-File "C:\Certificates\cert.pem" -Encoding ASCII
        $certInfo.key | Out-File "C:\Certificates\secret.pem" -Encoding ASCII
    } catch {
        Write-Error "Failed to download certificate: $_"
        exit 1
    }

# 3. Convert to PFX
$pfxPassword = "YourSecurePassword"
# Use OpenSSL to convert
& "openssl.exe" pkcs12 -export -in "C:\Certificates\cert.pem" -inkey "C:\Certificates\secret.pem" -out "C:\Certificates\new.pfx" -passout pass:$pfxPassword

# 4. Import and Bind
$pfxPassSecure = ConvertTo-SecureString $pfxPassword -AsPlainText -Force
$newCert = Import-PfxCertificate -FilePath "C:\Certificates\new.pfx" -CertStoreLocation $certStorePath -Password $pfxPassSecure

Import-Module RemoteDesktopServices
Set-Item -Path "RDS:\GatewayServer\SSLCertificate\Thumbprint" -Value $newCert.Thumbprint -Force
Restart-Service TSGateway -Force

Write-Output "Certificate renewed successfully."

Troubleshooting

  • Certificate Errors: Ensure your public DNS name matches the certificate's CN/SAN. Self-signed certificates require manual trust installation on the client.
  • No UDP: If connections are slow or audio is choppy, check if UDP 3391 is forwarded and enabled. The connection will fall back to HTTP (TCP) if UDP fails.
  • "Password Incorrect" on Import: If importing a PFX on older Server 2016 builds fails, the PFX might use modern encryption. Re-export it with legacy compatibility (-legacy flag in OpenSSL).
  • Access Denied: Check the CAP and RAP policies in the RD Gateway Manager. Ensure the user's account is included in the allowed groups.
  • Auto-Renewal Not Working: Check the scheduled task history and review the log file at C:\Scripts\cert-renewal.log.
  • Security Hardening:
    • Restrict the RAP to specific computer groups instead of "Any".
    • Keep the Gateway patched.
    • Store certificate passwords securely (consider using Windows Credential Manager or Azure Key Vault).