Managing Instance Access with SSH Key Pairs
This guide shows you how to control access to a Linux instance by creating SSH key pairs and editing public SSH key metadata. If you simply need to connect to a Linux instance, see Connecting to Linux Instances. If you need to connect to a Windows instance, see Connecting to Windows Instances.
To connect to a Linux VM instance, you must have an SSH key pair. Compute Engine manages your SSH key pairs for you whenever you connect to an instance from the browser or connect to an instance with the gcloud command-line tool, creating and applying SSH key pairs when necessary. However, in some situations, you might want to create and manage your own SSH key pair or key pairs for your project members. If you connect to Linux instances using third party tools, you must manage the SSH key pairs yourself.
An SSH key pair consists of the following files:
- A public SSH key file that is applied to instance-level metadata or project-wide metadata.
- A private SSH key file that the user stores on their local devices
Users can connect to an instance through third-party tools if their public SSH key is available to the instance through the metadata server and if they have the matching private SSH key. Any user who connects to an instance is automatically an administrator of the instance with permissions to run commands with sudo. SSH access to instances as the root user is disabled even if you specify an SSH key in project or instance metadata for root.
Before you begin
- If you want to use the command-line examples in this guide:
- Install the gcloud command-line tool.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
- Read about the risks of managing your own SSH keys.
Risks of manual key management
If you create and manage SSH key pairs yourself through the Cloud Platform Console, the gcloud command-line tool, or the API, you must keep track of the used keys and delete the public SSH keys for users who should not have access. For example, if a team member leaves your project, remove their public SSH keys from metadata so they cannot continue to access your instances.
Additionally, specifying your gcloud tool or API calls incorrectly can potentially wipe out all of the public SSH keys in your project or on your instances, which disrupts connections for your project members.
If you are not sure that you want to manage your own keys, use Compute Engine tools to connect to your instances instead.
Overview
By creating and managing SSH key pairs, you can allow users to access a Linux instance through third-party tools.
An SSH key pair consists of two files: a unique private SSH key file that is stored locally by a user and a matching public SSH key file that is accessed by the instances that the user connects to.
If a user presents their private SSH key, they can use a third-party tool to connect to any instance that has access to the matching public SSH key file from metadata even if they are not a member of your GCP project. Therefore, you can control which instances a user can access by changing the public SSH key metadata on one or more instances.
To edit public SSH key metadata:
-
Decide which tool you will use to edit metadata:
- Edit metadata from your browser by using the Google Cloud Platform Console.
- If you prefer the command-line, use the
gcloudcommand-line tool to edit metadata. - If you are an advanced user, you can automate your SSH key pair management with API methods.
-
If you need to add users to a Linux instance, prepare their public SSH keys with the following processes:
- If you need to add users who do not have SSH key pairs, generate a new SSH key pair for each new user.
- If you need to add users who have existing SSH key pairs, locate the public SSH key for each existing key pair.
- Format any public SSH keys that you want to add so they will work correctly with the tool that you will use to edit metadata. Optionally, you can also format your public SSH keys to add, edit, or remove expiration times.
-
Edit public SSH key metadata to add or remove users from a Linux instance.
-
Connect to your Linux instance through a third-party tool to ensure that each public SSH key is added or removed correctly. A user can only connect to an instance if their public SSH key is available to the instance through the metadata server and if they have the matching private SSH key.
Creating a new SSH key pair
If you do not have an existing private SSH key file and a matching public SSH key file that you can use, generate a new SSH key pair. If you want to use an existing SSH key pair, locate the public SSH key file.
On Linux or macOS workstations, you can generate a key pair with the ssh-keygen tool.
-
Open a terminal on your workstation and use the
ssh-keygencommand to generate a new key pair. Specify the-Cflag to add a comment with your username.ssh-keygen -t rsa -f ~/.ssh/[KEY_FILENAME] -C [USERNAME]where:
[KEY_FILENAME]is the name that you want to use for your SSH key files. For example, a filename ofmy-ssh-keygenerates a private key file namedmy-ssh-keyand a public key file namedmy-ssh-key.pub.[USERNAME]is the user for whom you will apply this SSH key pair.
This command generates a private SSH key file and a matching public SSH key with the following structure:
ssh-rsa [KEY_VALUE] [USERNAME]
where:
[KEY_VALUE]is the key value that you generated.[USERNAME]is the user that this key applies to.
-
Restrict access to your private key so that only you can read it and nobody can write to it.
chmod 400 ~/.ssh/[KEY_FILENAME]where
[KEY_FILENAME]is the name that you used for your SSH key files.
Repeat this process for every user that you need to create a key pair for. Then, locate the SSH key pairs that you made as well as any existing SSH keys that you want to add to a project or instance.
Locating an SSH key pair
There are multiple reasons why you might need to locate an SSH key pair. For example, if you want to add a user's public SSH key to a project or instance, you will need access to the public key file for their key pair. Alternatively, you might need to locate your private SSH key file in order to connect to a Linux instance.
When an SSH key pair is created, it is saved to a default location. The default locations and names of your public and private SSH key files depend on the tools that were used to create that key pair.
If you created a key pair on a Linux or macOS workstation by using the ssh-keygen tool, your key pair was saved to the following locations:
- Public key:
~/.ssh/[KEY_FILENAME].pub - Private key:
~/.ssh/[KEY_FILENAME]
where [KEY_FILENAME] is the filename of the SSH key pair, which was set when the key pair was created.
If you need to add or remove the public SSH key from project or instance metadata, format the public SSH key file.
Formatting your public SSH key files
Before you can upload your public SSH keys to your project or instance metadata, you must check the format of each public SSH key file that you plan to add.
Depending on which tool you will use to edit metadata, format your keys to work with the Cloud Platform Console, the gcloud command-line tool, or API methods. Optionally, you can also change your public SSH keys to add, edit, or remove an expiration time.
To check the format of a public SSH key:
-
Locate and open the public SSH key file.
-
Check the format of the public SSH key file.
-
If a public SSH key has an expiration time, then it must have the following format:
ssh-rsa [KEY_VALUE] google-ssh {"userName":"[USERNAME]","expireOn":"[EXPIRE_TIME]"}
where:
[KEY_VALUE]is the public SSH key value.[USERNAME]is the user for this SSH key, which was specified when the key pair was created.[EXPIRE_TIME]is a value in RFC3339 format. For example:2018-12-04T20:12:00+0000.
-
Otherwise, the public SSH key must have the following format:
ssh-rsa [KEY_VALUE] [USERNAME]
where:
[KEY_VALUE]is the public SSH key value.[USERNAME]is the user for this SSH key, which was specified when the key pair was created.
-
-
If your key does not match one of the above formats or if you want to add, edit, or remove an expiration time, then follow the instructions below to format your public SSH key. Otherwise, leave the file open and add the public SSH key to project or instance metadata.
To format a public SSH key for the console:
-
Make a copy of your public key file. Use the copy with Compute Engine and keep the original file to use with your other SSH configurations.
-
Open the copy of your public key file.
-
Modify the public key file so that it has the following format:
ssh-rsa [KEY_VALUE] [USERNAME]
where:
[KEY_VALUE]is the public SSH key value.[USERNAME]is the user for this SSH key, which was specified when the key pair was created.
Alternatively, if you want the public SSH key to have an expiration time, then modify the file to match the following format:
ssh-rsa [KEY_VALUE] google-ssh {"userName":"[USERNAME]","expireOn":"[EXPIRE_TIME]"}
where:
[KEY_VALUE]is the public SSH key value.[USERNAME]is the user for this SSH key, which was specified when the key pair was created.[EXPIRE_TIME]is a value in RFC3339 format. For example:2018-12-04T20:12:00+0000.
-
Save the changes that you have made, and leave the file open.
You are now ready to add the public SSH key to project or instance metadata.
Editing public SSH key metadata
User access to a Linux instance through third-party tools is determined by which public SSH keys are available to the instance. You can control the public SSH keys that are available to a Linux instance by editing metadata, which is where your public SSH keys and related information are stored. There are three types of metadata for your public SSH keys:
- Project-wide public SSH keys: Use this metadata to give users general access: the ability to connect to most instances in your project.
- Allow or Block project-wide public SSH keys: Use this metadata value to block or allow project-wide public SSH keys on a specific instance. By default, an instance accepts all project-wide public SSH keys. Block project-wide public SSH keys if you want to restrict the instance to only users with instance-level public SSH keys.
- Instance-level public SSH keys: Use this metadata to give users special access: the ability to connect to a specific instance in your project, even if it blocks project-wide public SSH keys.
Adding or removing project-wide public SSH keys
Use project-wide public SSH keys to give users general access to a Linux instance. Project-wide public SSH keys give users access to all of the Linux instances in a project that allow project-wide public SSH keys. If an instance blocks project-wide public SSH keys, a user cannot use their project-wide public SSH key to connect to the instance unless the same public SSH key is also added to instance metadata.
To add or remove project-wide public SSH keys from the Cloud Platform Console:
-
In the Google Cloud Platform Console, go to the metadata page for your project.
-
Under SSH Keys, click Edit.
-
Modify the project-wide public SSH keys:
- To add a public SSH key, click Add item at the bottom of the page. This will produce a text box. Copy the contents of your public SSH key file and paste them in to the text box. Repeat this process for each public SSH key that you want to add.
-
To remove a public SSH key, click the removal button next to it:
Repeat this process for each public SSH key that you want to remove.
-
When you are done, click Save at the bottom of the page.
When you have finished, test your changes by trying to connect to your Linux instance through third-party tools.
If you encounter issues, check the metadata of the instance that you are trying to connect to. If instance-level metadata is set to block project-wide SSH keys or has a deprecated instance-only sshKeys value, the instance will ignore all project-wide SSH keys. To apply project-wide keys to an instance, make sure the instance allows project-wide public SSH keys and, if present, remove the deprecated instance-only sshKeys value from instance metadata.
Allowing or blocking project-wide public SSH keys from a Linux instance
If you need your instance to ignore project-wide public SSH keys and use only the instance-level keys, you can block project-wide public SSH keys from the instance. This will only allow users whose public SSH key is stored in instance-level metadata to access the instance. If you want your instance to use both project-wide and instance-level public SSH keys, set the instance metadata to allow project-wide SSH keys. This will allow any user whose public SSH key is stored in project-wide or instance-level metadata to access the instance.
To allow or block project-wide public SSH keys from the Cloud Platform Console:
-
In the Google Cloud Platform Console, go to the VM instances page.
-
Click on the name of the instance that you want to modify.
-
Click Edit in the toolbar.
-
Under SSH Keys, go to the Block project-wide SSH keys checkbox.
- To block users with project-wide SSH keys from connecting to this instance, select Block project-wide SSH keys.
- To allow users with project-wide SSH keys to connect to this instance, deselect Block project-wide SSH keys.
-
When you are done, click Save at the bottom of the page.
When you have finished, test your changes by trying to connect to your Linux instance through third-party tools.
Adding or removing instance-level public SSH keys
Instance-level public SSH keys give users access to a specific Linux instance. Users with instance-level public SSH keys can access a Linux instance even if it blocks project-wide public SSH keys.
To add or remove instance-level public SSH keys from the Cloud Platform Console:
-
In the Google Cloud Platform Console, go to the VM instances page.
-
Click on the name of the instance that you want to modify.
-
Click Edit in the toolbar.
-
Under SSH Keys, click Show and edit. The section expands to show all of the instance-level public SSH keys.
-
Modify the instance-level public SSH keys:
- To add a public SSH key, click Add item. This will produce a text box. Copy the contents of your public SSH key file and paste them in to the text box. Repeat this process for each public SSH key that you want to add.
-
To remove a public SSH key, click the removal button next to it:
Repeat this process for each public SSH key that you want to remove.
-
When you are done, click Save at the bottom of the page.
When you have finished, test your changes by trying to connect to your Linux instance through third-party tools.
