Set up OS Login (original) (raw)

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

OS Login enables you to control access to virtual machine (VM) instances based on IAM permissions. You can use OS Login with or without 2FA, but you can't use 2FA without using OS Login. To learn more about OS Login and OS Login 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 up authentication. 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:
   gcloud init
   If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
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.
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
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 these images, use the Fedora 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 OS Login enabled.

Enable OS Login

You can enable OS Login or OS Login with two-factor authentication for a single VM, 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 are stored in project or instance metadata.

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 using the Google Cloud console or the gcloud CLI.

Console

Create a VM that enable OS Login and (optionally) OS Login 2FA on startup bycreating a VM from a public imageand specifying the following configurations:

1. Expand the Advanced options section.
2. Expand the Security section.
3. Expand the Manage access section.
4. Select Control VM access through IAM permissions.
5. Optional: If you want to enable OS Login 2FA, selectRequire two-step verification.
6. Click Create to create and start the VM.

gcloud

1. In the Google Cloud console, activate Cloud Shell.
   Activate Cloud Shell
   At the bottom of the Google Cloud console, aCloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
2. Create a VM that enable OS Login and (optionally) OS Login 2FA on startup by running one of the followinggcloud compute instance create commands:
   • To enable OS Login only, run the following command:
     gcloud compute instances create VM_NAME \
     --image-family=IMAGE_FAMILY \
     --image-project=IMAGE_PROJECT \
     --metadata enable-oslogin=TRUE
   • To enable OS Login 2FA, run the following command:
     gcloud compute instances create VM_NAME \
     --image-family=IMAGE_FAMILY \
     --image-project=IMAGE_PROJECT \
     --metadata enable-oslogin=TRUE,enable-oslogin-2fa=TRUE
     Replace the following:
   • VM_NAME: the name of the new VM.
   • IMAGE_FAMILY: the image family of a Linux OS. This creates the VM from the most recent non-deprecated OS image. For all public image families, seeOperating system details.
   • IMAGE_PROJECT: the image project that contains the image family. Each OS has its own image project. For all public image projects, see Operating system details.

Terraform

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

• Option 1: Set enable-oslogin in project-wide metadata so that it applies to all of the VMs in your project.
  Use thegoogle_compute_project_metadata Terraform resource and set a metadata value whereoslogin=TRUE:
  Alternatively, you can set enable-oslogin to FALSE to disable OS Login.
• Option 2: Set enable-oslogin in the metadata of a new or an existing VM.
  Use thegoogle_compute_instance Terraform resource and set oslogin=TRUE. Replaceoslogin_instance_name with the name of your VM.
  Alternatively, you can set enable-oslogin to FALSE to exclude your VM from using OS Login.

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 of USERNAME_DOMAIN_SUFFIX. For more information about usernames, see How OS Login works.

When you connect to VMs that have OS Login 2FA enabled, you also see a message based on your selected 2-step verification method or challenge type. 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.

Troubleshoot OS Login

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

What's next

• Learn how SSH connections to Linux VMs work on Compute Engine.
• Learn how to useSSH certificates (Preview) to connect to VMs.
• Learn how to useSSH with security keys (Preview) to further restrict access to VMs.