Azure Bastion
Native Tunnel
Implementation

1 Introduction

Azure Bastion provides a managed jump host that allows RDP and SSH connections to Azure VMs — and to any private IP reachable from the Bastion subnet — without exposing public IP addresses. Microsoft provides the Azure CLI command az network bastion tunnel to use this feature from the command line.

This document describes how the same tunnel can be established natively in .NET, without invoking the Azure CLI. The protocol was reverse-engineered by reading the source of the azext_bastion Python extension and validated through live debug capture and testing.

Prerequisites

2 Undocumented Findings

The following five findings were discovered during implementation. None appear in any public Microsoft documentation. Each caused implementation failures until discovered by reading the CLI source directly.

3 Protocol Flow

The native tunnel is established in five steps for each client TCP connection. Steps 2–5 repeat for every new RDP client that connects to the local listener port.

GET https://management.azure.com/subscriptions/{subscriptionId}
    /resourceGroups/{resourceGroupName}
    /providers/Microsoft.Network/bastionHosts/{bastionName}
    ?api-version=2024-05-01

Authorization: Bearer {ARM token}

// Response (excerpt):
{
  "properties": {
    "dnsName": "bst-<uuid>.bastion.azure.com",
    "enableTunneling": true,
    "enableIpConnect": true,
    "sku": { "name": "Standard" }
  }
}

POST https://bst-<uuid>.bastion.azure.com/api/tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded
// No Authorization header — ARM token goes in the form body

resourceId={resourceId}
&protocol=tcptunnel
&workloadHostPort=3389
&aztoken={ARM token}
&token=            // empty on first call; prev authToken for reconnection

// IP-connect only — also add:
&hostname={targetIpAddress}

{
  "authToken":      "<hex string>",   // used for DELETE cleanup only
  "websocketToken": "<hex string>",   // used in WebSocket URL
  "nodeId":         "10.x.x.x"      // Bastion scale unit identifier
}

WSS wss://bst-<uuid>.bastion.azure.com/webtunnelv2/{websocketToken}?X-Node-Id={nodeId}

var ws = new ClientWebSocket();
ws.Options.SetRequestHeader("User-Agent", "BastionRDPConnector/3.0");
await ws.ConnectAsync(wsUri, cancellationToken);

// TCP → WebSocket
while (ws.State == WebSocketState.Open) {
    int n = await tcpStream.ReadAsync(buffer, ct);
    if (n == 0) break;
    await ws.SendAsync(buffer[..n], WebSocketMessageType.Binary,
                      endOfMessage: true, ct);
}

// WebSocket → TCP
while (ws.State == WebSocketState.Open) {
    var result = await ws.ReceiveAsync(buffer, ct);
    if (result.MessageType == WebSocketMessageType.Close) break;
    await tcpStream.WriteAsync(buffer[..result.Count], ct);
}

DELETE https://bst-<uuid>.bastion.azure.com/api/tokens/{authToken} HTTP/1.1
X-Node-Id: {nodeId}

HTTP/1.1 204 No Content

4 Authentication

Only a single ARM token is needed throughout the entire flow. The token is obtained using the standard MSAL credential with the management.azure.com/.default scope — the same credential used for all other Azure Resource Manager calls in the application.

5 HTTP Client Configuration

The HttpClient must be configured to use HTTP/1.1. Python's urllib3 (used internally by the CLI) always negotiates HTTP/1.1, and the Bastion endpoint has been observed to behave incorrectly with HTTP/2 POST requests.

var httpClient = new HttpClient(new HttpClientHandler())
{
    Timeout = TimeSpan.FromSeconds(30),
    DefaultRequestVersion     = new Version(1, 1),
    DefaultVersionPolicy      = HttpVersionPolicy.RequestVersionExact
};

Build the form body using FormUrlEncodedContent, which automatically sets the correct Content-Type header:

var formFields = new Dictionary<string, string>
{
    ["resourceId"]       = resourceId,
    ["protocol"]         = "tcptunnel",
    ["workloadHostPort"] = targetPort.ToString(),  // must be a string
    ["aztoken"]          = armToken,
    ["token"]            = string.Empty            // never omit
};

// IP-connect only:
if (!string.IsNullOrEmpty(targetIpAddress))
    formFields["hostname"] = targetIpAddress;

request.Content = new FormUrlEncodedContent(formFields);

Set NoDelay = true on accepted TCP connections to minimise RDP latency. Without this, Nagle's algorithm introduces noticeable input lag in interactive sessions.

6 IP-Connect Mode

IP-connect mode allows tunnelling to any private IP address reachable from the Bastion subnet — not just Azure VMs. This includes on-premises hosts connected via ExpressRoute or Site-to-Site VPN, and hosts in other cloud providers connected via VPN.

Three differences from Azure VM mode:

