Setting up OS Login with two-factor authentication

If you use OS Login to manage access to your instances, you can add an extra layer of security by using two-factor authentication, also known as 2FA.

To use OS Login with 2FA authentication on your instances, complete the following steps:

1. Enable 2FA for your Google account or domain.
2. Enable 2FA on your project or instance.
3. Grant the necessary IAM roles to yourself, your project members, or your organization members.
4. [Optional] If your project is part of an organization, review Managing OS Login in an organization.
5. Connect to instances.
6. Review the expected login behaviors.

After setting up OS Login with 2FA, you can use audit logs to monitor your authentication sessions.

Note: If your project is part of an organization, you can grant instance access to users who are outside of your organization by using roles/compute.osLoginExternalUser, or by using custom role with the compute.oslogin.updateExternalUser permission. For more details, see Granting instance access to users outside of your organization .

Before you begin

• If you want to use the command-line examples in this guide:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.

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 images do not support OS Login.

Supported operating systems

OS Login two-factor authentication require operating system images created after the following dates:

Operating System	Dates
CentOS 6 and 7	March 26, 2019
Debian 9	March 26, 2019
RHEL 6 and 7	March 26, 2019
SUSE 12 and 15	June 17, 2019
Ubuntu 16.04 LTS, 18.04 LTS, 18.10, and 19.04	June 28, 2019

Supported methods or challenge types

OS Login supports the following 2FA methods or challenge types:

• Google Authenticator
• Text message or phone call verification
• Phone prompts

Enabling 2FA for your Google Account or domain

Before you can enable two-factor authentication for your project or instance, you must first enable 2FA on your Google Account or domain. Ensure that you enable 2FA on the domain that contains the project or instances, or for the user that owns the project or instances.

A G Suite administrator can enable two-factor authentication for a domain or an individual Google user can enable two-factor authentication at the user account level.

Domain

Two-factor authentication for a domain must be enabled by a G Suite administrator.

To enable 2FA for a domain, see Protect your business with 2-Step Verification in the G Suite Admin guide.

User account

If your user accounts are not managed by a G Suite administrator, you can configure 2FA for individual Google Accounts.

To configure 2FA for an individual Google Account, see Google 2-Step Verification.

Enabling 2FA on your project or instance

After you enable two-factor authentication at the domain or user account level, you can then enable individual instances or project to use OS Login 2FA.

An instance 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 instance creation or project set up. You can also configure OS Login 2FA on an existing instance or project that already has OS Login enabled.

To configure your project or instance to use OS Login two-factor authentication, set "enable-oslogin-2fa=TRUE" in the project or instance metadata.

Console

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

1. In the Google Cloud 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 desired properties for your instance.

4. In the Metadata section, add the following metadata entries:

   • enable-oslogin and the value is TRUE.
   • enable-oslogin-2fa and the value is TRUE.

5. Click Create to create the instance.

Set enable-oslogin-2fa 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-2fa 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-2fa 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-2fa and the value is TRUE. Alternatively, set the value to FALSE to exclude the instance from the feature. You should also verify that enable-oslogin is set to True.
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.

gcloud

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

gcloud compute instances create [INSTANCE_NAME] \
  --metadata enable-oslogin=True,enable-oslogin-2fa=True

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

gcloud compute project-info add-metadata \
  --metadata enable-oslogin=True,enable-oslogin-2fa=True

Set enable-oslogin-2fa in metadata of an existing instance:

gcloud compute instances add-metadata \
  --metadata enable-oslogin=True,enable-oslogin-2fa=True [INSTANCE_NAME]

where [INSTANCE_NAME] is the name of the instance.

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 that have the necessary IAM roles in your project or organization:

For example, you might grant instance access to 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

     You can grant either of these roles at the instance level by 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, the 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. For more information, see Connecting apps to instances using SSH.
