Azure Web PubSub local tunnel tool

Article
03/04/2024

Web PubSub local tunnel provides a local development environment for customers to enhance their local development experience. There's no need to use third-party tools to expose local ports anymore, use Web PubSub local tunnel as the tunnel between the Web PubSub service and your local server to keep your local development environment secure and safe.

Web PubSub local tunnel provides:

A way to tunnel traffic from Web PubSub to your local server
A way to view the end-to-end data flow from your client to Web PubSub through the tunnel and to your local server
Provides an embedded upstream server for you to get started
Provides a simple client for you to get started with your server development

Benefits:

Secured local: no need to expose your local server to public
Secured connection: use Microsoft Entra ID and Web PubSub access policy to connect
Simple configuration: URL template sets to tunnel:///<your_server_path>
Data inspection: vivid view of the data and the workflow

Prerequisite

Node.js version 16 or higher

Install

npm install -g @azure/web-pubsub-tunnel-tool

Usage

Usage: awps-tunnel [options] [command]

A local tool to help tunnel Azure Web PubSub traffic to local web app and provide a vivid view to the end to end workflow.

Options:
  -v, --version   Show the version number.
  -h, --help      Show help details.

Commands:
  status          Show the current configuration status.
  bind [options]  Bind configurations to the tool so that you don't need to specify them every time running the tool.
  run [options]   Run the tool.
  help [command]  Display help details for subcommand.

You could also set WebPubSubConnectionString environment variable if you don't want to configure endpoint.

Prepare the credential

Both connection string and Microsoft Entra ID are supported.

Using connection string

In your Web PubSub service portal, copy your connection string from your Web PubSub service portal.
Set the connection string to your local environment variable and start awps-tunnel.

Linux or macOS
Windows

export WebPubSubConnectionString="<your connection string>"

SET WebPubSubConnectionString=<your connection string>

Using Azure Identity

In your Web PubSub service portal, go to Access control tab, and add role Web PubSub Service Owner to your identity.
In your local terminal, use Azure CLI az login to sign in to your identity.
Alternatively, you could set account information via defined environment variables, or use Managed identity authentication directly for supported Azure services.

Run

In your Web PubSub service portal, go to Settings tab, specify the event handler URL template to start with tunnel:/// to allow tunnel connection.
Run the tool with the hub you set before, for example, connect to an endpoint https://<awps-host-name>.webpubsub.azure.com with hub chat:
```
awps-tunnel run --hub chat --endpoint https://<awps-host-name>.webpubsub.azure.com
```
You could also use awps-tunnel bind --hub chat --endpoint https://<awps-host-name>.webpubsub.azure.com to save the configuration and then awps-tunnel run.
You see output like Open webview at: http://127.0.0.1:4000, open the link in your browser and you could see the tunnel status and the workflow.
Now switch to Server tab, and check Built-in Echo Server to start a builtin upstream server with code similar to the sample code shown below it.
Alternatively, you can start your own upstream server at http://localhost:3000. You can also specify option--upstream http://localhost:<custom-port> when awps-tunnel run or awps-tunnel bind to configure your own upstream server at a custom port. For example, run the below code to start this sample upstream server, when it starts, the upstream serves requests to http://localhost:3000/eventhandler/.
```
git clone https://github.com/Azure/azure-webpubsub.git
cd tools/awps-tunnel/server/samples/upstream
npm install
npm start
```
Now switch to Client tab, select Connect to start a test WebSocket connection to the Azure Web PubSub service. You would see the traffic goes through Web PubSub to Local Tunnel and finally reaches the upstream server. The tunnel tab provides the details of the request and responses, providing you with a vivid view of what is requesting your upstream server and what is reponding from the upstream server.

Under the hood

How does the tunnel tool work? Under the hood it starts a tunnel connection to the Web PubSub service. Tunnel connection is a persistent connection (WebSocket) connects to the /server/tunnel endpoint, and it is considered as one kind of server connections. You could also use ACL rules in the service to disable such connections from connecting.