Managing Instance Access Using OS Login

You can use Compute Engine IAM roles to manage SSH access to instances. This new feature gives you more granular control over which users can connect to your instances, what instances they are allowed to access, and what level of permission they have.

Alternatively, you can manage instance access manually by adding and removing SSH keys in metadata.

Configure role-based instance access using the following process:

  1. Enable the OS Login feature on your project or on individual instances.
  2. Grant the necessary IAM roles to yourself, your project members, or your organization members.
  3. Optionally, add custom SSH keys to user accounts for yourself, your project member, or organization members. Alternatively, Compute Engine can automatically generate these keys for you when you Connect to instances.

Enabling or disabling OS Login

Before you can manage instance access using IAM roles, you must enable the OS Login feature by setting the enable-oslogin metadata value to TRUE in either project or instance metadata. To disable OS Login, set the metadata value to FALSE. For example, you might enable the feature across your entire project using enable-oslogin=TRUE at the project level, but set enable-oslogin=FALSE on specific instances that cannot use it yet.

You can apply the enable-oslogin metadata value on your projects or instances using one of the following options:

Console

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

  1. Go to the Metadata page.
  2. Click Edit.
  3. Add a metadata entry where the key is enable-oslogin and the value is TRUE. Alternatively, set the value to FALSE to disable the feature.
  4. Click Save to apply the changes.

Set enable-oslogin in metadata of an existing instance:

  1. Go to the VM instances page.
  2. Click the name of the instance on which you want to set the metadata value.
  3. At the top of the instance details page, click Edit to edit the instance settings.
  4. Under Custom metadata, add a metadata entry where the key is enable-oslogin and the value is TRUE. Alternatively, set the value to FALSE to exclude the instance from the feature.
  5. At the bottom of the instance details page, click Save to apply your changes to the instance.

Set enable-oslogin in instance metadata when you create an instance:

  1. In the GCP Console, go to the VM Instances page.

    Go to the VM Instances page

  2. Click the Create button.
  3. On the Create a new instance page, fill in the desired properties for your instance.
  4. In the Metadata section, add a metadata entry where the key is enable-oslogin and the value is TRUE. Alternatively, set the value to FALSE to exclude the instance from the feature.
  5. Click the Create button to create the instance.

gcloud

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 gcloud command-line tool and set 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.

Set enable-oslogin in metadata of an existing instance:

Use the instances add-metadata command in the gcloud command-line tool and set oslogin=TRUE to enable OS Login:

gcloud compute instances add-metadata [INSTANCE_NAME] --metadata enable-oslogin=TRUE

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

Set enable-oslogin in instance metadata when you create an instance:

Use the instances create command in the gcloud command-line tool and set oslogin=TRUE to enable OS Login:

gcloud compute instances create [INSTANCE_NAME] --metadata enable-oslogin=TRUE

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

In addition to the required metadata values, your instance must have the latest version of the Linux Guest Environment installed. The following image families do not yet support OS Login:

  • Project cos-cloud (Container-Optimized OS) image families cos-stable and cos-beta
  • All project coreos-cloud (CoreOS) image families
  • Project suse-cloud (SLES) image family sles-11
  • All Windows Server and SQL Server image families

If you have instances that run custom images that you imported, install the Linux Guest Environment on those instances to enable OS Login.

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

Configuring IAM roles on user accounts

Instances enabled for OS Login will accept connections only from user accounts that have the following roles in your project or organization:

  • The iam.serviceAccountUser role.
  • One of the following login roles:
    • The compute.osLogin role, which does not grant administrator permissions
    • The compute.osAdminLogin role, which grants administrator permissions

Alternatively, OS Login accepts connections from user accounts that have the Owner or Editor legacy roles, and also grants administrator permissions to those users.

Grant an instance access role to the project member that requires access to the instances. If you cannot grant this role to yourself or another project member, ask a project admin to grant the role for you. To revoke user access to instances that are enabled to use OS Login, remove the user roles from that user account. The user still has public SSH keys associated with their account, but those keys no longer function on your instances.

After you configure the necessary roles, connect to an instance using Compute Engine tools. Compute Engine automatically generates SSH keys and associates them with your user account.

Alternatively, if you create your own SSH keys and add those keys to your user account, you can connect to instances using third-party tools. The instance obtains your private key from your user account and allows you to connect to the instance if you provide the correct user name and private SSH key.

Adding SSH keys to a user account

You can associate public SSH keys with the following user account types:

