This document covers the basic steps for setting up OS Login.
OS Login lets you use Compute Engine 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.
To configure OS Login and connect to your instances, complete the following steps:
- Install or update the guest environment.
- Optional: If you are an organization administrator, review Managing OS Login in an organization.
- Enable the OS Login feature on your project or on individual instances.
- Grant the necessary IAM roles to yourself, your project members, or your organization members.
- Optional: Add custom SSH keys to user accounts for yourself, your project member, or organization members. If you don't add SSH keys, Compute Engine generates SSH keys for you when you connect to instances.
- Connect to instances.
Before you begin
- If you want to use the command-line examples in this guide:
- Install or update to the latest version of the gcloud command-line tool.
- Set a default region and zone.
- If you want to use the API examples in this guide, set up API access.
- For information about how SSH connections work in Compute Engine, including SSH key configuration and storage, see SSH connections to Linux VMs.
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.
Currently, Fedora CoreOS images do not support OS Login. To manage instance access to VMs created using these images, use the Fedora CoreOS ignition system.
Windows Server and SQL Server images do not support OS Login.
Step 1: Install or update the guest environment
Your VM instance must have the latest version of the guest environment installed. Most public images already have the latest version installed. If you don't have the latest guest environment, update your guest environment.
If you have VMs that run custom images that you imported, install the guest environment on those VMs.
If you don't have the latest guest environment, update your guest environment.
Step 2: (Optional) Review managing OS Login in an organization
If you are organization admin, you can set some configurations such as enabling OS Login at the organization level. See Managing OS Login in an organization.
Step 3: Enabling or disabling OS Login
You can enable or disable OS Login by setting metadata values
at the instance or project level. To set these values, you can use either
the Google Cloud Console or the
gcloud
command-line tool.
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.In the Google Cloud Console, go to the Metadata page.
Click Edit.
Add a metadata entry, setting the key to
enable-oslogin
and the value toTRUE
. Alternatively, set the value toFALSE
to disable the feature.Click Save to apply the changes.
Option 2: Set
enable-oslogin
in the instance metadata of an existing instance.In the Google Cloud Console, go to the VM instances page.
Click the name of the instance that you want to enable OS Login on.
On the instance details page, click Edit.
Under Custom metadata, add a metadata entry, setting the key to
enable-oslogin
and the value toTRUE
. Alternatively, set the value toFALSE
to disable OS Login on the instance.Click Save to apply the changes to the instance.
Option 3: Set
enable-oslogin
in instance metadata when you create an instance.- In the Cloud Console, go to the VM instances page.
- Click Create instance.
- On the Create a new instance page, fill in the properties for your instance.
- In the
Metadata section, add a metadata entry where the key is
enable-oslogin
and the value isTRUE
. Alternatively, set the value toFALSE
to exclude the instance from the feature. - Click Create to create the instance.
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 thegcloud
command-line tool and set a metadata value whereoslogin=TRUE
to enable OS Login:gcloud compute project-info add-metadata \ --metadata enable-oslogin=TRUE
Alternatively, you can set
enable-oslogin
toFALSE
to disable OS Login.Option 2: Set
enable-oslogin
in the metadata of an existing instance.Use the
instances add-metadata
command in thegcloud
command-line tool and setoslogin=TRUE
to enable OS Login. ReplaceVM_NAME
with the name of your VM.gcloud compute instances add-metadata VM_NAME \ --metadata enable-oslogin=TRUE
Alternatively, you can set
enable-oslogin
toFALSE
to exclude your instance from using OS Login.Option 3: Set
enable-oslogin
in instance metadata when you create an instance.Use the
instances create
command in thegcloud
command-line tool and setoslogin=TRUE
to enable OS Login. ReplaceVM_NAME
with the name of your instance.gcloud compute instances create VM_NAME \ --metadata enable-oslogin=TRUE
Alternatively, you can set
enable-oslogin
toFALSE
to exclude your instance from using OS Login.
After you enable OS Login on the instances in your project, grant users permission to connect to those instances.
Step 4: 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 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:
Grant one of the following instance access roles.
roles/compute.osLogin
, which doesn't grant administrator permissionsroles/compute.osAdminLogin
, which grants administrator permissions
You can grant these instance access roles at the instance level by using the
gcloud compute instances add-iam-policy-binding
command.If your VM instance uses a service account, then each user must be configured 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.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. 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:
- If your applications require SSH access to your Compute Engine instances, you can provide that access through a service account. For more information, see Connecting apps to instances using SSH.
- For information about how to manually assume the permissions of a service account and use those permissions to execute commands on a second instance, read Manually connecting between instances as a service account.
You can grant SSH access to your service accounts by using the following process:
- Create a service account.
- 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.
- 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 app if you run your app outside of the Compute Engine environment.
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 5: (Optional) Adding SSH keys to a user account
If you want connect to your VMs by using third-party tools, you need to add
your SSH keys to your user account. If you connect to your instances using
other options, such as the gcloud
command-line tool or SSH from the browser, you can
skip this step because Compute Engine automatically generates SSH
keys for you.
You can associate public SSH keys with the following user account types:
- Managed user accounts that are part of an organization resource:
- 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 Users resource 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
Replace the following:
KEY_FILE_PATH
: 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 thepublic-openssh
format.EXPIRE_TIME
: an optional flag to set an expiration time for the public SSH key. For example, you can specify30m
and the SSH key will expire after 30 minutes. This flag uses the following units:s
for secondsm
for minutesh
for hoursd
for days- 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" }
Replace the following:
ACCOUNT_EMAIL
: the email address that represents your managed user account.SSH_KEY
: The public key that you want to apply to the account. Make sure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use thepublic-openssh
format.EXPIRATION_TIMESTAMP
: 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" } ] }
Replace the following:
USER_ID_KEY
: an immutable ID for the user.SSH_KEY
: a public key that you want to apply to the account. Make sure that the public SSH key is properly formatted. If you use PuTTYgen on Linux systems to generate your public keys, you must use thepublic-openssh
format.EXPIRATION_TIMESTAMP
: the expiration time for a key, in microseconds since epoch.
To remove all keys from an account, specify "sshPublicKeys": null
as the body, replacing USER_ID_KEY with an immutable ID for
the user:
PUT https://www.googleapis.com/admin/directory/v1/users/USER_ID_KEY { "sshPublicKeys": null }
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. Accounts that don't belong to organizations cannot change the default username.
You can find the current username for your account by running the
gcloud compute os-login describe-profile
command.
For example, your output might resemble the following:
name: '314159265358979323846' posixAccounts: - gid: '27182818' homeDirectory: /home/user_example_com ⋮ uid: '27182818' username: user_example_com ⋮
Step 6: Connect to instances
When you connect to a VM, you have three main options:
If you connect to a VM by using either the gcloud
tool or SSH from
the browser, Compute Engine automatically generates SSH keys and
associates them with your user account.
If you connect to an instance by using a third-party tool, you need to add the public keys to your user account. The VM gets your public key from your user account and lets you 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.
Review 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.
Cloud Identity administrators can configure POSIX information and set a username for organization members. If a username is not set by a Cloud Identity administrator, OS Login generates a default Linux username by combining the username and domain from the email address associated with the user's Google profile. This naming convention ensures uniqueness. For example, if the user email associated with the Google profile is
user@example.com
, then their generated username isuser_example_com
.Optionally, Google Workspace organizations can change their default to remove the domain suffix for newly generated usernames. For example, if the user email address associated with the Google profile is
user@example.com
, then their generated username isuser
. For more information, see Managing the OS Login API.If a user is from a separate Google Workspace organization, the generated username is prefixed with 'ext_'. For example, if
user@example.com
is accessing a VM in a different organization, then their generated username isext_user_example_com
.When you log in to an instance by using the
gcloud compute ssh
command, the login message has the following format for a useruser
that belongs to theexample.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.
What's next
- Connect to instances.
- Learn how SSH connections to Linux VMs work on Compute Engine.
- Learn more about Compute Engine access control.
- Read about service accounts.
- Read the Connecting apps to instances using SSH tutorial to see an example app for service account SSH.
- Read about Google Cloud project access.
- Troubleshoot OS Login.