Setting up OS Login with 2-step verification

This document covers the basic steps for setting up OS Login with 2-step verification.

If you use OS Login to manage access to your virtual machine (VM) instances, you can add an extra layer of security by using 2-step verification also known as two-factor authentication, or 2FA. To learn more about the other benefits of using OS Login, see OS Login.

To use OS Login 2FA on your VMs, complete the following steps:

1. Enable 2-step verification for your Google Account or domain.

   Note: When OS Login 2FA is enabled on your VM, you must have 2-step verification set up on your Google Account or domain to log in. Otherwise, any attempts to access these VMs are denied. 2-step verification is not enforced on service account users.

2. Enable 2FA on your project or VM.

3. Grant the necessary IAM roles to yourself or other principals.

To further restrict VM access, you can set up hardware-backed SSH key pairs. For more information, see SSH with security keys.

After setting up OS Login 2FA, you can use audit logs to monitor your authentication sessions.

Before you begin

• If you want to use the command-line examples in this guide, do the following:
  1. Install or update to the latest version of the Google Cloud CLI.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• For information about how SSH connections work in Compute Engine, including SSH key configuration and storage, see SSH connections to Linux VMs.

Limitations

OS Login is not supported in the following products, features, and VMs:

• Cloud Data Fusion versions 6.1.4 and earlier
• Cloud Composer
• Google Kubernetes Engine (GKE) public clusters that run versions earlier than 1.23.5
• GKE private clusters that run node pool versions earlier than 1.20.5
• Dataproc Serverless
• Windows Server and SQL Server VMs
• Fedora CoreOS VMs. To manage instance access to VMs created using these images, use the Fedora CoreOS ignition system

Supported methods or challenge types

OS Login supports the following 2-step verification methods or challenge types:

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

Step 1: Enable 2-step verification for your Google Account or domain

Before you can enable OS Login 2FA for your project or VM, you must first enable 2-step verification on your Google Account or domain. Make sure that you either enable 2-step verification on the domain that contains the project or VMs or enable 2-step verification for the user that owns the project or VMs.

As a security best practice, require 2-step verification on user accounts in your organization. Enabling OS Login 2FA doesn't block login access to users who don't have two-factor authentication configured.

A Google Workspace administrator can enable 2-step verification for a domain, or an individual Google user can enable 2-step verification for a user-account.

Domain

2-step verification for a domain must be enabled by a Google Workspace administrator.

To enable 2-step verification for a domain, see Protect your business with 2-Step Verification in the Google Workspace Admin guide.

User account

If your user accounts are not managed by a Google Workspace administrator, you can configure 2-step verification for individual Google Accounts.

To configure 2-step verification for an individual Google Account, see Google 2-Step Verification.

Step 2: Enable OS Login 2FA on your project or VM

After you enable 2-step verification for a domain or user account, you can then enable individual VMs or projects to use OS Login 2FA. A VM or project must have OS Login enabled in order to use OS Login 2FA.

You can configure both OS Login and OS Login 2FA during VM creation or project setup. You can also configure OS Login 2FA on an existing VM or project that already has OS Login enabled.

To configure your project or VM to use OS Login two-factor authentication, set enable-oslogin-2fa=TRUE and enable-oslogin=TRUE in the project or instance metadata. Enabling OS Login with two-factor authentication in instance metadata overrides the value that is set in project metadata.

Console

You can apply the metadata values on your projects or VMs using one of the following options:

• Option 1: Enable OS Login with two-factor authentication when you create a VM.

  1. In the console, go to the Create an instance page.

     Go to Create an instance

  2. Expand Networking, disks, security, management, sole tenancy to reveal additional configuration options.
  3. Expand the Security section.
  4. Expand the Manage access section.
  5. Select Control VM access through IAM permissions.
  6. Select Require 2-step verification.
  7. To create the VM, click Create.

• Option 2: Set enable-oslogin-2fa and enable-oslogin=TRUE in project-wide metadata so that the setting is applied to all of the VMs in your project.

  1. In the Google Cloud console, go to the Metadata page.

     Go to Metadata

  2. Click Edit.

  3. In the Metadata section, add the following metadata entries:

     • Set enable-oslogin to TRUE.
     • Set enable-oslogin-2fa to TRUE.

  4. Click Save to apply the changes.

• Option 3: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in the metadata of an existing VM.

  1. In the Google Cloud console, go to the VM instances page.

     Go to VM instances

  2. Click the name of the VM on which you want to set the metadata value.

  3. On the Instance details page, click Edit.

  4. Under Custom metadata, add the following metadata entries:

     • Set enable-oslogin to TRUE.
     • Set enable-oslogin-2fa to TRUE.

  5. On the Instance details page, click Save to apply your changes to the instance.

gcloud

You can apply the metadata values on your projects or VMs by using one of the following options:

• Option 1: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in instance metadata when you create a VM.

  1. Create a Compute Engine instance. Configure the instance as follows:
     • Replace INSTANCE_NAME with your preferred instance name.
     • Set the --zone flag to the zone in which you want to create your instance.
     • Set enable-oslogin and enable-oslogin-2fa to TRUE in instance metadata to enable OS Login with 2-step verification.

     gcloud compute instances create INSTANCE_NAME --zone=ZONE --metadata=enable-oslogin=TRUE,enable-oslogin-2fa=TRUE

  Replace VM_NAME with the name of your VM.