1. The resourceId uses the bh-hostConnect provider path with the target IP as the resource name
2. An additional hostname field is required in the POST body, containing the same IP address
3. The resource group in the resourceId is the Bastion's own resource group, not the target's

// Azure VM mode resourceId:
/subscriptions/{sub}/resourceGroups/{vmRG}/providers/Microsoft.Compute/virtualMachines/{vmName}

// IP-connect mode resourceId:
/subscriptions/{bastionSub}/resourceGroups/{bastionRG}/providers/Microsoft.Network/bh-hostConnect/{ipAddress}

// IP-connect mode: also add to form body:
hostname={ipAddress}

7 Error Reference

8 Full HTTP Exchanges

Anonymised request/response examples captured during live testing. IP addresses replaced with representative placeholders.

Azure VM mode — POST /api/tokens

POST https://bst-<uuid>.bastion.azure.com/api/tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Accept: application/json

resourceId=%2Fsubscriptions%2F{sub}
  %2FresourceGroups%2F{rg}
  %2Fproviders%2FMicrosoft.Compute
  %2FvirtualMachines%2F{vmName}
&protocol=tcptunnel
&workloadHostPort=3389
&aztoken=eyJ0eXAiOi[...]
&token=

HTTP/1.1 200 OK
Content-Type: application/json

{
  "authToken":
    "<64-char hex>",
  "websocketToken":
    "<hex string>",
  "nodeId":
    "10.x.x.x"
}

IP-connect mode — POST /api/tokens

POST https://bst-<uuid>.bastion.azure.com/api/tokens HTTP/1.1
Content-Type: application/x-www-form-urlencoded

resourceId=%2Fsubscriptions%2F{bastionSub}
  %2FresourceGroups%2F{bastionRG}
  %2Fproviders%2FMicrosoft.Network
  %2Fbh-hostConnect%2F{targetIp}
&protocol=tcptunnel
&workloadHostPort=3389
&aztoken=eyJ0eXAiOi[...]
&token=
&hostname={targetIp}

HTTP/1.1 200 OK

{
  "authToken":
    "<64-char hex>",
  "websocketToken":
    "<hex string>",
  "nodeId":
    "10.x.x.x"
}

WebSocket upgrade

GET /webtunnelv2/{websocketToken}
    ?X-Node-Id={nodeId} HTTP/1.1
Host: bst-<uuid>.bastion.azure.com
Upgrade: websocket
Connection: Upgrade
User-Agent: BastionRDPConnector/3.0

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade

Session cleanup — DELETE /api/tokens

DELETE https://bst-<uuid>.bastion.azure.com/api/tokens/{authToken} HTTP/1.1
X-Node-Id: {nodeId}

HTTP/1.1 204 No Content

9 Debug Log Output

A successful connection produces the following sequence in the application debug log (%LOCALAPPDATA%\BastionRDPConnector\debug.log):

INFO  | === Starting Native Bastion Tunnel (no Azure CLI) ===
INFO  | ARM token: aud=https://management.azure.com, expires=19:15:47 (expires in 3649s)
INFO  | Bastion SKU: Standard
INFO  | Bastion features: enableTunneling=True, enableIpConnect=True, enableFileCopy=False
INFO  | Bastion DNS: bst-<uuid>.bastion.azure.com
INFO  | TCP listener started on localhost:55000
INFO  | Accepted TCP connection from 127.0.0.1:{ephemeral-port}
INFO  | Token request resourceId: /subscriptions/.../virtualMachines/{vmName}
INFO  | Token request encoding: application/x-www-form-urlencoded
INFO  | Token response received (294 chars)
INFO  | Bastion token obtained (nodeId=10.x.x.x)
INFO  | WebSocket connected to Bastion (state=Open)
INFO  | TCP->WS: connection closed normally (...)
INFO  | Cleaning up Bastion session (authToken length=64)
INFO  | Bastion session cleaned up successfully

10 Implementation Notes

One WebSocket per TCP client

Each RDP client connection must have its own independent WebSocket. The WebSocket cannot be shared. The TcpListener accept loop should spawn a new task per connection, each independently executing steps 2–5.

Bastion node load balancing

The nodeId returned identifies which Bastion scale unit handled the request. On subsequent connections the nodeId may differ, indicating round-robin load balancing across scale units. Each nodeId must be paired with its corresponding websocketToken — never mix tokens and node IDs from different requests.

Port auto-selection

If the configured local port is already in use, the application increments the port number up to 100 times to find an available one, then falls back to an OS-assigned port. The LocalPortChanged event is fired to notify the UI of the new port.

TCP NoDelay

Set tcpClient.NoDelay = true on all accepted connections to disable Nagle's algorithm. Without this, interactive RDP sessions exhibit noticeable input lag due to packet coalescing.

Buffer sizing

Use a 4096-byte buffer — matching what the CLI uses internally. Use ArrayPool<byte> to rent buffers rather than allocating per-connection, to avoid GC pressure during long sessions.

11 Sources