• For information about how 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 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:
   • 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. Read the Connecting applications to instances using SSH tutorial to see an example app 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. 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 associated with their account, but those keys no longer function on the VM 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.

Connecting 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.

When you connect to your instance, you will get a message based on your selected 2FA 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 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.

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.

Viewing OS Login 2FA audit logs

Compute Engine provides audit logs to track two-factor authentication requests. Two-factor authentication has two request types:

• StartSession. Starts a new authentication session. In a StartSession call, a client declares its capabilities to the server and obtains information about the first challenge. A StartSession call returns the following:

  • A session ID. this session ID is passed to all subsequent ContinueSession calls.
  • Information about the challenge or 2FA method used in this new authentication session.

• ContinueSession. Continues an existing authentication session. By using the provided session ID, the ContinueSession API can perform one of the following two actions:

  • Accept the response to a challenge or method and then either authenticate, reject, or require additional challenges from the user.
  • Switch to a different type of challenge than the one initially proposed by the server on the previous round of API calls. If a client chooses to complete a different challenge type (for example, Google Authenticator instead of phone prompt), the client can request a different challenge type in a call to the server by using a request.challengeId of the desired type.

To view logs, you must have permissions for the Logs Viewer or be a project viewer or editor.

1. Go to the Logs page in the Cloud Console.

   Go to the Logs page

2. Expand the drop-down menu and select Audited Resource.
3. In the search bar, type oslogin.googleapis.com and hit Enter.

4. A list of audit logs describing the two-factor authentication requests displays. Expand any of the entries to get more information:

   

For any of the audit logs, you can:

1. Expand the protoPayload property.

   

2. Look for methodName to see activity this log applies to (either a StartSession or ContinueSession request). For example, if this log tracks a StartSession request, the method name would say "google.cloud.oslogin.OsLoginService.v1.StartSession". Similarly, a ContinueSession log would say "google.cloud.oslogin.OsLoginService.v1.ContinueSession". An audit log entry is recorded for every start and continue session requests.

There are different audit log properties for different log types. For example, audit logs relating to StartSession have properties that are specific to starting sessions, while audit logs for ContinueSession have their own set of properties. There are certain audit log properties that are also shared between both log types.

All two-factor authentication audit logs

Property	Value
serviceName	oslogin.googleapis.com
resourceName	A string containing the project number. This project number indicates which login request the audit log belongs to. For example, projects/myproject12345.
severity	The severity level of the log message. For example, INFO or WARNING.
request.email	The email address of the user that the API call is authenticating.
request.numericProjectId	The project number of the Google Cloud project.
response.@type	type.googleapis.com/google.cloud.oslogin.OsLoginService.v1.StartOrContinueSessionResponse
response.sessionId	An ID string uniquely identifying the session. This session ID is passed to the next API call in the sequence.
response.authenticationStatus	Status of the session. For example, Authenticated, Challenge required or Challenge pending.
response.challenges	The set of challenges that you can attempt to pass this round of authentication. At most one of these challenges is started and has a status of READY. The others are provided as options that the user can specify as an alternative to the proposed primary challenge.

StartSession audit logs

Property	Value
methodName	google.cloud.oslogin.OsLoginService.v1.StartSession
request.@type	type.googleapis.com/google.cloud.oslogin.OsLoginService.v1.StartSessionRequest
request.supportedChallengeTypes	The list of challenge types or 2FA methods that you can choose from.

ContinueSession audit logs

Property	Value
methodName	google.cloud.oslogin.OsLoginService.v1.ContinueSession
request.sessionId	An ID string uniquely identifying the previous session. This session ID is passed from the previous API call in the sequence.
request.@type	type.googleapis.com/google.cloud.oslogin.OsLoginService.v1.ContinueSessionRequest
request.challengeId	An ID string identifying which challenge to start or execute. This ID must belong to a challenge type returned from the response.challenges call in a previous API response.
request.action	The action to take.

What's next

• Learn more about OS Login.