GCP OS Login Explained: IAM-Based SSH Access for Compute Engine

What is OS Login?

OS Login is a Compute Engine feature that replaces SSH key management in VM metadata with centralised IAM-based access control.

With the traditional approach, you store SSH public keys in VM metadata: either at the project level (which applies to every VM) or at the instance level (per VM). Managing those keys across many VMs and many team members becomes messy. When someone leaves, you have to find and remove their key from every place it was added.

OS Login works differently. Access is controlled by IAM roles assigned to Google identities (user accounts or service accounts). When a user with the right IAM role runs gcloud compute ssh, GCP validates their identity and IAM permissions in real time, creates a Linux user account on the VM automatically, and establishes the connection. No keys need to be manually distributed, and no metadata needs to be edited on individual VMs.

Why OS Login exists: the SSH key management problem

SSH key metadata access works well for a single developer on a personal project. It starts to break down the moment a team is involved.

• Key sprawl. As the team grows, keys accumulate in project metadata and get added to individual VMs. There is no central view of who has access to what.

• Offboarding is manual and error-prone. When a team member leaves, someone must remember to remove their key from project metadata and from every instance it was added to individually. A missed key means stale access.

• No automatic audit trail. Metadata-based SSH access does not produce a log entry per connection in the same structured way OS Login does. You cannot easily audit who connected to which VM and when.

• Inconsistent access scope. Project-level keys grant access to every VM in the project by default, which is wider than most users should have. Scoping access per VM using metadata requires editing each VM individually.

OS Login addresses all of these by moving access decisions into IAM, where they are already centralised, auditable, and consistently enforced.

How OS Login works

When a user runs gcloud compute ssh on a VM with OS Login enabled, the following happens:

1. GCP checks whether the user has compute.osLogin or compute.osAdminLogin permission on the instance or the project it belongs to.

2. If the permission is present, GCP looks up or creates a POSIX user account on the VM tied to the user’s Google identity. The Linux username is derived from the user’s Google account.

3. The SSH connection is established using the user’s OS Login profile keys (SSH public keys stored in the OS Login profile, not in VM metadata).

4. The connection is logged in Cloud Audit Logs under the compute.googleapis.com service: who connected, to which VM, and when.

When you remove the user’s IAM role binding, the permission check fails on the next connection attempt. Access is revoked immediately. No key cleanup required. The Linux user account remains in the OS, but the user cannot authenticate without the IAM role.

When OS Login is enabled on a VM, project-level SSH key metadata and per-instance SSH key metadata are both ignored. Keys stored directly in VM metadata no longer grant access.

Required roles and permissions

Two roles control OS Login access. Both are part of the Compute Engine IAM role set:

• roles/compute.osLogin: grants SSH access as a standard Linux user. The user can log in and run commands but does not have sudo privileges.

• roles/compute.osAdminLogin: grants SSH access with sudo privileges. This gives the user effective root access on the VM.

Both roles can be granted at the project level (applies to all VMs in the project) or at the instance level (applies to one VM only). Instance-level grants are preferable for developers who only need access to specific VMs. Project-level grants suit administrators who need broad access, but even then, use osLogin rather than osAdminLogin unless root access is genuinely required.

Users also need permissions to look up instance metadata when using gcloud compute ssh. roles/compute.viewer or a custom role with compute.instances.get is typically sufficient alongside the OS Login role.

# Grant standard SSH access at the project level
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=user:alice@example.com \
  --role=roles/compute.osLogin

# Grant sudo SSH access at the project level
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member=user:bob@example.com \
  --role=roles/compute.osAdminLogin

# Grant SSH access on a single VM only (instance-level)
gcloud compute instances add-iam-policy-binding my-vm \
  --zone=us-central1-a \
  --member=user:alice@example.com \
  --role=roles/compute.osLogin

# Revoke access immediately (no key cleanup needed)
gcloud projects remove-iam-policy-binding PROJECT_ID \
  --member=user:alice@example.com \
  --role=roles/compute.osLogin

For teams managing a lot of OS Login bindings via code, see managing IAM with gcloud. For fine-grained access that varies by environment or time window, see IAM conditions.

