Set up OS Login

This document covers how to set up OS Login.

OS Login lets you use Compute Engine Identity and Access Management (IAM) roles to grant or revoke SSH access to your Linux instances. OS Login is an alternative to managing instance access by adding and removing SSH keys in metadata. To learn more about the benefits of using this feature, see OS Login.

If you want to enable OS Login with a layer of security by using two-factor authentication, see Setting up OS Login with 2-step verification. To review all the options for managing access to your VMs, see Choosing an access method.

Before you begin

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

Step 1: Enable or disable OS Login

You can enable or disable OS Login by setting metadata values at the instance or project level. Enabling or disabling OS Login in instance metadata overrides the value that is set in project metadata. To set OS Login values, you can use either the Google Cloud console or the Google Cloud CLI.

Console

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 instances in your project.

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

      Go to Metadata

    2. Click Edit.

    3. Add a metadata entry, setting the key to enable-oslogin and the value to TRUE. Alternatively, set the value to FALSE to disable the feature.

    4. Click Save to apply the changes.

  • Option 2: Set enable-oslogin in the instance metadata of an existing instance.

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

      Go to VM instances

    2. Click the name of the instance that you want to enable OS Login on.

    3. On the instance details page, click Edit.

    4. Under Custom metadata, add a metadata entry, setting the key to enable-oslogin and the value to TRUE. Alternatively, set the value to FALSE to disable OS Login on the instance.

    5. Click Save to apply the changes to the instance.

  • Option 3: Enable OS Login when you create an instance.

    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. To create the VM, click Create.

gcloud

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

  • Option 1: Set enable-oslogin in project-wide metadata so that it applies to all of the instances in your project.

    Use the project-info add-metadata command in the Google Cloud CLI and set a metadata value where oslogin=TRUE to enable OS Login:

    gcloud compute project-info add-metadata \
        --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 an existing instance.

    Use the instances add-metadata command in the Google Cloud CLI and set oslogin=TRUE to enable OS Login. Replace VM_NAME with the name of your VM.

    gcloud compute instances add-metadata VM_NAME \
        --metadata enable-oslogin=TRUE
    

    Alternatively, you can set enable-oslogin to FALSE to exclude your instance from using OS Login.

  • Option 3: Set enable-oslogin in instance metadata when you create an instance.

    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 to TRUE in instance metadata to enable OS Login.
      gcloud compute instances create INSTANCE_NAME --zone=ZONE --metadata=enable-oslogin=TRUE

After you enable OS Login on the instances in your project, grant users permission to connect to those instances.

Step 2: 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.

  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:

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:

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.

Step 3: 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

  • 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