• Option 2: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in project-wide metadata, so that it applies to all of the VMs in your project.

  gcloud compute project-info add-metadata \
    --metadata enable-oslogin=True,enable-oslogin-2fa=True
  

• Option 3: Set enable-oslogin=TRUE and enable-oslogin-2fa=TRUE in metadata of an existing VM.

  gcloud compute instances add-metadata \
    --metadata enable-oslogin=True,enable-oslogin-2fa=True VM_NAME
  

  Replace VM_NAME with the name of your VM.

Step 3: Configure OS Login roles on user accounts

Granting OS Login IAM roles

After you enable OS Login on one or more instances in your project, those VMs accept connections only from user accounts that have the necessary IAM roles in your project or organization.

To allow OS Login access to these VMs, you need to grant the necessary roles to the user. To allow OS Login access, complete the following steps:

1. If the user doesn't have the roles/owner role, roles/editor role, or roles/compute.instanceAdmin role, grant one of the following instance access roles:

   • roles/compute.osLogin, which doesn't grant administrator permissions

   • roles/compute.osAdminLogin, which grants administrator permissions

     You can grant the instance access role at the project level or at the instance level. If a user requires SSH access from console or gcloud CLI, you must grant the instance access role at the project level, or additionally grant a role at the project level that contains the compute.projects.get permission.

2. If your VM uses a service account, then each user that connects to the VM using SSH must have the ability to impersonate the service account. To ensure that the impersonation follows best practices, configure each user to have the roles/iam.serviceAccountUser role on the service account. To learn how to add access for a user to a service account, see Managing service account impersonation.

   Note: VMs created by using the Google Cloud console or the Google Cloud CLI have a service account associated by default. VMs that don't have an associated service account don't require this permission. To check if you have an associated service account, see Checking if your VM has a service account.

3. For users that are outside of your organization to access your VMs, in addition to granting an instance access role, grant the roles/compute.osLoginExternalUser role, which enables POSIX account creation. This role must be granted at the organization level by an organization administrator. For more information, see Granting instance access to users outside of your organization.

Granting SSH access to a service account

You can use OS Login roles to allow service accounts to establish SSH connections to your instances. This is useful for the following tasks:

• If your applications require SSH access to your Compute Engine instances, you can provide that access through a service account. For more information, see Connecting apps to instances using SSH.
• For information about how to manually assume the permissions of a service account and use those permissions to execute commands on a second instance, read Manually connecting between instances as a service account.

You can grant SSH access to your service accounts by using the following process:

1. Create a service account.
2. Grant the necessary OS Login roles to your service account. Service accounts require the same roles as user accounts. To learn how to configure roles and permissions for service accounts, see Granting roles to service accounts.
3. Provide Application Default Credentials to your service account, so that it can authorize requests to the necessary APIs. Provide Application Default Credentials using one of the following options:
   • Create an instance that is associated with your service account. The instance provides Application Default Credentials to your service account.
   • Manually provide service account credentials to your app if you run your app outside of the Compute Engine environment.

After you grant SSH access to your service accounts, you can configure your apps to create SSH keys and establish SSH connections to other instances on your VPC networks. To see an example app for service account SSH, read the Connecting apps to instances using SSH tutorial.

Revoking OS Login IAM roles

To revoke user access to instances that are enabled to use OS Login, remove the user roles from that user account. For information about removing an IAM role for a user, see Granting, changing, and revoking access to resources.

When a user's access is revoked, the user will still have public SSH keys that are associated with their account, but those keys no longer function on the VM instances.

Note: Users with active SSH connections aren't disconnected and retain their sudo privileges until the next time they establish an SSH connection. Compute Engine determines a user's authentication, authorization, and sudo privileges only when a user establishes a connection to an instance.

Step 4: Connect to VMs

When you connect to VMs that have OS Login enabled, Compute Engine uses the username 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 of USERNAME_DOMAIN_SUFFIX. For more information about usernames, see How OS Login works.

Expected login behaviors

• When you connect to your VM, you will get a message based on your selected 2-step verification method or challenge type.

  • For Google Authenticator, you will see the following message:

    "Enter your one-time password:"

  • For text message or phone call verification, you will see the following message:

    "A security code has been sent to your phone. Enter code to continue:"

  • For phone prompt, you will see the following message:

    "A login prompt has been sent to your enrolled device:"

  • For security key OTP, you will see the following message:

    "Enter your security code by visiting g.co/sc:"

  For the phone prompt method, accept the prompts on your phone or tablet to continue.

  For other methods, enter your security code or one-time password.

• On some instances using OS Login, you might receive the following error message after the connection is established:

  /usr/bin/id: cannot find name for group ID 123456789

  Ignore this error message. This error does not affect your instances.

• When you log in to an instance by using the gcloud compute ssh command, the login message has the following format for a user user that belongs to the example.com domain:

  Using OS Login user user_example_com instead of default user user

  This message confirms that the user is logging in with an OS Login profile.

• You might see logs similar to the following when you create VMs:

  Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Refreshing group entry cache
  Dec 10 22:31:05 instance-1 google_oslogin_nss_cache[381]: oslogin_cache_refresh[381]: Failure getting groups, quitting
  

  These logs indicate that your organization doesn't have OS Login Linux groups configured. Ignore these messages.

What's next

• Learn more about OS Login.
• Monitor OS Login audit logs.
• Learn how SSH connections to Linux VMs work on Compute Engine.
• Troubleshoot OS Login.