About SSH connections

Linux Windows

Compute Engine uses key-based SSH authentication to establish connections toLinux virtual machine (VM) instances and additionally supportscertificate-based authentication for OS Login VMs.You can optionally enable SSH for Windows VMs. By default, passwords aren'tconfigured for local users on Linux VMs.

Before you can connect to a VM, several configurations must be performed. If youuse the Google Cloud console or the Google Cloud CLI to connect to your VMs,Compute Engine performs these configurations on your behalf.Compute Engine performs different configurations depending on which tool youuse to connect and whether youmanage access to VMs throughmetadata orOS Login. OS Login is available only forLinux VMs.

Note: When a user connects to a VM, that user can use all of the IAM permissions granted to the service account attached to the VM.

Metadata-managed SSH connections

By default,Compute Engine uses custom project and/or instance metadata toconfigure SSH keys and to manage SSH access.All Windows VMs use metadata tomanage SSH keys, while Linux VMs can use metadata keys or OS Login. If you useOS Login, metadata SSH keys are disabled.

Click each tab to learn more about the configurations Compute Engine performsbefore it grants SSH connections when you use the Google Cloud console, thegcloud CLI, or third-party tools to connect to VMs. If you connect toVMs without using the Google Cloud console or the gcloud CLI, you mustperform some configurations yourself.

Console

  1. You use theSSH button in the Google Cloud console toconnect to your VM.
  2. Compute Engine sets a username and creates an ephemeral SSH key pair with the following configuration:
  3. Compute Engine authenticates your SSH key and grants your connection.
  4. Compute Engine uploads the public SSH key and username to metadata.
  5. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username, and on Linux VMs, stores the public key in your user's~/.ssh/authorized_keys file on the VM. On Windows VMs, Compute Engine doesn't store the public key on the VM.
  6. Compute Engine grants your connection.

gcloud

  1. You use thegcloud compute ssh command toconnect to your VM.
  2. Compute Engine sets a username and creates a persistent SSH key pair with the following configurations:
  3. Compute Engine authenticates your SSH key and grants your connection.
  4. Compute Engine uploads the public SSH key and username to metadata.
  5. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username, and on Linux VMs, stores the public key in your user's~/.ssh/authorized_keys file on the VM. On Windows VMs, Compute Engine doesn't store the public key on the VM.
  6. Compute Engine grants your connection.

Third-party tools

  1. You create an SSH key pair and username. SeeCreate SSH keys for details.
  2. You upload the public key and username to metadata.SeeAdd SSH keys to VMs that use metadata-based SSH keys for details.
  3. You connect to the VM.
  4. Compute Engine retrieves the SSH key and username from metadata, creates a user account with the username, and on Linux VMs, stores the public key in your user's~/.ssh/authorized_keys file on the VM. On Windows VMs, Compute Engine doesn't store the public key on the VM.
  5. Compute Engine grants your connection.
Note: Google doesn't have access to your private key.

OS Login-managed SSH connections

Note: OS Login is only available for Linux VMs.

When you set OS Login metadata, Compute Engine deletes the VM'sauthorized_keys files and no longer accepts connections from SSH keys that arestored in project or instance metadata. OS Login supports connections from SSHkeys that are associated with your Google Account, and SSH certificates that aresigned by the OS Login certificate authority. You can optionally require OSLogin to only allow connections using SSH certificates, as described inRequireSSH certificates with OS Login.

SSH key connections

Click each tab to learn more about the configurations Compute Engineperforms before it grants SSH connections when you use SSH keys to connectto VMs. Compute Engine performs different configurations depending on ifyou use the Google Cloud console, the gcloud CLI, or third-partytools to connect to VMs. If you connect using third-party tools, you mustperform some configurations yourself.

Console

  1. You use theSSH button in the Google Cloud console toconnect to your VM.
  2. Compute Engine sets a username and creates an ephemeral SSH key pair with the following configuration:
    • Your username is the username set by your organization's Cloud Identity or Google Workspace administrator. If your organization hasn't configured a username for you, or your project doesn't belong to an organization, Compute Engine uses your Google Account email, in the following format:

      USERNAME_DOMAIN_SUFFIX
       For example, if the email associated with your Google Account iscloudysanfrancisco@gmail.com, then your generated username iscloudysanfrancisco_gmail_com.

    • Your public SSH key is stored in your browser session and in your Google Account.
    • Your private SSH key is stored in your browser session.
    • Your SSH key has an expiry of three minutes. Three minutes after Compute Engine creates the key, you can't use the SSH key to connect to the VM anymore.
  3. Compute Engine authenticates your SSH key and grants your connection.

