This document describes how to use the physical security keys registered in your Google account to connect to virtual machine (VM) instances that use OS Login.
Physical security are used to generate private SSH key files for connecting to VMs. When you use the Google Cloud CLI to connect to VMs using security keys, the gcloud CLI retrieves the private SSH key associated with your security key and configures the SSH key file for you. When you use third-party tools to connect, you must use the OS Login API to retrieve the SSH key information and configure the SSH key file yourself.
Before you begin
- If you want to use the command-line examples in this guide, do the following:
- Install or update to the latest version of the Google Cloud CLI.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
- Add a security key to your Google Account.
- Set up OS Login.
Limitations
- VMs that have security keys enabled can't use the Google Cloud console SSH-in-browser tool.
- VMs that have security keys enabled only accept connections from SSH keys that are attached to the physical security keys registered in your Google account.
Both the VM you're connecting to and the workstation you're connecting from must use a version of OpenSSH 8.2 or later that supports security key SSH types. The following Compute Engine VM operating systems support security keys:
- Debian 11 (or later)
- SUSE Linux Enterprise Server (SLES) 15 (or later)
- Ubuntu 20.04 LTS (or later)
- Container-Optimized OS 93 LTS (or later)
- Rocky Linux 9 (or later)
To check if your environment supports security keys, run the following command:
ssh -Q key | grep ^sk-
If the command doesn't return any output, your environment doesn't support security keys.
Enable security keys with OS Login
You can enable use of security keys for all VMs that use OS Login in your project, or for single VMs.
Enable security keys for all OS Login-enabled VMs in a project
To enable security keys on all VMs that use OS Login in your project, use the Google Cloud console or the gcloud CLI.
Console
To enable security keys for all OS Login-enabled VMs, use the
Google Cloud console to set enable-oslogin
and enable-oslogin-sk
to
TRUE
in project metadata:
Go to the Metadata page.
Click Edit.
Click Add item.
- In the Key field, enter
enable-oslogin
. - In the Value field, enter
TRUE
.
- In the Key field, enter
Click Add item.
- In the Key field, enter
enable-oslogin-sk
. - In the Value field, enter
TRUE
.
- In the Key field, enter
Click Save.
gcloud
To enable security keys for all OS Login-enabled VMs, use the
gcloud compute project-info add-metadata
command
to set enable-oslogin=TRUE
and enable-oslogin-sk=TRUE
in project
metadata:
gcloud compute project-info add-metadata \ --metadata enable-oslogin=TRUE,enable-oslogin-sk=TRUE
Enable security keys on a single OS Login-enabled VM
To enable security keys on a VM that uses OS Login, use the Google Cloud console or the gcloud CLI.
Console
To enable security keys on a single VM, use the Google Cloud console to
set enable-oslogin
and enable-oslogin-sk
to TRUE
in instance metadata:
Go to the VM instances page.
Click the name of the VM you want to enable security keys for.
Click Edit.
In the Metadata section, click Add item.
- In the Key field, enter
enable-oslogin
. - In the Value field, enter
TRUE
.
- In the Key field, enter
Click Add item.
- In the Key field, enter
enable-oslogin-sk
. - In the Value field, enter
TRUE
.
- In the Key field, enter
Click Save.
gcloud
To enable security keys on a single VM, use the
gcloud compute instances add-metadata
command
to set enable-oslogin=TRUE
and enable-oslogin-sk=TRUE
in instance
metadata:
gcloud compute instances add-metadata VM_NAME\ --metadata enable-oslogin=TRUE,enable-oslogin-sk=TRUE
Replace VM_NAME
with the name of your VM.
Connect to a VM using a security key
You can connect to a VM that uses security keys using the gcloud CLI or third-party tools. If you connect to VMs using the gcloud CLI, the gcloud CLI configures your SSH key for you. If you connect to VMs using third-party tools, you must perform the configuration yourself.
gcloud
When you connect to VMs using the gcloud CLI, the gcloud CLI retrieves the private keys associated with your security keys and configures the private key files. This configuration is persistent and applies to all VMs that use security keys.
Use the
gcloud beta compute ssh
command
to connect to a VM that has security keys enabled:
gcloud beta compute ssh VM_NAME
Third-party tools
Before you connect to a VM that has security keys enabled, you must retrieve the private keys associated with your security keys and configure the private key files. This example uses the Python client library to perform the configuration.
You only need to perform this configuration the first time you connect to a VM. The configuration is persistent and applies to all VMs that use security keys in your project.
From a terminal on your workstation, do the following:
Install the Google client library for Python, if you haven't already, by running the following command:
pip3 install google-api-python-client
Save the following sample Python script, which retrieves the private keys associated with your security keys, configures the private key files, and connects to the VM.
Run the script to configure your keys and optionally connect to the VM.
python3 SCRIPT_NAME.py --user_key=USER_KEY --ip_address=IP_ADDRESS [--dryrun]
Replace the following:
SCRIPT_NAME
: the name of your configuration script.USER_KEY
: your primary email address.IP_ADDRESS
: the external IP address of the VM you're connecting to.[--dryrun]
: (Optional) add the--dryrun
flag to print the connection command without connecting to the VM. If you don't specify this flag, the script runs the connection command.
What's next?
- Learn how to set up OS Login with 2-step verification.
- Learn how to manage OS Login in an organization.