Set up OS Login

This document describes how to set up OS Login.

OS Login lets you control access to virtual machine (VM) instances based on IAM permissions. To learn more about OS Login, see About OS Login.

Before you begin

  • 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.
  • SLES-16 VMs. To manage instance access to VMs created by using these images, use the Metadata-based SSH.

To verify OS Login support for specific Linux distributions, see Operating system details.

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 for a single VM, or all VMs in a project, by setting enable-oslogin to TRUE in project or instance 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 value in project metadata:

  • Key: enable-oslogin
  • Value: TRUE

Enable OS Login for a single VM

To enable OS Login for a single VM, set the following value in instance metadata:

  • Key: enable-oslogin
  • Value: TRUE

Enable OS Login during VM creation

Enable OS Login while creating a VM using the Google Cloud console or the gcloud CLI.

Console

Create a VM that enables OS Login 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. 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 enables OS Login on startup by running the following gcloud compute instance create command:

    gcloud compute instances create VM_NAME \
   --image-family=IMAGE_FAMILY \
   --image-project=IMAGE_PROJECT \
   --metadata enable-oslogin=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.

Enable OS Login with 2FA

For additional security, you can require users to use two-factor authentication (2FA) when connecting to VMs that have OS Login enabled. If you plan to use OS Login with two-factor authentication, users must configure 2-Step Verification on their accounts. For information about supported 2FA methods, see About OS Login.

Before you enable 2FA, ensure that OS Login is enabled as described in Enable OS Login. To enable OS Login 2FA, set the following metadata value in instance or project metadata:

  • Key: enable-oslogin-2fa
  • Value: TRUE

For OS Login 2FA to be enforced, metadata for both OS Login (enable-oslogin) and OS Login 2FA (enable-oslogin-2fa) must be set to TRUE.

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