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

Article
11/15/2023

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

The Win32 OpenSSH project makes remote connectivity with 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'll need to enable SSH in your Windows machine.

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

Set-AzVMExtension -ResourceGroupName $myResourceGroup -VMName $myVM -Name 'OpenSSH' -Publisher 'Microsoft.Azure.OpenSSH' -Type 'WindowsOpenSSH' -TypeHandlerVersion '3.0'

{
  "type": "Microsoft.Compute/virtualMachines/extensions",
  "name": "[concat(parameters('VMName'), '/WindowsOpenSSH')]",
  "apiVersion": "2020-12-01",
  "location": "[parameters('location')]",
  "properties": {
    "publisher": "Microsoft.Azure.OpenSSH",
    "type": "WindowsOpenSSH",
    "typeHandlerVersion": "3.0"
  }
}

resource windowsOpenSSHExtension 'Microsoft.Compute/virtualMachines/extensions@2020-12-01' = {
  parent: virtualMachine
  name: 'WindowsOpenSSH'
  location: resourceGroup().location
  properties: {
    publisher: 'Microsoft.Azure.OpenSSH'
    type: 'WindowsOpenSSH'
    typeHandlerVersion: '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

Get-AzNetworkSecurityGroup -Name $MyNSG -ResourceGroupName $myResourceGroup | Add-AzNetworkSecurityRuleConfig -Name allow-SSH -access Allow -Direction Inbound -Priority 1000 -SourceAddressPrefix 208.130.28.4/32 -SourcePortRange '*' -DestinationAddressPrefix '*' -DestinationPortRange 22 -Protocol TCP | Set-AzNetworkSecurityGroup

{
  "type": "Microsoft.Network/networkSecurityGroups/securityRules",
  "apiVersion": "2021-08-01",
  "name": "allow-SSH",
  "properties": {
    "access": "Allow",
    "destinationAddressPrefix": "*",
    "destinationPortRange": "22",
    "direction": "Inbound",
    "priority": "1000",
    "protocol": "TCP",
    "sourceAddressPrefix": "208.130.28.4/32",
    "sourcePortRange": "*"
  }
}

resource allowSSH 'Microsoft.Network/networkSecurityGroups/securityRules@2021-08-01' = {
  name: 'allowSSH'
  parent: MyNSGSymbolicName
  properties: {
    access: 'Allow'
    destinationAddressPrefix: '*'
    destinationPortRange: 'string'
    destinationPortRanges: [
      '22'
    ]
    direction: 'Inbound'
    priority: 1000
    protocol: 'TCP'
    sourceAddressPrefix: '208.130.28.4/32'
    sourcePortRange: '*'
  }
}

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 doesn't 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' -Encoding UTF8;icacls.exe 'C:\ProgramData\ssh\administrators_authorized_keys' /inheritance:r /grant 'Administrators:F' /grant 'SYSTEM:F'"

Invoke-AzVMRunCommand -ResourceGroupName $myResourceGroup -VMName $myVM -CommandId 'RunPowerShellScript' -ScriptString "MYPUBLICKEY | Add-Content 'C:\ProgramData\ssh\administrators_authorized_keys' -Encoding UTF8;icacls.exe 'C:\ProgramData\ssh\administrators_authorized_keys' /inheritance:r /grant 'Administrators:F' /grant 'SYSTEM:F'"

{
  "type": "Microsoft.Compute/virtualMachines/runCommands",
  "apiVersion": "2022-03-01",
  "name": "[concat(parameters('VMName'), '/RunPowerShellScript')]",
  "location": "[parameters('location')]",
  "properties": {
    "timeoutInSeconds":600
    "source": {
      "script": "MYPUBLICKEY | Add-Content 'C:\\ProgramData\\ssh\\administrators_authorized_keys -Encoding UTF8';icacls.exe 'C:\\ProgramData\\ssh\\administrators_authorized_keys' /inheritance:r /grant 'Administrators:F' /grant 'SYSTEM:F'"
    }
  }
}

resource runPowerShellScript 'Microsoft.Compute/virtualMachines/runCommands@2022-03-01' = {
  name: 'RunPowerShellScript'
  location: resourceGroup().location
  parent: virtualMachine
  properties: {
    timeoutInSeconds: 600
    source: {
      script: "MYPUBLICKEY | Add-Content 'C:\ProgramData\ssh\administrators_authorized_keys' -Encoding UTF8;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's 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

Go to the Azure portal to connect to a VM. Search for and select Virtual machines.
Select the virtual machine from the list.
Select Connect from the left menu.
Select the option that fits with your preferred way of connecting. The portal helps walk you through the prerequisites for connecting.

Next steps

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