Quickstart: Enable SSH and RDP over an IoT Hub device stream by using a Node.js proxy application (preview)

Microsoft Azure IoT Hub currently supports device streams as a preview feature.

IoT Hub device streams allow service and device applications to communicate in a secure and firewall-friendly manner.

This quickstart describes the execution of a Node.js proxy application that's running on the service side to enable Secure Shell (SSH) and Remote Desktop Protocol (RDP) traffic to be sent to the device over a device stream. For an overview of the setup, see Local Proxy Sample.

During public preview, the Node.js SDK supports device streams on the service side only. As a result, this quickstart covers instructions to run only the service-local proxy application. To run the device-local proxy application, see:

This article describes the setup for SSH (by using port 22) and then describes how to modify the setup for RDP (which uses port 3389). Because device streams are application- and protocol-agnostic, you can modify the same sample to accommodate other types of client-server application traffic, usually by modifying the communication port.

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

If you don’t have an Azure subscription, create a free account before you begin.


  • The preview of device streams is currently supported only for IoT hubs that are created in the following regions:

    • Central US
    • Central US EUAP
    • Southeast Asia
    • North Europe
  • To run the service-local application in this quickstart, you need Node.js v10.x.x or later on your development machine.

    • Download Node.js for multiple platforms.
    • Verify the current version of Node.js on your development machine by using the following command:
    node --version
  • Add the Azure IoT Extension for Azure CLI to your Cloud Shell instance by running the following command. The IOT Extension adds IoT Hub, IoT Edge, and IoT Device Provisioning Service (DPS)-specific commands to the Azure CLI.

    az extension add --name azure-cli-iot-ext
  • If you haven't already done so, download the sample Node.js project and extract the ZIP archive.

Create an IoT hub

If you completed the previous Quickstart: Send telemetry from a device to an IoT hub, you can skip this step.

This section describes how to create an IoT hub using the Azure portal.

  1. Sign in to the Azure portal.

  2. Choose Create a resource, and then enter IoT Hub in the Search the Marketplace field.

  3. Select IoT Hub from the search results, and then select Create.

  4. On the Basics tab, complete the fields as follows:

    • Subscription: Select the subscription to use for your hub.

    • Resource Group: Select a resource group or create a new one. To create a new one, select Create new and fill in the name you want to use. To use an existing resource group, select that resource group. For more information, see Manage Azure Resource Manager resource groups.

    • Region: Choose the region in which you want your hub to be located. Select a region that supports the IoT Hub device streams preview, either Central US or Central US EUAP.

    • IoT Hub Name: Enter a name for your hub. This name must be globally unique. If the name you enter is available, a green check mark appears.

    Creating an IoT hub in the Azure portal


    Because the IoT hub will be publicly discoverable as a DNS endpoint, be sure to avoid entering any sensitive or personally identifiable information when you name it.

  5. Select Next: Size and scale to continue creating your hub.

    Setting size and scale for a new IoT hub using the Azure portal

    In Size and scale, you can accept the default settings and select Review + create at the bottom. Consider the following options:

    • Pricing and scale tier: Your selected tier. Select one of the standard tiers (S1, S2, or S3) or F1: Free tier. This choice can also be guided by the size of your fleet and the non-streaming workloads that you expect in your hub, for example, telemetry messages. For example, the free tier is intended for testing and evaluation. It allows 500 devices to be connected to the IoT hub and up to 8,000 messages per day. Each Azure subscription can create one IoT hub in the free tier.

    • Number of IoT Hub units: The number of messages allowed per unit per day depends on your hub's pricing tier. This choice depends on non-streaming workload you expect in your hub. You can select 1 for now.

    • Advanced Settings > Device-to-cloud partitions: This property relates the device-to-cloud messages to the number of simultaneous readers of the messages. Most hubs only need four partitions.

    For more information about tier options, see Choose the right IoT hub tier.

  6. To review your choices, choose Review + create. Your results will be similar to the following:

    Information for creating the new IoT hub

  7. To create your new IoT hub, select Create. The process takes a few minutes.

Register a device

If you completed Quickstart: Send telemetry from a device to an IoT hub, you can skip this step.

