This document describes best practices for controlling SSH login accessto Linux virtual machine (VM) instances.

To effectively manage SSH access to VM instances, you must allow users accesswhen they need it, and revoke that access when they don't need it anymore. Ifyour process for revoking access isn't reliable or doesn't cover all resources,then bad actors might be able to hold on to access even after their accessshould have been revoked.

The following sections contain best practices that help you ensure effective accessrevocation and protect against persistence threats:

• Use OS Login to ensure continuous access evaluation against IAM policies
• Use organizational policies to enforce consistent use of OS Login
• Grant privileged roles on a per-VM basis
• Suspend user accounts when users leave the organization
• Avoid granting SSH access to VMs that have a privileged service account
• Pre-create POSIX profiles to ensure consistent usernames and UIDs
• Limit the use of root privileges

The document focuses on practices that are either specific to Google Cloud orof particular relevance when using SSH on Google Cloud. The document doesn'tcover best practices for specific SSH client or server implementations.

Use OS Login to ensure continuous access evaluation against IAM policies

The Compute Enginepublic Linux images are configuredto allow SSH public key authentication. To authorize a user's public key and grantthem permission to a establish an SSH session, you can use one of the followingtwo mechanisms:

• Metadata-based key authorization: As an administrator, you upload auser's public key to VM or project metadataor you let users perform the upload themselves by granting them permission to modify metadata.

  A public key uploaded to the metadata of a single VM grants the user root privilegesto the VM only; a key uploaded to project metadata grants a user access toall VMs in the project.

• OS Login key authorization: As a user, youupload one or more public keys to your OS Login profile, which is part ofyour Google user account.

  As an administrator, you can decide whether to grant a user root privilegesor regular user privileges on the VM by granting either theOS Login Admin User IAM role orOS Login UserIAM role.

  The gcloud CLI, the Google Cloud console in-browserSSH client, andIAP Desktopautomatically detect which mechanism you're using and can upload a user'skey accordingly.

Using metadata-based keys can expose you to persistence threats: Users mightretain SSH access for longer than necessary if their public key isn't removedfrom metadata in a timely manner, and they might even retain access after leavingthe organization. Although you can reduce this risk by regularly scouring metadata,doing so can be difficult in larger environments, and it might be insufficientbecause metadata-based keysgrant users root privileges.

To help protect against such persistence threats, don't allow users to usemetadata-based keys. Instead, configure your projects to enforce the use of OS Login.

Use organizational policies to enforce consistent use of OS Login

OS Login is controlledby theenable-oslogin metadata key:Settingenable-oslogin toTRUE in project or instance metadata enables OS Login,setting it toFALSE disables OS Login.

To modify project-level metadata, you need thecompute.projects.setCommonInstanceMetadatapermission on the project. This permission is part of theCompute Instance Admin (roles/compute.instanceAdmin.v1)andCompute Admin (roles/compute.admin) roles. Similarly, modifying instance-levelmetadata requires thecompute.instances.setMetadata permission on the respectiveVM instance.

Instance-level metadata takes higher precedence than project-level metadata.Settingenable-oslogin toTRUE in project metadata is therefore insufficientto enforce the use of OS Login throughout the project: Users withCompute Instance Adminor equivalent access to a VM instances in the project can override your settingby addingenable-oslogin=FALSE to the VM instance's metadata.

To enforce consistent use of OS Login, don't rely on settingenable-oslogintoTRUE in project metadata. Instead, apply theEnable OS Login for an organization using an organization policyso that any attempts to setenable-oslogin tofalse in instance or projectmetadata are rejected.

Grant privileged roles on a temporary or per-VM basis

If you have VM instances that run different workloads and are managed by differentteams, you can simplify access management by deploying these VMs in differentGoogle Cloud projects, and letting the projects use a shared network.But using separate projects isn't always viable and some of your projects mightcontain a combination of VM instances, where different VM instances should onlybe accessible to different users.

Whenever a project contains such a combination of different VM instances, avoidpermanently granting users roles such asCompute Instance Admin on the project level.Instead, distinguish between view-only and privileged access:

• Grant usersCompute Viewer or an equivalent view-only role on the projectlevel. This role lets users browse VMs using the Google Cloud console,but doesn't let them publish SSH keys or access the VMs.
• Grant users ComputeOS Login,Compute Instance Admin, or other privilegedroles only for individual VMs, oron a just-in-time basis only.

