This document covers the basic steps for setting up OS Login with 2-step verification.
If you use OS Login to manage access to your virtual machine (VM) instances, you can add an extra layer of security by using 2-step verification also known as two-factor authentication, or 2FA. To learn more about the other benefits of using OS Login, see OS Login.
To use OS Login 2FA on your VMs, complete the following steps:
Grant the necessary IAM roles to yourself or other principals.
To further restrict VM access, you can set up hardware-backed SSH key pairs. For more information, see SSH with security keys.
After setting up OS Login 2FA, you can use audit logs to monitor your authentication sessions.
Before you begin
- If you want to use the command-line examples in this guide, do the following:
- 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.
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
Supported methods or challenge types
OS Login supports the following 2-step verification methods or challenge types:
- Google Authenticator
- Text message or phone call verification
- Phone prompts
- Security key one-time password (OTP)
Step 1: Enable 2-step verification for your Google Account or domain
Before you can enable OS Login 2FA for your project or VM, you must first enable 2-step verification on your Google Account or domain. Make sure that you either enable 2-step verification on the domain that contains the project or VMs or enable 2-step verification for the user that owns the project or VMs.
As a security best practice, require 2-step verification on user accounts in your organization. Enabling OS Login 2FA doesn't block login access to users who don't have two-factor authentication configured.
A Google Workspace administrator can enable 2-step verification for a domain, or an individual Google user can enable 2-step verification for a user-account.
2-step verification for a domain must be enabled by a Google Workspace administrator.
To enable 2-step verification for a domain, see Protect your business with 2-Step Verification in the Google Workspace Admin guide.
If your user accounts are not managed by a Google Workspace administrator, you can configure 2-step verification for individual Google Accounts.
To configure 2-step verification for an individual Google Account, see Google 2-Step Verification.
Step 2: Enable OS Login 2FA on your project or VM
After you enable 2-step verification for a domain or user account, you can then enable individual VMs or projects to use OS Login 2FA. A VM or project must have OS Login enabled in order to use OS Login 2FA.
You can configure both OS Login and OS Login 2FA during VM creation or project setup. You can also configure OS Login 2FA on an existing VM or project that already has OS Login enabled.
To configure your project or VM to use OS Login two-factor authentication,
enable-oslogin=TRUE in the project or
instance metadata. Enabling OS Login with two-factor authentication in
instance metadata overrides the value that is set in project metadata.
You can apply the metadata values on your projects or VMs using one of the following options:
Option 1: Enable OS Login with two-factor authentication when you create a VM.
- In the Google Cloud console, go to the Create an instance page.
- Expand Networking, disks, security, management, sole tenancy to reveal additional configuration options.
- Expand the Security section.
- Expand the Manage access section.
- Select Control VM access through IAM permissions.
- Select Require 2-step verification.
- To create the VM, click Create.
Option 2: Set
enable-oslogin=TRUEin project-wide metadata so that the setting is applied to all of the VMs in your project.
In the Google Cloud console, go to the Metadata page.
In the Metadata section, add the following metadata entries:
Click Save to apply the changes.
Option 3: Set
enable-oslogin-2fa=TRUEin the metadata of an existing VM.
In the Google Cloud console, go to the VM instances page.
Click the name of the VM on which you want to set the metadata value.
On the Instance details page, click Edit.
Under Custom metadata, add the following metadata entries:
On the Instance details page, click Save to apply your changes to the instance.
You can apply the metadata values on your projects or VMs by using one of the following options:
Option 1: Set
enable-oslogin-2fa=TRUEin instance metadata when you create a VM.
Create a Compute Engine instance. Configure the instance as follows:
INSTANCE_NAMEwith your preferred instance name.
--zoneflag to the zone in which you want to create your instance.
TRUEin instance metadata to enable OS Login with 2-step verification.
gcloud compute instances create INSTANCE_NAME --zone=ZONE --metadata=enable-oslogin=TRUE,enable-oslogin-2fa=TRUE
VM_NAMEwith the name of your VM.
- Create a Compute Engine instance. Configure the instance as follows:
Option 2: Set
enable-oslogin-2fa=TRUEin project-wide metadata, so that it applies to all of the VMs in your project.
gcloud compute project-info add-metadata \ --metadata enable-oslogin=True,enable-oslogin-2fa=True
Option 3: Set
enable-oslogin-2fa=TRUEin metadata of an existing VM.
gcloud compute instances add-metadata \ --metadata enable-oslogin=True,enable-oslogin-2fa=True VM_NAME
VM_NAMEwith the name of your VM.
Step 3: 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:
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 Google Cloud 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
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.serviceAccountUserrole 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.osLoginExternalUserrole, 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:
- 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:
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 4: 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
For more information about usernames, see
How OS Login works.
Expected login behaviors
When you connect to your VM, you will get a message based on your selected 2-step verification method or challenge type.
For Google Authenticator, you will see the following message:
"Enter your one-time password:"
For text message or phone call verification, you will see the following message:
"A security code has been sent to your phone. Enter code to continue:"
For phone prompt, you will see the following message:
"A login prompt has been sent to your enrolled device:"
For security key OTP, you will see the following message:
"Enter your security code by visiting g.co/sc:"
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.
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 sshcommand, the login message has the following format for a user
userthat belongs to the
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: oslogin_cache_refresh: Refreshing group entry cache Dec 10 22:31:05 instance-1 google_oslogin_nss_cache: oslogin_cache_refresh: Failure getting groups, quitting
These logs indicate that your organization doesn't have OS Login Linux groups configured. Ignore these messages.
- Learn more about OS Login.
- Monitor OS Login audit logs.
- Learn how SSH connections to Linux VMs work on Compute Engine.
- Troubleshoot OS Login.