DOCSEARCHbyAlgolia
Submit Docs

RDPGW (GO Remote Desktop Gateway)

repository·master·Indexed 22 days ago

https://github.com/bolkedebruin/rdpgw

An open-source implementation of the Microsoft Remote Desktop Gateway protocol that enables secure RDP connections over HTTPS. It supports multiple authentication methods including OIDC, Kerberos, PAM, NTLM, and Header authentication, providing a replacement for the Microsoft Remote Desktop Gateway with support for access policies and official Microsoft clients.

Tokens
34.3K
Snippets
118
Records
155
Agent score
77%

What's inside rdpgw

  1. Overview of GO Remote Desktop Gateway (RDPGW)

    master

    RDPGW is an implementation of the Remote Desktop Gateway protocol. It allows users to connect to remote desktops (such as XRDP running in Kubernetes containers) using official Microsoft clients over HTTPS.

    Its primary goal is to provide an open-source replacement for the Microsoft Remote Desktop Gateway, including support for access policies and various authentication mechanisms.

  2. Compare RDP client compatibility with rdpgw

    master

    Different RDP clients have varying levels of compatibility and authentication flexibility with rdpgw:

    ClientAuthentication SupportNotes
    Windows mstscOpenID Connect, Kerberos, NTLMMost restrictive; requires specific ciphers, hostnames, and port-inclusive host configs. No basic auth.
    MS Store Remote DesktopVariousRequires gateway and RDP host credentials to be identical.
    Mac Remote DesktopBasic, OpenID Connect, KerberosMost flexible; supports different credentials for gateway and host.
    iOS/Android ClientsVariousGenerally more flexible than mstsc.
    FreeRDPVariousThird-party client that may provide additional flexibility.

  3. Configure Authentication Mechanisms in RDPGW

    master

    RDPGW supports several authentication methods. Configuration is managed via a YAML file (defaulting to rdpgw.yaml).

    Supported Mechanisms:

    • OpenID Connect (OIDC): Provides built-in Multi-Factor Authentication (MFA) by integrating with providers like Keycloak, Okta, Google, Azure, Apple, or Facebook. Users authenticate via a web page, which then provides an RDP file with temporary credentials.
    • Kerberos: Requires a valid Ticket Granting Ticket (TGT). The gateway proxies TGT requests to the KDC. This requires a krb5.conf file and connectivity to the KDC. It allows direct connection without an RDP file.
    • PAM/Local Authentication: Verifies credentials against a local PAM service. This requires the rdpgw-auth service to be running and a valid PAM configuration.
    • NTLM Authentication: Requires user credentials to be configured in the rdpgw-auth configuration file.
    • Header Authentication (Proxy Integration): Used for integration with upstream reverse proxies (e.g., Azure App Proxy, Google IAP, AWS ALB) that pass user identity via HTTP headers.

    Mixing Mechanisms:

    • You can mix Local authentication with Kerberos or NTLM.
    • OpenID Connect cannot currently be mixed with Local or Kerberos authentication.

  4. Authentication requirements for Microsoft mstsc client

    master

    The default Windows RDP client (mstsc) has several limitations regarding authentication and connection behavior:

    • No Basic Authentication: mstsc does not support basic authentication. You must use OpenID Connect, Kerberos, or NTLM authentication.
    • Credential Handling: When configuring a gateway directly in the client, you must either "save the credentials" for the gateway or specify a domain in the username field (e.g., .\username) when prompted. Failure to do this will cause the client to loop and repeatedly ask for credentials without sending packages to the gateway.
    • Certificate Requirement: mstsc requires a valid certificate on the gateway.

  5. Use RDP template files for client-side settings (v2.0+)

    master

    In version 2.0 and later, client-side RDP settings are configured via a template file instead of direct configuration options. This file is an RDP file where specific settings are replaced to ensure correct domain and connection usage.

    The filename is specified under the client > defaults configuration key.

    The template format uses the following syntax: # <setting>:<type i or s>:<value>

    • i: integer
    • s: string

    Example template content:

    # <setting>:<type i or s>:<value>
domain:s:testdomain
connection type:i:2
    # <setting>:<type i or s>:<value>
