Using TCP Proxying with a Custom Process Launcher

Secret Server's SSH Proxy can tunnel TCP traffic for any application that accepts a host and port as command-line arguments—not just SSH clients. This enables users to launch tools like database clients through the Secret Server proxy, connecting to endpoints that are not directly reachable from the client machine.

Despite the "SSH Tunneling" label on the launcher setting, this feature tunnels arbitrary TCP traffic—not just SSH. The SSH Proxy infrastructure handles the transport.

How It Works

When Use SSH Tunneling with SSH Proxy is enabled on a Process-type launcher and the secret has proxying enabled:

  1. Secret Server opens a local TCP listener on the client machine at a randomly assigned port.

  2. The $HOST token in the process arguments is replaced with 127.0.0.1.

  3. The $PORT token is replaced with the random local port number.

  4. The launched application connects to 127.0.0.1:<random port>.

  5. Traffic flows from the client through an SSH tunnel to the Secret Server proxy, which connects to the real target host and port.

The user's machine never connects directly to the target. Only the Secret Server proxy (or a distributed engine) needs network access to the target endpoint.

Prerequisites

Before configuring this launcher:

  • The SSH Proxy must be enabled and configured. See Configuring SSH Proxies for Launchers.

  • The secret must have proxying enabled.

  • The Secret Server proxy endpoint must be able to reach the target on the relevant port (for example, TCP 1433 for SQL Server). The client machine does not need this access.

  • The secret template must have Host and Port fields defined and mapped to the launcher.

Example: Azure Data Studio — SQL Server

This example creates a custom launcher that opens Azure Data Studio and connects to a SQL Server instance through the Secret Server SSH Proxy.

Step 1: Create the launcher

  1. Search for and select Secret Templates. The Secret Templates page appears.

  2. Select the Launchers tab, then click Create. The New Launcher page appears.

  3. Configure the General Settings:

    • Launcher Type: Process

    • Launcher Name: Azure Data Studio (Proxied)

    • State: Enabled

    • Use SSH Tunneling with SSH Proxy: Checked

    • Use Additional Prompt: Unchecked

    Use SSH Tunneling with SSH Proxy and Use Additional Prompt are mutually exclusive. Enabling one disables the other.

  4. Configure the Windows Settings:

    • Process Name: C:\Users\<username>\AppData\Local\Programs\Azure Data Studio\azuredatastudio.exe

    • Process Arguments: --server $HOST,$PORT --user $USERNAME --password $PASSWORD --database master

    $HOST and $PORT are replaced with 127.0.0.1 and the local tunnel port when proxying is active. The comma between host and port in the --server argument matches Azure Data Studio's connection string format.

  5. Click Save.

Step 2: Map the launcher to a secret template

The launcher must be mapped to a template with Host and Port fields for the SSH Tunneling feature to function. Without this mapping, the checkbox has no effect.

  1. Navigate to the desired secret template (for example, a SQL Server Account template).

  2. Click the Mapping tab, then click Add Mapping.

  3. In the Mapping Type dropdown, select your new launcher.

  4. Map the fields:

    • Host → Server (or Machine)

    • Port → Port (set a default of 1433 if no port field exists on the template)

    • Username → Username

    • Password → Password

  5. Click Save.

Step 3: Enable proxying on the secret

When launching a secret, ensure that Proxy Enabled is set on the secret. If the SSH Proxy is not available or proxying is not enabled on the secret, $HOST and $PORT fall back to the actual secret values and the connection is made directly from the client machine.

Step 4: Test the connection

  1. Navigate to a secret based on the configured template.

  2. Click the launcher. Azure Data Studio launches and connects through the local tunnel.

  3. Verify that the connection succeeds.

If the connection fails, confirm that the proxy endpoint has TCP access to the SQL Server on port 1433. See Configuring SSH Proxies for Launchers.

Network Requirement

The Secret Server proxy endpoint (or distributed engine) must have network access to the target host on the required port. The client machine does not need direct access. This is the primary use case for this feature: allowing users to reach endpoints that are firewalled from their workstations.