How to connect using Secure Shell (SSH) and sign on to an Azure virtual machine running Windows

Applies to: ✔️ Windows VMs ✔️ Flexible scale sets

The Win32 OpenSSH project makes remote connectivity using Secure Shell ubiquitous by providing native support in Windows. The capability is provided in Windows Server version 2019 and later, and can be added to older versions of Windows using a virtual machine (VM) extension.

The examples below use variables. You can set variables in your environment as follows.

Shell Example
Bash/ZSH myResourceGroup='resGroup10'
PowerShell $myResourceGroup='resGroup10'

Enable SSH

First, you will need to enable SSH in your Windows machine.

Windows Server 2019 and newer

Following the Windows Server documentation page Get started with OpenSSH, run the command Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0 to enable the built-in capability, start the service, and open the Windows Firewall port.

You can use the Azure RunCommand extension to complete this task.

az vm run-command invoke -g $myResourceGroup -n $myVM --command-id RunPowerShellScript --scripts "Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0"

Windows Server 2016 and older

  • Deploy the SSH extension for Windows. The extension provides an automated installation of the Win32 OpenSSH solution, similar to enabling the capability in newer versions of Windows. Use the following examples to deploy the extension.
az vm extension set --resource-group $myResourceGroup --vm-name $myVM --name WindowsOpenSSH --publisher Microsoft.Azure.OpenSSH --version 3.0

Open TCP port

Ensure the appropriate port (by default, TCP 22) is open to allow connectivity to the VM.

az network nsg rule create -g $myResourceGroup --nsg-name $myNSG -n allow-SSH --priority 1000 --source-address-prefixes 208.130.28.4/32 --destination-port-ranges 22 --protocol TCP
  • Your VM must have a public IP address. To check if your VM has a public IP address, select Overview from the left menu and look at the Networking section. If you see an IP address next to Public IP address, then your VM has a public IP. To learn more about adding a public IP address to an existing VM, see Associate a public IP address to a virtual machine

  • Verify your VM is running. On the Overview tab, in the essentials section, verify the status of the VM is Running. To start the VM, select Start at the top of the page.

Authentication

You can authenticate to Windows machines using either username and password or SSH keys. Azure does not support provisioning public keys to Windows machines automatically, however you can copy the key using the RunCommand extension.

Overview of SSH and keys

SSH is an encrypted connection protocol that provides secure sign-ins over unsecured connections. Although SSH provides an encrypted connection, using passwords with SSH connections still leaves the VM vulnerable to brute-force attacks. We recommend connecting to a VM over SSH using a public-private key pair, also known as SSH keys.

  • The public key is placed on your VM.

  • The private key remains on your local system. Protect this private key. Do not share it.

When you use an SSH client to connect to your VM (which has the public key), the remote VM tests the client to make sure it has the correct private key. If the client has the private key, it's granted access to the VM.

Depending on your organization's security policies, you can reuse a single public-private key pair to access multiple Azure VMs and services. You do not need a separate pair of keys for each VM or service you wish to access.

Your public key can be shared with anyone, but only you (or your local security infrastructure) should have access to your private key.

Supported SSH key formats

Azure currently supports SSH protocol 2 (SSH-2) RSA public-private key pairs with a minimum length of 2048 bits. Other key formats such as ED25519 and ECDSA are not supported.

Copy a public key using the RunCommand extension.

The RunCommand extension provides an easy solution to copying a public key into Windows machines and making sure the file has correct permissions.

az vm run-command invoke -g $myResourceGroup -n $myVM --command-id RunPowerShellScript --scripts "MYPUBLICKEY | Add-Content 'C:\ProgramData\ssh\administrators_authorized_keys';icacls.exe 'C:\ProgramData\ssh\administrators_authorized_keys' /inheritance:r /grant 'Administrators:F' /grant 'SYSTEM:F'"

Connect using Az CLI

Connect to Windows machines using Az SSH commands.

az ssh vm  -g $myResourceGroup -n $myVM --local-user $myUsername

It is also possible to create a network tunnel for specific TCP ports through the SSH connection. A good use case for this is Remote Desktop which defaults to port 3389.

az ssh vm  -g $myResourceGroup -n $myVM --local-user $myUsername -- -L 3389:localhost:3389

Connect from Azure portal

  1. Go to the Azure portal to connect to a VM. Search for and select Virtual machines.
  2. Select the virtual machine from the list.
  3. Select Connect from the left menu.
  4. Select the SSH tab. If the VM has a just-in-time policy set, you first need to select the Request access button to request access before you can download the RDP file. For more information about the just-in-time policy, see Manage virtual machine access using the just in time policy.

Next steps

Learn how to transfer files to an existing VM, see Use SCP to move files to and from a VM.