Stay organized with collections
Save and categorize content based on your preferences.
This page describes the OS Login service and how it works. To learn how to set
up OS Login, see Set up OS Login.
Use OS Login to manage SSH access to your instances using IAM
without having to create and manage individual SSH keys. OS Login maintains a
consistent Linux user identity across VM instances and is the recommended way to
manage many users across multiple VMs or projects.
Benefits of OS Login
OS Login simplifies SSH access management by linking your Linux user account to
your Google identity. Administrators can easily manage access to instances at
either an instance or project level by setting IAM permissions.
OS Login provides the following benefits:
Automatic Linux account lifecycle management - You can directly tie
a Linux user account to a user's Google identity so that the same Linux
account information is used across all instances in the same project or
organization.
Fine grained authorization using Google IAM - Project
and instance-level administrators can use IAM to grant SSH
access to a user's Google identity without granting a broader set of
privileges. For example, you can grant a user permissions to log into the
system, but not the ability to run commands such as sudo. Google checks
these permissions to determine whether a user can log into a VM instance.
Automatic permission updates - With OS Login, permissions are updated
automatically when an administrator changes IAM
permissions. For example, if you remove IAM permissions from
a Google identity, then access to VM instances is revoked. Google checks
permissions for every login attempt to prevent unwanted access.
Ability to import existing Linux accounts - Administrators
can choose to optionally synchronize Linux account information from
Active Directory (AD) and Lightweight Directory Access Protocol (LDAP) that
are set up on-premises. For example, you can ensure that users have the
same user ID (UID) in both your Cloud and on-premises environments.
Integration with Google Account two-step verification - You can optionally
require that OS Login users validate their identity using one of the following
2-step verification (2FA) methods or challenge types when connecting to VMs:
Support for certificate-based authentication (Preview) - You can use SSH
certificate authentication to connect to VMs that use OS Login. For more
information, see
Require SSH certificates with OS Login.
Integration with audit logging - OS Login provides
audit logging that you can use to
monitor connections to VMs for OS Login users.
How OS Login works
When OS Login is enabled, Compute Engine performs configurations
on VMs and the Google accounts of OS Login users.
VM configuration
When you enable OS Login, Compute Engine deletes the VM's authorized_keys
files and configures an OpenSSH server. This server retrieves the SSH keys
associated with the Linux user account to authenticate the login attempt.
You can configure an authorized_keys file to provision access for a local user
account even when OS Login is enabled. SSH public keys that are configured in
the authorized_keys file are used to authenticate user login attempts by the
local user. Local user accounts and OS Login users must have different usernames
and UIDs.
For more information about the OS Login components, review the
OS Login GitHub page.
User account configuration
OS Login configures your Google account with POSIX information, including a
username, when you do any of the following:
Connect to an OS Login-enabled VM using the Google Cloud console
Connect to an OS Login-enabled VM using the gcloud CLI
Import a public SSH key using the gcloud CLI
Import a public SSH key using the OS Login API
OS Login configures POSIX accounts with the following values:
Username: a username in the format of
USERNAME_DOMAIN_SUFFIX.
If the user is from a different Google Workspace organization than the
one hosting their OS Login-enabled VMs, their username is prefixed
with ext_. If the user is a service account, its username is prefixed with
sa_.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-29 UTC."],[[["\u003cp\u003eOS Login streamlines SSH access management by linking Linux user accounts to Google identities, eliminating the need for individual SSH key management.\u003c/p\u003e\n"],["\u003cp\u003eIt leverages Google IAM for fine-grained authorization, enabling administrators to control access at the instance or project level and grant specific permissions, such as login without \u003ccode\u003esudo\u003c/code\u003e rights.\u003c/p\u003e\n"],["\u003cp\u003eOS Login automates Linux account lifecycle management, ensuring consistent user information across VMs, and automatically updates permissions based on changes in IAM settings.\u003c/p\u003e\n"],["\u003cp\u003eThe system supports integration with two-step verification methods and provides audit logging for monitoring VM connections.\u003c/p\u003e\n"],["\u003cp\u003eWhen OS Login is enabled, it configures VMs by managing \u003ccode\u003eauthorized_keys\u003c/code\u003e files, setting up an OpenSSH server with \u003ccode\u003eAuthorizedKeysCommand\u003c/code\u003e, configuring NSS functionality, and adding PAM configurations.\u003c/p\u003e\n"]]],[],null,["# About OS Login\n\n*** ** * ** ***\n\nThis page describes the OS Login service and how it works. To learn how to set\nup OS Login, see [Set up OS Login](/compute/docs/oslogin/set-up-oslogin).\n\nUse OS Login to manage SSH access to your instances using IAM\nwithout having to create and manage individual SSH keys. OS Login maintains a\nconsistent Linux user identity across VM instances and is the recommended way to\nmanage many users across multiple VMs or projects.\n| **Note:** When a user connects to a VM, that user can use all of the IAM permissions granted to the service account attached to the VM.\n\nBenefits of OS Login\n--------------------\n\nOS Login simplifies SSH access management by linking your Linux user account to\nyour Google identity. Administrators can easily manage access to instances at\neither an instance or project level by setting IAM permissions.\n\nOS Login provides the following benefits:\n\n- **Automatic Linux account lifecycle management** - You can directly tie\n a Linux user account to a user's Google identity so that the same Linux\n account information is used across all instances in the same project or\n organization.\n\n- **Fine grained authorization using Google IAM** - Project\n and instance-level administrators can use IAM to grant SSH\n access to a user's Google identity without granting a broader set of\n privileges. For example, you can grant a user permissions to log into the\n system, but not the ability to run commands such as `sudo`. Google checks\n these permissions to determine whether a user can log into a VM instance.\n\n- **Automatic permission updates** - With OS Login, permissions are updated\n automatically when an administrator changes IAM\n permissions. For example, if you remove IAM permissions from\n a Google identity, then access to VM instances is revoked. Google checks\n permissions for every login attempt to prevent unwanted access.\n\n- **Ability to import existing Linux accounts** - Administrators\n can choose to optionally synchronize Linux account information from\n Active Directory (AD) and Lightweight Directory Access Protocol (LDAP) that\n are set up on-premises. For example, you can ensure that users have the\n same user ID (UID) in both your Cloud and on-premises environments.\n\n- **Integration with Google Account two-step verification** - You can optionally\n require that OS Login users validate their identity using one of the following\n 2-step verification (2FA) methods or challenge types when connecting to VMs:\n\n - [Google Authenticator](https://support.google.com/accounts/answer/1066447)\n - Text message or phone call verification\n - [Phone prompts](https://support.google.com/accounts/answer/7026266)\n - [Security key one-time password (OTP)](https://gsuiteupdates.googleblog.com/2019/06/security-codes-and-security-keys.html)\n- **Support for certificate-based authentication (Preview)** - You can use SSH\n certificate authentication to connect to VMs that use OS Login. For more\n information, see\n [Require SSH certificates with OS Login](/compute/docs/oslogin/certificates).\n\n- **Integration with audit logging** - OS Login provides\n [audit logging](/compute/docs/oslogin/view-audit-logs) that you can use to\n monitor connections to VMs for OS Login users.\n\nHow OS Login works\n------------------\n\nWhen OS Login is enabled, Compute Engine performs configurations\non VMs and the Google accounts of OS Login users.\n\n### VM configuration\n\nWhen you enable OS Login, Compute Engine deletes the VM's `authorized_keys`\nfiles and configures an OpenSSH server. This server retrieves the SSH keys\nassociated with the Linux user account to authenticate the login attempt.\n\nYou can configure an `authorized_keys` file to provision access for a local user\naccount even when OS Login is enabled. SSH public keys that are configured in\nthe `authorized_keys` file are used to authenticate user login attempts by the\nlocal user. Local user accounts and OS Login users must have different usernames\nand UIDs.\n| **Note:** VMs that use OS Login can't use metadata-based SSH keys. If you enable OS Login for a VM, then the VM's guest agent ignores the keys stored in metadata. To learn more about using SSH keys with VMs, see [Add SSH keys to VMs](/compute/docs/connect/add-ssh-keys).\n\nFor more information about the OS Login components, review the\n[OS Login GitHub page](https://github.com/GoogleCloudPlatform/guest-oslogin#overview).\n\n### User account configuration\n\nOS Login configures your Google account with POSIX information, including a\nusername, when you do any of the following:\n\n- Connect to an OS Login-enabled VM using the Google Cloud console\n- Connect to an OS Login-enabled VM using the gcloud CLI\n- Import a public SSH key using the gcloud CLI\n- Import a public SSH key using the OS Login API\n\nOS Login configures POSIX accounts with the following values:\n\n- **Username:** a username in the format of\n \u003cvar translate=\"no\"\u003eUSERNAME\u003c/var\u003e`_`\u003cvar translate=\"no\"\u003eDOMAIN\u003c/var\u003e`_`\u003cvar translate=\"no\"\u003eSUFFIX\u003c/var\u003e.\n If the user is from a different Google Workspace organization than the\n one hosting their OS Login-enabled VMs, their username is prefixed\n with `ext_`. If the user is a service account, its username is prefixed with\n `sa_`.\n\n Cloud Identity administrators can\n [modify usernames](/compute/docs/oslogin/manage-oslogin-in-an-org#modify-users)\n and Google Workspace super administrators can change the username\n format to\n [remove the domain suffix](/compute/docs/oslogin/manage-oslogin-in-an-org#manage-oslogin-api).\n- **UID:** a unique, randomly-generated\n [POSIX-compliant](https://en.wikipedia.org/wiki/User_identifier) user ID.\n\n- **GID:** a POSIX-compliant group ID that is the same as the UID.\n\n- **Home directory:** the path to the user's home directory.\n\nOrganization administrators can configure and update a user's POSIX account\ninformation. For more information, see\n[Modify user accounts using the Directory API](/compute/docs/oslogin/manage-oslogin-in-an-org#modify-users).\n\nWhat's next\n-----------\n\n- For step-by-step instructions, review one of the following:\n - [Setting up OS Login](/compute/docs/instances/managing-instance-access).\n - [Setting up OS Login with 2-step verification](/compute/docs/oslogin/setup-two-factor-authentication)\n- Review [Managing OS Login in an organization](/compute/docs/oslogin/manage-oslogin-in-an-org)\n- [Troubleshoot](/compute/docs/oslogin/troubleshoot-os-login) OS Login."]]
