This page describes the OS Login service and how it works. To learn how to setup OS Login, seeSet up OS Login.

Use OS Login to manage SSH access to your instances using IAMwithout having to create and manage individual SSH keys. OS Login maintains aconsistent Linux user identity across VM instances and is the recommended way tomanage many users across multiple VMs or projects.

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.

Benefits of OS Login

OS Login simplifies SSH access management by linking your Linux user account toyour Google identity. Administrators can easily manage access to instances ateither an instance or project level by setting IAM permissions.

OS Login provides the following benefits:

• Automatic Linux account lifecycle management - You can directly tiea Linux user account to a user's Google identity so that the same Linuxaccount information is used across all instances in the same project ororganization.

• Fine grained authorization using Google IAM - Projectand instance-level administrators can use IAM to grant SSHaccess to a user's Google identity without granting a broader set ofprivileges. For example, you can grant a user permissions to log into thesystem, but not the ability to run commands such assudo. Google checksthese permissions to determine whether a user can log into a VM instance.

• Automatic permission updates - With OS Login, permissions are updatedautomatically when an administrator changes IAMpermissions. For example, if you remove IAM permissions froma Google identity, then access to VM instances is revoked. Google checkspermissions for every login attempt to prevent unwanted access.

• Ability to import existing Linux accounts - Administratorscan choose to optionally synchronize Linux account information fromActive Directory (AD) and Lightweight Directory Access Protocol (LDAP) thatare set up on-premises. For example, you can ensure that users have thesame user ID (UID) in both your Cloud and on-premises environments.

• Integration with Google Account two-step verification - You can optionallyrequire that OS Login users validate their identity using one of the following2-step verification (2FA) methods or challenge types when connecting to VMs:

  • Google Authenticator
  • Text message or phone call verification
  • Phone prompts
  • Security key one-time password (OTP)

• Support for certificate-based authentication - You can use SSH certificateauthentication to connect to VMs that use OS Login. For more information, seeRequire SSH certificates with OS Login.

• Integration with audit logging - OS Login providesaudit logging that you can use tomonitor connections to VMs for OS Login users.

How OS Login works

When OS Login is enabled, Compute Engine performs configurationson VMs and the Google accounts of OS Login users.

VM configuration

When you enable OS Login, the VM fetches the SSH keys associated with theLinux user account from the OS Login service to authenticate a login attempt.

You can configure anauthorized_keys file to provision access for a local useraccount even when OS Login is enabled. SSH public keys that are configured intheauthorized_keys file are used to authenticate user login attempts by thelocal user. Local user accounts and OS Login users must have different usernamesand UIDs.

Note: VMs that use OS Login can't use metadata-based SSH keys. If you enableOS 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, seeAdd SSH keys to VMs.

For more information about the OS Login components, review theOS Login GitHub page.

User account configuration

OS Login configures your Google account with POSIX information, including ausername, 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 ofUSERNAME_DOMAIN_SUFFIX.If the user is from a different Google Workspace organization than theone hosting their OS Login-enabled VMs, their username is prefixedwithext_. If the user is a service account, its username is prefixed withsa_. Usernames cannot exceed 32 characters. Usernames that exceed 32characters are truncated.

  Cloud Identity administrators canmodify usernamesand Google Workspace super administrators can change the usernameformat toremove the domain suffix.

• UID: a unique, randomly-generatedPOSIX-compliant user ID.

• GID: a POSIX-compliant group ID that is the same as the UID.

• Home directory: the path to the user's home directory.

Organization administrators can configure and update a user's POSIX accountinformation. For more information, seeModify user accounts using the Directory API.

What's next

• For step-by-step instructions, review one of the following:
  • Setting up OS Login.
  • Setting up OS Login with 2-step verification
• ReviewManaging OS Login in an organization
• Troubleshoot OS Login.