You can use the gcloud command-line tool, or the OS Login API to add SSH keys to your own account. Alternatively, if you are a domain admin for an organization, you can use the Directory API, to add SSH keys to the user account in your organization.

gcloud

The gcloud compute os-login commands are available only on Google Cloud SDK version 184 and later.

Use the gcloud command-line tool to associate public SSH keys with an account.

gcloud compute os-login ssh-keys add \
    --key-file [KEY_FILE_PATH] \
    --ttl [EXPIRE_TIME]

where:

  • [KEY_FILE_PATH] is the path to the public SSH key on your local workstation.
  • [EXPIRE_TIME] is an optional flag to set an expiration time for the public SSH key. For example, you can specify 30m and the SSH key will expire after 30 minutes. Valid units for this flag are s for seconds, m for minutes, h for hours, or d for days. You can set the value to 0 to indicate no expiration time.

OS Login API

Use the OS Login API to associate public SSH keys with an account.

POST https://oslogin.googleapis.com/v1/users/[ACCOUNT_EMAIL]:importSshPublicKey

{
 "key": "[SSH_KEY]",
 "expirationTimeUsec": "[EXPIRATION_TIMESTAMP]"
}

where:

  • [ACCOUNT_EMAIL] is the email address that represents your managed user account.
  • [SSH_KEY] is the public key that you want to apply to the account.
  • [EXPIRATION_TIMESTAMP] is the expiration time for the key in microseconds since epoch.

Directory API

If you are a domain admin for an organization, you can use the Directory API Reference, to add SSH keys to the account of another user in your organization. For example, create a PUT request to the directory.users.update method with one or more SSH sshPublicKeys entries.

PUT https://www.googleapis.com/admin/directory/v1/users/[USER_ID_KEY]

{
 "sshPublicKeys": [
  {
   "key": "[SSH_KEY]",
   "expirationTimeUsec": "[EXPIRATION_TIMESTAMP]"
  },
  {
   "key": "[SSH_KEY]",
   "expirationTimeUsec": "[EXPIRATION_TIMESTAMP]"
  }
 ]
}

where:

  • [USER_ID_KEY] is an immutable ID for the user.
  • [SSH_KEY] is a public key that you want to apply to the account.
  • [EXPIRATION_TIMESTAMP] is the expiration time for a key in microseconds since epoch.

To remove all keys from an account, specify "sshPublicKeys": null as the body:

PUT https://www.googleapis.com/admin/directory/v1/users/[USER_ID_KEY]

{
  "sshPublicKeys": null
}

where [USER_ID_KEY] is an immutable ID for the user.

After you add your keys to your account, you can connect to instances using third-party tools and the username associated with your account. Your organization admin can change this username. You can find the username for your account by running the gcloud compute os-login describe-profile command:

gcloud compute os-login describe-profile

name: [ACCOUNT_EMAIL]
posixAccounts:
⋮
  username: [USER_NAME]
⋮

where:

  • [ACCOUNT_EMAIL] is the email address that represents your managed user account.
  • [USER_NAME] is the username for establishing SSH connections. By default, this is generated from your [ACCOUNT_EMAIL].

Modifying user accounts using the Directory API

If you are an organization admin, you can modify instance login settings for user accounts as well as many other user properties. To learn how to make a user an administrator, read the Directory API guide. You can use this API to add and remove a user's SSH keys, modify POSIX account information, and change the username that the users connects to on the instance.

For example, create a PUT request to the directory.users.update method and specify one or more properties to change on the user account:

PUT https://www.googleapis.com/admin/directory/v1/users/[USER_ID_KEY]

{
 "posixAccounts": [
   {
    "username": "[USER_NAME]",
    "uid": "[UID]",
    "gid": "[GID]",
    "homeDirectory": "[USER_HOME_PATH]",
    "shell": "[SHELL_PATH]"
   }
  ],
}

where:

  • [USER_ID_KEY] is an immutable ID for the user.
  • [USER_NAME] is the username that Compute Engine adds to the instance for the user. This value must be unique within your organization.
  • [UID] is the user ID on the instance for this user. This property must be a value between 1001 and 65000, or a value between 65535 and 2147483647. The UID must be unique within your organization.
  • [GID] is the group ID on the instance that this user belongs to.
  • [USER_HOME_PATH] is the home directory on the instance for this user. For example, /home/example_username.
  • [SHELL_PATH] is the path to the default shell for the user after they connect to the instance. For example, /bin/bash or /bin/sh.

To learn about all of the account properties that you can edit, see the Directory API Reference.

Expected login messages

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 the error message.

What's next

Send feedback about...

Compute Engine Documentation