domain:s:testdomain
connection type:i:2

  6. Security and TLS Requirements for RDPGW

    master

    To ensure successful connections, especially with Windows clients, the following security requirements must be met:

    1. TLS Certificate: The server must use a valid TLS certificate signed by a trusted authority. The Common Name (CN) in the certificate must match the DNS hostname of the gateway.
    2. TLS Configuration:
      • You can provide your own certificate and key files.
      • You can use Let's Encrypt (requires port 80 to be reachable from Let's Encrypt servers).
      • You can disable TLS if a reverse proxy is handling TLS termination in front of the gateway.
    3. IP Validation: When using OpenID Connect, the client's IP address is typically verified against the IP used to obtain the gateway token. This can be disabled if NAT or proxies prevent matching, though this increases security risk.
    # For Let's Encrypt
Tls: auto

# For custom certificates
Tls: enable
CertFile: server.pem 
KeyFile: key.pem

  7. How Auto-Launch RDP clients works

    master

    The web interface features an automatic RDP client launching mechanism that works by converting RDP configuration into downloadable blobs via Data URLs. This allows browsers to trigger the OS-level file association for RDP files.

    The workflow is as follows:

    1. The client fetches the RDP configuration from the /api/rdp-content endpoint.
    2. The JavaScript logic converts this content into a downloadable blob.
    3. The browser triggers a download which, depending on the OS, launches the appropriate client:
      • Windows: The .rdp file auto-opens with mstsc.
      • macOS: The .rdp file auto-opens with Microsoft Remote Desktop.
      • Universal: Uses a temporary download handled by the browser's protocol handlers.

  8. Configure NTLM Authentication in RDPGW

    master

    To enable NTLM authentication, you must configure the RDPGW gateway to use the ntlm authentication method and disable TokenAuth.

    Security Warning: NTLM authentication requires passwords to be stored in plain text in the authentication helper configuration. Ensure all configuration files are strictly protected.

    Server:
  Authentication:
    - ntlm
Caps:
  TokenAuth: false

  9. Manage NTLM users (Add, Rotate, Remove)

    master

    User management is performed by modifying the /etc/rdpgw-auth.yaml file and restarting the rdpgw-auth helper.

    • Adding Users: Append a new entry to the Users list in the config file.
    • Password Rotation: Update the Password field for an existing user in the config file.
    • User Removal: Delete the user entry from the config file.

    Note: A restart of the rdpgw-auth process is required after every change to apply the new user state.

  10. Customize the RDP Gateway Web Interface

    master

    You can customize the look and feel of the RDP Gateway web interface by providing your own template files. The system uses Go template syntax for HTML and standard CSS/JS for styling.

    Steps to customize:

    1. Copy the contents of the cmd/rdpgw/templates/ directory to your preferred location.
    2. Edit the files (index.html, style.css, app.js) to match your branding requirements.
    3. Set the templates path in your RDP Gateway configuration to point to your new directory.
    4. Restart RDP Gateway to apply the changes.

    Note: If template files are missing, the system automatically falls back to embedded templates.

  11. Configure RDP Endpoint Passthrough in Azure App Proxy

    master

    To ensure RDP client compatibility, you must configure the App Proxy to bypass authentication for the RDP protocol path.

    Critical Path: /remoteDesktopGateway/*

    If the passthrough configuration is not available in your Azure Portal, you must open an Azure Support Ticket and request passthrough configuration for the /remoteDesktopGateway/* path, providing your Application ID and External URL.

  12. Set up Google Cloud Identity-Aware Proxy (IAP)

    master

    To use Google Cloud IAP, configure RDPGW to use the specific headers provided by Google's load balancer and trust the IAP/Load Balancer CIDR ranges.

    Required Header Mapping:

    • UserHeader: X-Goog-Authenticated-User-Email
    • UserIdHeader: X-Goog-Authenticated-User-ID
    • EmailHeader: X-Goog-Authenticated-User-Email

    Trusted Proxies:

    • 35.191.0.0/16 (Google IAP / load balancer health checkers)
    • 130.211.0.0/22 (Google Cloud Load Balancing)
    Header:
  UserHeader: "X-Goog-Authenticated-User-Email"
  UserIdHeader: "X-Goog-Authenticated-User-ID"
  EmailHeader: "X-Goog-Authenticated-User-Email"
  TrustedProxies:
    - "35.191.0.0/16"
    - "130.211.0.0/22"