This document describes how to set up OS Login and OS Login with two-factorauthentication (2FA).

OS Login enables you to control access to virtual machine (VM) instances basedon IAM permissions. You can use OS Login with or without 2FA, butyou can't use 2FA without using OS Login. To learn more about OS Login and OSLogin 2FA, including which challenge types OS Login supports, seeAbout OS Login.

Before you begin

• If you want to use OS Login 2FA, enable 2FA on your domain or account:
  • Enable two-factor authentication for your domain.
  • Enable two-factor authentication for your user account.
• If you haven't already, set upauthentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.
  2. Set a default region and zone.

  Terraform

  To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloudauthapplication-defaultlogin

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

  For more information, see Set up authentication for a local development environment.

Limitations

OS Login is not supported on the following VMs:

• Windows Server and SQL Server VMs
• Fedora CoreOS VMs. To manage instance access to VMs created using theseimages, use theFedora CoreOS ignition system

• OS Login 2FA isn't supported on VMs that useworkforce identity federation with OS Login.

Assign OS Login IAM roles

Assign all of the required IAM roles to users who connect to VMs that have OSLogin enabled.

Role	Required users	Grant level
roles/compute.osLogin orroles/compute.osAdminLogin	All users	On theProject orinstance. If a user requires SSH access from Google Cloud console or Google Cloud CLI, you must grant these roles at the project level, or additionally grant a role at the project level that contains thecompute.projects.get permission.
roles/iam.serviceAccountUser	All users, if the VM has a service account	On theService account.
roles/compute.osLoginExternalUser	Users from a different organization than the VM they're connecting to	On theOrganization. This role must be granted by an organization administrator.

Enable OS Login

You can enable OS Login or OS Login with two-factor authentication for a singleVM, or all VMs in a project, by setting OS Login metadata.

When you set OS Login metadata, Compute Engine deletes the VM'sauthorized_keys files and no longer accepts connections from SSH keys that arestored in project or instance metadata.

Note: When OS Login 2FA is enabled on your VM, you must have 2-stepverification set up on yourGoogle Account ordomainto connect. Otherwise, any attempts to access these VMs are denied. 2-stepverification is not enforced on service account users.

Enable OS Login for all VMs in a project

To enable OS Login for all VMs in a project, set the following values inproject metadata:

1. Enable OS Login:
   • Key:enable-oslogin
   • Value:TRUE
2. (Optional) Enable two-factor authentication:
   • Key:enable-oslogin-2fa
   • Value:TRUE

Enable OS Login for a single VM

To enable OS Login for a single VM, set the following values ininstance metadata:

1. Enable OS Login:
   • Key:enable-oslogin
   • Value:TRUE
2. (Optional) Enable two-factor authentication:
   • Key:enable-oslogin-2fa
   • Value:TRUE

Enable OS Login during VM creation

Enable OS Login (optionally, with 2-step verification) while creating a VM usingthe Google Cloud console or the gcloud CLI.

Connect to VMs that have OS Login enabled

Connect to VMs that have OS Login enabled by using the methods described inConnect to Linux VMs.

When you connect to VMs that have OS Login enabled, Compute Engine uses theusername that your organization administrator configured for you.If your organization administrator hasn't configured a username for you,Compute Engine generates a username in the format ofUSERNAME_DOMAIN_SUFFIX.For more information about usernames, seeHow OS Login works.

When you connect to VMs that have OS Login 2FA enabled, you also see a messagebased on your selected 2-step verification method or challenge type. For thephone prompt method, accept the prompts on your phone or tablet to continue. Forother methods, enter your security code or one-time password.

Troubleshoot OS Login

To find methods for diagnosing and resolving OS Login errors, seeTroubleshooting OS Login.

What's next

• Learn howSSH connections to Linux VMs work onCompute Engine.
• Learn how to useSSH certificates (Preview) to connectto VMs.
• Learn how to useSSH with security keys (Preview)to further restrict access to VMs.