How to turn on OS Login for Compute Engine SSH in Google Cloud
This guide moves SSH access to Compute Engine VMs from loose SSH keys in metadata to IAM-controlled OS Login, and closes the serial console alongside it. It is for Google Cloud admins who want to grant and revoke VM access centrally.
Before you start
Before you start
OS Login ties SSH access to a Google identity and IAM roles, so access is granted and removed in one place instead of by editing keys on each VM.
- Roles for your admin: permission to edit project metadata and instance metadata, and to grant IAM roles on the project.
- Roles for the people who connect:
roles/compute.osLogin(standard user) orroles/compute.osAdminLogin(administrator). Users from a different organization than the VM also needroles/compute.osLoginExternalUser, granted at organization level. - Tools: the gcloud CLI, signed in with
gcloud auth login, with the right project set. - Limits: Google documents that OS Login is not supported on Windows Server or SQL Server images; check Google's OS Login page for the full list of unsupported images.
- Warning: once OS Login is on, Compute Engine deletes the VM's
authorized_keysfiles and stops accepting SSH keys stored in project or instance metadata. Make sure people have their IAM roles first, or they lose access.
Step by step
Step by step
- List who connects to your VMs today and decide who gets
roles/compute.osLoginand who getsroles/compute.osAdminLogin. - In the Google Cloud console open IAM & Admin > IAM for the project and grant those roles. Grant them at project level so the console and gcloud SSH work without extra permissions.
- Turn on OS Login for the whole project by setting the project metadata key
enable-oslogintoTRUE(command in the change section below). - Optional: require 2-Step Verification for SSH by also setting
enable-oslogin-2fatoTRUE. Both keys must beTRUEfor it to apply, and users need 2-Step Verification on their Google account or access is denied. - Turn off the interactive serial console by setting
serial-port-enabletoFALSE. Google also offers the organization policy constraintcompute.disableSerialPortAccess, which blocks serial console access for every project in the organization regardless of that key. - Look for VMs that override the project setting. An instance-level
enable-osloginvalue ofFALSEwins over the project-levelTRUE. - For any VM that must stay on metadata SSH keys for now, set
block-project-ssh-keystoTRUEon that VM so project-wide keys are not accepted there. Google notes that users with keys in the instance's own metadata can still get in. - Ask one admin and one standard user to connect, then remove the old keys from project and instance metadata once everyone is confirmed.
Check it worked
Check it worked
These commands only read. Show the project-level metadata and look for enable-oslogin and serial-port-enable:
gcloud compute project-info describe --format='json(commonInstanceMetadata.items)'
List every VM with its own metadata, to spot instance-level overrides:
gcloud compute instances list --format='json(name,zone,metadata.items)'
Check the OS Login profile of the account you are signed in with:
gcloud compute os-login describe-profile
Changes: commands that modify the project
These commands change your project. Metadata updates through gcloud are additive: keys you do not list are kept. Run them against the project you intend to change.
# Turn on OS Login for the project
gcloud compute project-info add-metadata --metadata=enable-oslogin=TRUE
# Optional: require 2-Step Verification
gcloud compute project-info add-metadata --metadata=enable-oslogin-2fa=TRUE
# Turn off the interactive serial console for the project
gcloud compute project-info add-metadata --metadata=serial-port-enable=FALSE
# One VM that must stay on metadata keys: ignore project-wide keys
gcloud compute instances add-metadata VM_NAME --zone=ZONE --metadata=block-project-ssh-keys=TRUECommon mistakes
Common mistakes
- Turning it on before granting roles. People are locked out as soon as metadata keys stop working.
- Forgetting instance overrides. A VM set to
enable-oslogin=FALSEkeeps using metadata keys even when the project saysTRUE. - Granting
osAdminLoginto everyone. Give administrator rights only to those who need sudo. - Cross-organization users. They need
roles/compute.osLoginExternalUseras well. - Relying on 2-Step Verification for service accounts. Google states it is not enforced for service account users.
- Leaving old keys in metadata. They stop working under OS Login, but stale keys still make later audits noisy; remove them once access is confirmed.
How ConfigCobra helps
How ConfigCobra helps
ConfigCobra is read-only and never changes your Google Cloud environment. It reads your organization with a service account that has viewer-level roles, across every project or a list you choose, and assesses against the CIS Google Cloud Platform Foundation Benchmark v5.0.0 (93 controls). Controls related to this guide include enabling OS Login for the project (4.4), blocking project-wide SSH keys on VM instances (4.3), disabling serial-port connections (4.5), no public IP on compute instances (4.9) and restricting SSH from the internet (3.6).
- Remediation impact analysis shows the affected resources and identities before you apply a fix.
- Scheduled scans (daily, weekly or monthly) and drift detection alert you by email if a control regresses.
- Each finding comes with a copy-paste remediation script or portal steps for you to review and run yourself.
Go further
- All guidesAdmin how-tos for Microsoft 365, Azure, Google Cloud and AWS
- Check libraryEvery CIS check, explained
- RemediationSee what a fix changes in your tenant before you apply it, then use the generated script
- Inventory & InsightsEvery user, app, device and resource in one inventory, with built-in risk views
See where your Google Cloud stands
A read-only assessment against the CIS benchmarks, prioritised so you know what to fix first.