Setting up and configuring OS Login

OS Login allows you to use Compute Engine IAM roles to manage SSH access to Linux instances and is an alternative to manually managing instance access by adding and removing SSH keys in metadata.

To configure OS Login and connect to your instances, use 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, complete any of the following steps:
   • Set up two-factor authentication.
   • 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.
   • Modify user accounts using the Directory API.
   • Grant instance access to users outside of your organization.
4. Connect to instances.
5. Review the expected login behaviors.

Note: If your project is part of an organization, you can grant instance access to users who are outside of your organization by granting roles/compute.osLoginExternalUser, or a custom role with the compute.oslogin.updateExternalUser permission, to those users at the organization level.

Limitations

• OS Login is not currently supported in Google Kubernetes Engine (GKE). GKE cluster nodes continue to use metadata SSH keys when OS Login is enabled.

• Windows Server and SQL Server image families do not yet support OS Login.

Enabling or disabling OS Login

Before you can manage instance access using IAM roles, you must enable the OS Login feature by setting a metadata key/value pair in your project or in your instance's metadata: enable-oslogin=TRUE. 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 can't use it yet.

Caution: Enabling OS Login on instances disables metadata-based SSH key configurations on those instances. Disabling OS Login restores SSH keys that you have configured in project or instance metadata.

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.

   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.

For VMs that are not running CoreOS, this change is applied instantaneously; you do not need to restart your instance. For CoreOS distributions, reboot or restart the instance for the change to take effect. To restart, perform a stop and then start operation on your instances.

Set enable-oslogin in metadata of an existing instance:

1. Go to the VM instances page.

   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.

For all operating systems except CoreOS, this change is applied instantaneously; you do not need to restart your instance. For CoreOS distributions, reboot or restart the instance for the change to take effect. To restart, perform a stop and then start operation on your instances.

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 Create instance.
3. On the Create a new instance page, fill in the 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 Create 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.

For VMs that are not running CoreOS, this change is applied instantaneously; you do not need to restart your instance. For CoreOS distributions, reboot or restart the instance for the change to take effect.

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.

For all operating systems except CoreOS, this change is applied instantaneously; you do not need to restart your instance. For CoreOS distributions, reboot or restart the instance for the change to take effect.

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 guest environment installed. If you have instances that run custom images that you imported, install the 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 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 instances accept connections only from user accounts who have the necessary IAM roles in your project or organization:

As an example, you might grant instance access to your users with the following process:

1. Grant the necessary instance access roles to the user. Users must have the following roles:

   • roles/iam.serviceAccountUser.

   • One of the following login roles:

     • roles/compute.osLogin, which does not grant administrator permissions
     • roles/compute.osAdminLogin, which grants administrator permissions

     Either of these roles can be granted at the instance level using the gcloud beta compute instances add-iam-policy-binding command.

2. If you are an organization admin who wants to allow members outside of your organization to access your instances, grant roles/compute.osLoginExternalUser to that user at the organization level.

Users cannot view details about your instances or the external IP addresses for those instances unless you provide those details directly to them. To allow users to view the details of your instances, they require additional IAM roles. For example, roles/compute.viewer role allows users to view all of the resources in your project, including instance details.

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:

• If your applications require SSH access to your Compute Engine instances, you can provide that access through a service account. Read the Connecting Applications to Instances Using SSH tutorial to learn more.
• If you want to assume the permissions of a service account and use them to chain-SSH between instances manually, read Manually Connecting Between Instances as a Service Account.

You can grant SSH access to your service accounts 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. Read Granting Roles to Service Accounts to learn how to configure roles and permissions for 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:
   • Create an instance that is associated with your service account. The instance provides Application Default Credentials to your service account.
   • Manually provide service account credentials to your application if you run your application outside of the Compute Engine environment.

After you grant SSH access to your service accounts, you can configure your applications to create SSH keys and establish SSH connections to other instances on your VPC networks. Read the Connecting applications to instances using SSH tutorial to see an example application for service account SSH.

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. The user still has public SSH keys associated with their account, but those keys no longer function on your instances.

Note: Users with active SSH connections are not disconnected and retain their sudo privileges until the next time they establish an SSH connection. Compute Engine determines a user's authentication, authorization, and sudo privileges only when a user establishes a connection to an instance.

Connect to 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 the public keys to your user account, you can connect to instances using third-party tools. The instance obtains your public key from your user account and allows you to connect to the instance if you provide the correct user name and matching private SSH key.

After you connect to your instance, review the expected login behaviors.

Granting instance access to users outside of your organization

By default, users outside of your organization cannot set SSH keys for instances in your organization or be granted access to instances in your organization. In some situations, you might need to grant instance access to users who are part of a different organization or who have a consumer Google gmail.com account.

The roles/compute.osLoginExternalUser IAM role allows external Google accounts to interact with the other OS Login roles by allowing them to configure POSIX account information.

Grant roles/compute.osLoginExternalUser and other necessary OS Login instance access roles to users outside of your organization:

1. Go to the project and organization selection page.

   Go to the project and organization selection page

2. In the Organization drop down menu, select your organization.
3. Click All, to view all of your organizations.
4. Click the name of the organization.
5. Click Add to add a new role to a user.
6. Specify the user name for the user for whom you want to configure instance access.
7. Click Select a role to specify which roles you want to grant to the users.
8. Select the Compute OS Login External User role, which is part of the Compute Engine roles list.
9. Click Add to confirm that you want to grant the selected role to the user.
10. If you have not already done so, grant the other OS Login instance access roles to the user at the project or organization level.

The user can now connect to instances in your project that have OS Login enabled.

Adding SSH keys to a user account

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

• Managed user accounts that are part of an organization resource:
  • G Suite
  • Cloud Identity
• Consumer Google accounts, such as gmail.com accounts

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 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. Ensure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use the public-openssh format.
• [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. Ensure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use the public-openssh format.
• [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. Ensure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use the public-openssh format.
• [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 60000, or a value between 65535 and 2147483647. To access a Container-Optimized OS, the UID must have value between 65536 and 214748646. 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.

Note: Do not update the systemID property. The systemID property must be left blank.

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

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.

• If a username is not set by a G Suite administrator, OS Login generates a default Linux username by combining the username and domain from the email associated with the user's Google profile. This naming convention ensures uniqueness. For example, if the user email associated with the Google profile is [e-mail], then their generated username is user_example_com.

  This generated username is based on domains associated with a G Suite account. If a user is from a separate G Suite organization, the generated username is prefixed with 'ext_'. For example, if [e-mail] is accessing a VM in a different organization, then their generated username is ext_user_example_com.

• When you log in to an instance by using the gcloud compute ssh command, the following message displays:

  Using OS Login user [user_example_com] instead of default user [user]

  This message confirms that you are logging in with your OS Login profile.

What's next

• Connect to instances.
• Learn more about Compute Engine access control.
• Read about service accounts.
• Read the Connecting to Instances as a Service Account tutorial to see an example application for service account SSH.
• Read about GCP project access