Set up OS Login

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, see About OS Login.

Before you begin

  • If you want to use OS Login 2FA, enable 2FA on your domain or account:
  • If you haven't already, then set up authentication. Authentication is the process by which your identity is verified 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, then initialize it by running the following command: 

      gcloud init
    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.

    1. Install the Google Cloud CLI.

    2. To initialize the gcloud CLI, run the following command: 

      gcloud init

    3. 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.

    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

Assign OS Login IAM roles

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

Role Required users Grant level
roles/compute.osLogin or roles/compute.osAdminLogin All users

On the Project or instance.

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 the compute.projects.get permission.
roles/iam.serviceAccountUser All users, if the VM has a service account On the Service account.
roles/compute.osLoginExternalUser Users from a different organization than the VM they're connecting to

On the Organization.

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 single VM, or all VMs in a project, by setting OS Login metadata.

When you set OS Login metadata, Compute Engine deletes the VM's authorized_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 in project 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 in instance 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 by creating a VM from a public image and 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, select Require 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, a Cloud 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 following gcloud 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, see Operating 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 the google_compute_project_metadata Terraform resource and set a metadata value where oslogin=TRUE:

    resource "google_compute_project_metadata" "default" {
  metadata = {
    enable-oslogin = "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 the google_compute_instance Terraform resource and set oslogin=TRUE. Replace oslogin_instance_name with the name of your VM.

    resource "google_compute_instance" "oslogin_instance" {
  name         = "oslogin-instance-name"
  machine_type = "f1-micro"
  zone         = "us-central1-c"
  metadata = {
    enable-oslogin : "TRUE"
  }
  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }
  network_interface {
    # A default network is created for all GCP projects
    network = "default"
    access_config {
    }
  }
}

    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 in Connect to Linux 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.

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, see Troubleshooting OS Login.

What's next