gcloud

  1. You use thegcloud compute ssh command toconnect to your VM.
  2. Compute Engine sets a username and creates a persistent SSH key pair with the following configurations:
    • Your username is the username set by your organization's Cloud Identity or Google Workspace administrator. If your organization hasn't configured a username for you, Compute Engine uses your Google Account email, in the following format:

      USERNAME_DOMAIN_SUFFIX
       For example, if the email associated with your Google Account iscloudysanfrancisco@gmail.com, then your generated username iscloudysanfrancisco_gmail_com.

    • Your public SSH key is stored in your Google Account.
    • Your private SSH key is stored on your local machine in thegoogle_compute_engine file.
    • Your SSH key doesn't have an expiry. It is used for all future SSH connections you make, unless you configure a new key.
  3. Compute Engine authenticates your SSH key and grants your connection.

Third-party tools

  1. You create an SSH key pair. SeeCreate SSH keys for details.
  2. You upload your public SSH key to your OS Login profile. See Add keys to VMs that use OS Login for details.
    • Compute Engine stores your key in your Google Account.
    • Compute Engine configures your username in the default format:
      USERNAME_DOMAIN_SUFFIX
       For example, if the email associated with your Google Account iscloudysanfrancisco@gmail.com, then your generated username iscloudysanfrancisco_gmail_com.
  3. You optionally set a username with theGoogle Workspace Admin SDK Directory API.
  4. You connect to the VM.
  5. Compute Engine authenticates your SSH key and grants yourconnection.

SSH certificate connections

Click each tab to learn more about the configurations Compute Engineperforms before it grants SSH connections when you use SSH certificatesto connect to VMs. Compute Engine performs different configurationsdepending on if you use the Google Cloud console, the gcloud CLI, orthird-party tools to connect to VMs. If you connect using third-party tools,you must perform some configurations yourself.

Console

  1. You use theSSH button in theGoogle Cloud console toconnectto your VM.
  2. Compute Engine sets a username and creates an ephemeral SSH key pair. Your username is the username set by your organization's Cloud Identity or Google Workspace administrator. If your organization hasn't configured a username for you, or your project doesn't belong to an organization, Compute Engine uses your Google Account email, in the following format:

    USERNAME_DOMAIN_SUFFIX
     For example, if the email associated with your Google Account iscloudysanfrancisco@gmail.com, then your generated username iscloudysanfrancisco_gmail_com.

  3. Compute Engine sends your public key to the OS Login certificate authority and performs IAM authorization to ensure you have the permissions to connect to the VM.
  4. The OS Login certificate authority provides a short-lived signed SSH certificate.
  5. Compute Engine authenticates your short-lived certificate and grants your connection.

gcloud

  1. You use thegcloud beta compute sshcommand to connect to your VM.
  2. Compute Engine sets a username and creates an ephemeral SSH key pair. Your username is the username set by your organization's Cloud Identity or Google Workspace administrator. If your organization hasn't configured a username for you, or your project doesn't belong to an organization, Compute Engine uses your Google Account email, in the following format:

    USERNAME_DOMAIN_SUFFIX
     For example, if the email associated with your Google Account iscloudysanfrancisco@gmail.com, then your generated username iscloudysanfrancisco_gmail_com.

  3. Compute Engine sends your public key to the OS Login certificate authority and performs IAM authorization to ensure you have the permissions to connect to the VM.
  4. The OS Login certificate authority provides a short-lived signed SSH certificate.
  5. Compute Engine authenticates your short-lived certificate and grants your connection.

Third-party tools

  1. You create an SSH key pair. SeeCreate SSH keys for details.
  2. If you haven't previously connected to a VM that uses OS Login, youprovisiona POSIX account.
  3. Compute Engine configures your username in the default format:
    USERNAME_DOMAIN_SUFFIX
    For example, if the email associated with your Google Account iscloudysanfrancisco@gmail.com, then your generated usernameiscloudysanfrancisco_gmail_com.
  4. Your administrator can optionallyset a username with the Google Workspace Admin SDK Directory API.If your organization usesworkforce identity federation you must contact your administrator tochange your username instead.
  5. Yousend your public key to the OS Login certificate authority.
  6. The OS Login certificate authority provides a short-lived signed SSH certificate.
  7. You use the certificate to connect to the VM.
  8. Compute Engine authenticates your short-lived certificate and grants your connection.
Note: Google doesn't have access to your private key.

What's next?

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-09 UTC.