Quick steps: Create and use an SSH public-private key pair for Linux VMs in Azure

  • Article

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

With a secure shell (SSH) key pair, you can create virtual machines (VMs) in Azure that use SSH keys for authentication. This article shows you how to quickly generate and use an SSH public-private key file pair for Linux VMs. You can complete these steps with the Azure local Shell, a macOS, or a Linux host.

For help with troubleshooting issues with SSH, see Troubleshoot SSH connections to an Azure Linux VM that fails, errors out, or is refused.

Note

VMs created using SSH keys are by default configured with passwords disabled, which greatly increases the difficulty of brute-force guessing attacks.

For more background and examples, see Detailed steps to create SSH key pairs.

For additional ways to generate and use SSH keys on a Windows computer, see How to use SSH keys with Windows on Azure.

Supported SSH key formats

Azure currently supports following key types:

  • SSH protocol 2 (SSH-2) RSA (Rivest, Shamir, Adleman) with a minimum length of 2048 bits
  • ED25519 Keys with a fixed length of 256 bits

Other key formats such as Elliptic-curve Diffie-Hellman (ECDH) and Elliptic Curve Digital Signature Algorithm (ECDSA) are currently not supported.

Create an SSH key pair

Use the ssh-keygen command to generate SSH public and private key files. By default, these files are created in the ~/.ssh directory. You can specify a different location, and an optional password (passphrase) to access the private key file. If an SSH key pair with the same name exists in the given location, those files are overwritten.

The following command creates an SSH key pair using RSA encryption and a bit length of 4096:

ssh-keygen -m PEM -t rsa -b 4096 -f ~/.ssh/id_rsa.pem

The following command creates an SSH key pair using ED25519 encryption with a fixed length of 256 bits:

ssh-keygen -m PEM -t ed25519 -f ~/.ssh/id_ed25519.pem

Note

You can also create key pairs with the Azure CLI with the az sshkey create command, as described in Generate and store SSH keys.

If you use the Azure CLI to create your VM with the az vm create command, you can optionally generate SSH public and private key files using the --generate-ssh-keys option. The key files are stored in the ~/.ssh directory unless specified otherwise with the --ssh-dest-key-path option. If an ssh key pair already exists and the --generate-ssh-keys option is used, a new key pair won't be generated but instead the existing key pair will be used. In the following command, replace VMname, RGname and UbuntuLTS with your own values:

Note

Before you can use Azure CLI in Microsoft Azure operated by 21Vianet, please run az cloud set -n AzureChinaCloud first to change the cloud environment. If you want to switch back to Azure Public Cloud, run az cloud set -n AzureCloud again.

az vm create --name VMname --resource-group RGname --image Ubuntu2204 --generate-ssh-keys

Note

az sshkey create command deafults to RSA encryption and cannot be use to generate ED25519 key pairs, however you can create a ED25519 key pair using ssh-keygen as described above and then use that public key to create a VM.

Provide an SSH public key when deploying a VM

To create a Linux VM that uses SSH keys for authentication, specify your SSH public key when creating the VM using the Azure portal, Azure CLI, Azure Resource Manager templates, or other methods:

If you're not familiar with the format of an SSH public key, you can display your public key with the following cat command, replacing ~/.ssh/id_rsa.pub with the path and filename of your own public key file if needed:

RSA key pair

cat ~/.ssh/id_rsa.pub

A typical RSA public key value looks like this example:

