Manage SSH Access to GCP Instances with OS Login (2026)

OS Login is GCP’s way of managing SSH access to your Compute Engine instances by tying it to IAM, rather than traditional metadata or SSH keys.

Let’s see it in action. Imagine you’ve got a VM running and you want to SSH into it.

gcloud compute ssh my-instance --zone us-central1-a

If OS Login is enabled and configured correctly, this command will authenticate you using your Google identity. No more managing individual SSH keys on each VM!

The core problem OS Login solves is the sprawl of SSH keys and access control lists across a fleet of VMs. When you have many users and many machines, keeping track of who has access to what, and revoking access when someone leaves, becomes a nightmare. OS Login centralizes this management within IAM.

Here’s how it works internally:

1. User Authentication: When you try to SSH, your SSH client (like gcloud or ssh) uses your Google identity to authenticate with GCP. This is typically done via an OAuth 2.0 token.
2. OS Login API: Your SSH client then contacts the OS Login API. This API checks your IAM roles to determine if you have the necessary permissions to log in to the target instance.
3. Instance Agent: On the Compute Engine instance, a small agent (part of the guest environment) is running. This agent periodically polls the OS Login API for user information and authorized SSH keys associated with the instance.
4. Local User Management: Based on the information from the OS Login API, the agent dynamically creates or manages local user accounts on the instance. It ensures the user’s public SSH key from their Google profile is added to the ~/.ssh/authorized_keys file for the corresponding local user.
5. SSH Daemon: When your SSH client connects to the instance, the SSH daemon (sshd) on the instance is configured to trust the user accounts managed by the OS Login agent. It uses the public keys provided by the agent to authenticate your connection.

The key levers you control are IAM roles and OS Login specific metadata.

• IAM Roles: The most critical roles are roles/compute.osLogin (allows login) and roles/compute.osAdminLogin (allows login with sudo privileges). You grant these roles to users or service accounts at the project or instance level.
• Instance Metadata: You can enable or disable OS Login on a per-instance basis using the enable-oslogin metadata key. Setting it to TRUE enables OS Login for that instance.
• Project Metadata: You can also set enable-oslogin at the project level, which then becomes the default for all new instances in that project unless overridden by instance metadata.

For users to be able to log in, they need the roles/compute.osLogin IAM role, and the enable-oslogin metadata must be set to TRUE on the instance or project. OS Login also respects IAM’s conditions, allowing fine-grained access control based on time, resource, or other attributes.

When OS Login is enabled, the standard SSH key management via instance metadata is disabled. This means any keys you previously added directly to instance metadata will no longer be used for authentication. The OS Login agent on the instance will only provision users based on IAM policy.

The surprising thing about OS Login is how it fundamentally shifts the paradigm from managing credentials on the machine to managing access through an identity provider and policy engine. It means your SSH access is no longer tied to the lifecycle of a specific VM but to the lifecycle of a Google identity.

If you’re using OS Login and encounter issues where users can’t log in, the most common culprit is a misconfiguration of IAM roles. Ensure the user has roles/compute.osLogin granted.

The next concept you’ll likely dive into is managing POSIX account attributes (like UID, GID, home directory) for users when using OS Login, especially if you have specific requirements for how these are set on the instance.