Suspend user accounts when users leave the organization

Suspending or deleting a user account in Cloud Identity or Google Workspace automaticallyrevokes the user's IAM permissions. Because OS Login checks auser's IAM permissions before allowing them to establish anSSH session, suspending or deleting a user account also revokes the user's accessto VMs that use OS Login.

If you've configured Cloud Identity or Google Workspace to usean external IdP for single sign-on, then employees have a user account in bothyour external IdP and in Cloud Identity or Google Workspace.Disabling or deleting an employee's user account in your external IdPrevokes their ability to establish new browser sessions to access Google services,but has no immediate impact on OS Login: As long as the employee's Cloud Identityor Google Workspace user account remains active, OS Login will continue toallow the user to authenticate and establish SSH connections.

To reliably revoke SSH access when a user leaves the organization, make sure tosuspend or delete their Cloud Identity or Google Workspaceuser account. If you use an external IdP, configure it topropagate user suspension eventsso that OS Login can revoke access.

Avoid granting SSH access to VMs that have a privileged service account

If a VM instance has anattachedservice account, then applications running on the VM canrequest short-livedcredentials from the VM's metadata serverand use these credentials toact as the service account.

Having SSH access to a VM grants you similar privileges: Like an application,you can request short-lived credentials from the VM's metadata server andact as the attached service account.

Because having SSH access to a VM with an attached service account lets you actas the service account, OS Login requires you to have theiam.serviceAccounts.actAspermission on the service account, and checks for this permission every time youconnect to the VM instance. That way, OS Login helps maintain the security ofthe service account and prevent SSH access from being abused for privilege escalation.

To further mitigate the risks associated with VMs that have privileged serviceaccounts, consider the following alternatives:

• Don't attach a service account to the VM unless the workload requiresaccess to Google Cloud resources.
• Use asingle-purpose service accountand only grant it access to the resources that workload needs.
• Require users torequest a just-in-time accessinstead of granting them access to the VM and service account on a permanent basis.

Limit the use of root privileges

When you use OS Login and grant a user theOS Login User (roles/compute.osLogin)role, you're assigning the user limited user privileges on the VM. In contrast,when you grant a user theOS Login Admin User (roles/compute.osAdminLogin)role, use metadata-based key authorization instead of OS Login, or allow usersto modify VM metadata, you're implicitly granting the user root privileges onthe VM.

Granting users root privileges on a VM can expose you to persistence risks:Users might abuse these privileges to create new user accounts or installbackdoors to maintain persistent access to the VM.

To help reduce this persistence risk, limit the use of root privileges andonly grant theOS Login User (roles/compute.osLogin) role when root privilegesaren't required.

Pre-create POSIX profiles to ensure consistent usernames and UIDs

Each Linux VM maintains a local database of users (/etc/passwd) and groups (/etc/groups).When you first connect to a Linux VM by using SSH, the guest environmentautomatically creates a Linux user account for you, and assigns it a UID.

When you use metadata-based keys, the guest environment doesn't link the Linux userto your Google user account and might assign you a different UID on each VM youconnect to. If you use protocols such as NFS that assume consistent UIDsin an environment that doesn't enforce consistent UIDs across machines,users might – accidentally or, in the case ofbad actors, deliberately – be able to perform remote access as a different user.

When you use metadata-based keys, the guest environment also lets you choose theusername you want to use. If you choose a username that a coworker used previously,you're logged in with the account that was initially created for your coworker.

You can prevent such UID and username ambiguities by using OS Login: When you firstsign in to a Linux VM by using OS Login, the guest environment creates a Linux userbased on your Google user account'sPOSIX profile.The POSIX profile serves as a template for Linux users and defines the following:

• a Linux username that's unique across all users of the same Cloud Identityor Google Workspace account
• a UID and GID that unique across all Google Cloud projects
• a home directory path
• additional configuration, such as a login shell

If your Google Account doesn't have a POSIX profile when you first sign in,OS Login automatically creates one for you.

The username and UIDs allocated by OS Login are unique within your Google Cloudenvironment, but might overlap or be inconsistent with usernames and UIDs thatyou use outside of Google Cloud. If you need OS Login usernames and UIDsto be consistent across other environments, it's best not to rely on automaticprofile creation. Instead, use theDirectory APIto pre-create OS Login POSIX profiles and assign custom usernames, UIDs, and GIDs.

What's next

• Continue reading aboutbest practices for protecting SSH credentials