How to enable OS Login

OS Login is enabled through metadata, not through the IAM console. You can set it at the project level (applies to all VMs) or at the instance level (applies to one VM and overrides the project setting).

# Enable OS Login for all VMs in a project
gcloud compute project-info add-metadata \
  --metadata=enable-oslogin=TRUE

# Enable OS Login on a specific VM only
gcloud compute instances add-metadata my-vm \
  --zone=us-central1-a \
  --metadata=enable-oslogin=TRUE

# Override to keep key-based access on a specific VM
# even when OS Login is enabled project-wide
gcloud compute instances add-metadata my-vm \
  --zone=us-central1-a \
  --metadata=enable-oslogin=FALSE

Rolling out safely to an existing team

A safe rollout sequence:

1. Identify every user with current SSH access and determine which IAM role they should receive.

2. Grant each user the appropriate role (osLogin or osAdminLogin) before making any metadata change.

3. Enable OS Login on a single test VM using instance-level metadata and verify each user can still connect.

4. Once verified, roll out project-wide. Keep a break-glass account available during the transition.

How users add their SSH keys to an OS Login profile

Users can add SSH public keys to their OS Login profile. These keys are stored centrally in Google’s identity system, not in any individual VM’s metadata. Once added, a key works on any VM where that user has the OS Login IAM role. No per-VM key setup required.

This is one of the main practical advantages over metadata SSH keys: a developer with access to 20 VMs only needs to add their public key once. The key follows their identity, not the VM.

# Add an SSH public key to your OS Login profile
gcloud compute os-login ssh-keys add \
  --key-file=~/.ssh/id_ed25519.pub

# List SSH keys currently in your profile
gcloud compute os-login ssh-keys list

# Remove a key by its fingerprint
gcloud compute os-login ssh-keys remove \
  --key=KEY_FINGERPRINT

Enforcing MFA for SSH

OS Login supports mandatory two-factor authentication (2FA) for SSH connections. When enabled, a successful IAM role check is not enough. The user must also complete a second factor: a TOTP code from Google Authenticator or a compatible app, or a hardware security key.

This is worth enabling in any environment where VMs hold sensitive data, are exposed to the internet, or need to meet a compliance requirement such as PCI-DSS, HIPAA, or SOC 2 that specifies MFA for privileged access.

# Enable OS Login with 2FA project-wide
gcloud compute project-info add-metadata \
  --metadata=enable-oslogin=TRUE,enable-oslogin-2fa=TRUE

# Enable OS Login with 2FA on a specific VM
gcloud compute instances add-metadata my-vm \
  --zone=us-central1-a \
  --metadata=enable-oslogin=TRUE,enable-oslogin-2fa=TRUE

When to use OS Login

OS Login is the right default for most team-managed Compute Engine environments. It fits cleanly when:

• Multiple people need VM access. Even with two developers, centralising access control in IAM is cleaner and safer than passing keys around.

• People join and leave the team regularly. OS Login makes onboarding and offboarding instant and complete. A removed IAM binding revokes all VM access in one command.

• You have many VMs. Managing per-VM SSH key metadata at scale is fragile. OS Login lets the IAM policy do the heavy lifting.

• Audit logging matters. Every OS Login SSH connection appears in Cloud Audit Logs automatically. Key-based metadata access does not produce the same structured audit trail.

• Compliance or production requirements. Most security frameworks expect centralised access management, evidence of revocation, and logs of who accessed what. OS Login satisfies all three.

• You use service accounts alongside human access. OS Login integrates naturally with the IAM model you are already using for service accounts and other GCP resources.

When OS Login may not be your first priority

If you are spinning up a personal sandbox VM for a learning lab or a quick test, key-based metadata access is faster to set up and perfectly adequate. OS Login adds the most value in team, production, or compliance-sensitive contexts. For a single-developer personal project, the overhead of IAM role management may outweigh the benefit.

For all the SSH options available in Compute Engine, including IAP tunnelling and when to use each, see SSH access in Compute Engine.

OS Login vs SSH keys in metadata

Both approaches let users SSH into Compute Engine VMs. The differences matter when operating at team scale or under security requirements.