ssh-rsa AAAAB3NzaC1yc2EAABADAQABAAACAQC1/KanayNr+Q7ogR5mKnGpKWRBQU7F3Jjhn7utdf7Z2iUFykaYx+MInSnT3XdnBRS8KhC0IP8ptbngIaNOWd6zM8hB6UrcRTlTpwk/SuGMw1Vb40xlEFphBkVEUgBolOoANIEXriAMvlDMZsgvnMFiQ12tD/u14cxy1WNEMAftey/vX3Fgp2vEq4zHXEliY/sFZLJUJzcRUI0MOfHXAuCjg/qyqqbIuTDFyfg8k0JTtyGFEMQhbXKcuP2yGx1uw0ice62LRzr8w0mszftXyMik1PnshRXbmE2xgINYg5xo/ra3mq2imwtOKJpfdtFoMiKhJmSNHBSkK7vFTeYgg0v2cQ2+vL38lcIFX4Oh+QCzvNF/AXoDVlQtVtSqfQxRVG79Zqio5p12gHFktlfV7reCBvVIhyxc2LlYUkrq4DHzkxNY5c9OGSHXSle9YsO3F1J5ip18f6gPq4xFmo6dVoJodZm9N0YMKCkZ4k1qJDESsJBk2ujDPmQQeMjJX3FnDXYYB182ZCGQzXfzlPDC29cWVgDZEXNHuYrOLmJTmYtLZ4WkdUhLLlt5XsdoKWqlWpbegyYtGZgeZNRtOOdN6ybOPJqmYFd2qRtb4sYPniGJDOGhx4VodXAjT09omhQJpE6wlZbRWDvKC55R2d/CSPHJscEiuudb+1SG2uA/oik/WQ== username@domainname

ED25519 key pair

cat ~/.ssh/id_ed25519.pub

A typical ED25519 public key value looks like this example:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILRjWGWLeiUQ3U9fNnCsNpXIyACpD/Jbm09OZGsz3DIM username@domainname

If you copy and paste the contents of the public key file to use in the Azure portal or a Resource Manager template, make sure you don't copy any trailing whitespace. To copy a public key in macOS, you can pipe the public key file to pbcopy. Similarly in Linux, you can pipe the public key file to programs such as xclip.

The public key that you place on your Linux VM in Azure is by default stored under ~/.ssh/ directory, unless you specified a different location when you created the key pair. To use the Azure CLI 2.0 to create your VM with an existing public key, specify the value and optionally the location of this public key using the az vm create command with the --ssh-key-values option. In the following command, replace myVM, myResourceGroup, UbuntuLTS, azureuser, and mysshkey.pub with your own values:

az vm create \
  --resource-group myResourceGroup \
  --name myVM \
  --image Ubuntu2204 \
  --admin-username azureuser \
  --ssh-key-values mysshkey.pub

If you want to use multiple SSH keys with your VM, you can enter them in a comma-separated list, like this --ssh-key-values sshkey-desktop.pub, sshkey-laptop.pub.

SSH into your VM

With the public key deployed on your Azure VM, and the private key on your local system, SSH into your VM using the IP address or DNS name of your VM. In the following command, replace azureuser and myvm.chinanorth.cloudapp.chinacloudapi.cn with the administrator user name and the fully qualified domain name (or IP address):

ssh azureuser@myvm.chinanorth.cloudapp.chinacloudapi.cn

If you're connecting to this VM for the first time, you'll be asked to verify the host's fingerprint. It's tempting to accept the fingerprint that's presented, but that approach exposes you to a possible person-in-the-middle attack. You should always validate the host's fingerprint. You need to do this only the first time you connect from a client. To obtain the host fingerprint via the portal, use the Run Command feature to execute the command ssh-keygen -lf /etc/ssh/ssh_host_ecdsa_key.pub | awk '{print $2}'.

Screenshot showing using the Run Command to validate the host fingerprint.

To run the command using CLI, use az vm run-command invoke.

If you specified a passphrase when you created your key pair, enter that passphrase when prompted during the sign-in process. The VM is added to your ~/.ssh/known_hosts file, and you won't be asked to connect again until either the public key on your Azure VM changes or the server name is removed from ~/.ssh/known_hosts.

If the VM is using the just-in-time access policy, you need to request access before you can connect to the VM. For more information about the just-in-time policy, see Manage virtual machine access using the just in time policy.

Next steps