A device must be registered with your IoT hub before it can connect. In this section, you use Azure Cloud Shell to register a simulated device.

  1. To create the device identity, run the following command in Cloud Shell:


    • Replace the YourIoTHubName placeholder with the name you chose for your IoT hub.
    • For the name of the device you're registering, it's recommended to use MyDevice as shown. If you choose a different name for your device, use that name throughout this article, and update the device name in the sample applications before you run them.
    az iot hub device-identity create --hub-name {YourIoTHubName} --device-id MyDevice
  2. To enable the back-end application to connect to your IoT hub and retrieve the messages, you also need a service connection string. The following command retrieves the string for your IoT hub:


    Replace the YourIoTHubName placeholder with the name you chose for your IoT hub.

    az iot hub show-connection-string --policy-name service --name {YourIoTHubName} --output table

    Note the returned service connection string for later use in this quickstart. It looks like the following example:


SSH to a device via device streams

In this section, you establish an end-to-end stream to tunnel SSH traffic.

Run the device-local proxy application

As mentioned earlier, the IoT Hub Node.js SDK supports device streams on the service side only. For the device-local application, use a device proxy application that's available in one of the following quickstarts:

Before you proceed to the next step, ensure that the device-local proxy application is running.

Run the service-local proxy application

With the device-local proxy application running, run the service-local proxy application that's written in Node.js by doing the following in a local terminal window:

  1. For environment variables, provide your service credentials, the target device ID where the SSH daemon runs, and the port number for the proxy that's running on the device.

    # In Linux
    export IOTHUB_CONNECTION_STRING="{ServiceConnectionString}"
    export PROXY_PORT=2222
    # In Windows
    SET IOTHUB_CONNECTION_STRING={ServiceConnectionString}

    Change the ServiceConnectionString placeholder to match your service connection string, and MyDevice to match your device ID if you gave yours a different name.

  2. Navigate to the Quickstarts/device-streams-service directory in your unzipped project folder. Use the following code to run the service-local proxy application:

    cd azure-iot-samples-node-streams-preview/iot-hub/Quickstarts/device-streams-service
    # Install the preview service SDK, and other dependencies
    npm install azure-iothub@streams-preview
    npm install
    # Run the service-local proxy application
    node proxy.js

SSH to your device via device streams

In Linux, run SSH by using ssh $USER@localhost -p 2222 on a terminal. In Windows, use your favorite SSH client (for example, PuTTY).

Console output on the service-local after SSH session is established (the service-local proxy application listens on port 2222):

SSH terminal output

Console output of the SSH client application (SSH client communicates to SSH daemon by connecting to port 22, where the service-local proxy application is listening):

SSH client output

RDP to your device via device streams

Now use your RDP client application and connect to the service proxy on port 2222, an arbitrary port that you chose earlier.


Ensure that your device proxy is configured correctly for RDP and configured with RDP port 3389.

The RDP client connects to the service-local proxy application

Clean up resources

If you plan to continue to the next recommended article, you can keep and reuse the resources you've already created.

Otherwise, to avoid charges, you can delete the Azure resources that you created in this article.


Deleting a resource group is irreversible. The resource group and all the resources contained in it are permanently deleted. Make sure that you don't accidentally delete the wrong resource group or resources. If you created the IoT hub inside an existing resource group that contains resources that you want to keep, delete only the IoT hub resource itself, not the resource group.

To delete a resource group by name:

  1. Sign in to the Azure portal, and then select Resource groups.

  2. In the Filter by name box, enter the name of the resource group that contains your IoT hub.

  3. In the result list, to the right of your resource group, select the ellipsis (...), and then select Delete resource group.

    The "Delete resource group" button

  4. To confirm the deletion of the resource group, reenter the resource group name, and then select Delete. After a few moments, the resource group and all its contained resources are deleted.

Next steps

In this quickstart, you set up an IoT hub, registered a device, and deployed a service proxy application to enable RDP and SSH on an IoT device. The RDP and SSH traffic will be tunneled via a device stream through the IoT hub. This process eliminates the need for direct connectivity to the device.

To learn more about device streams, see: